Cchost/Developers

From Creative Commons
Revision as of 13:41, 15 November 2008 by Fourstones (talk | contribs) (Useful Reading)
Jump to: navigation, search


Docs Home Install Upgrade Troubleshoot Customize Admins Devs Content Query Templates Commands Skins


Source Code

The source for ccHost has moved from SourceForge. For existing clients: you must perform the svn 'relocate' command to switch over. To do this, change directory to the root of your ccHost svn project, then perform the following command:

 svn switch --relocate https://cctools.svn.sourceforge.net/svnroot/cctools http://code.creativecommons.org/svnroot

When to make changes to ccHost core

Never.

Seriously

Never.

But I have changes to share

Oh, that's different. Definitely submit a patch! But before going too far down this road you definitely want to hop on the dev mailing list. If you are shy ask to speak with Victor or Jon in private.


Bugs and Feature Requests

Make sure to use the 'ccHost' category when filing bugs. Also, please use a real email so that we can followup on any bugs posted. Be descriptive when posting and commenting on bugs (every bit counts).

Coding in ccHost

ccHost's Model for a 'Module'

There is no formalized higher level model for a 'module' or 'plugin' in ccHost. The model is the same as PHP: a source file. All files with a .PHP extension that reside in the <local_files>/lib directory will be parsed and executed for every page request to a ccHost installation. Where <local_files> is the name of the directory the administrator specified during installation as to where site customizations reside (also editable from admin/paths)

Because of the automatic loading you should be aware of some performance and timing considerations.

Keep Per Page Execution at a Minimum

You should have no significant code that executes outside of functions. You module will be loaded on each every page (and AJAX) request so (other than registering for ccHost events) you should keep all your code in functions that get called in response to ccHost events.

 <?
    for( $i = 0; $i < 52; $i++ ) { $deck[] = rand() % 52; } // this is bad
 ?>

Instead of the above, you would do:

  <?
    function start_my_shuffle()
    {
      global $deck;

      for( $i = 0; $i < 52; $i++ ) { $deck[] = rand() % 52; }
    }

    // no we only do the shuffle once after ever upload
    CCEvents::AddHandler( CC_EVENT_UPLOAD_DONE, 'start_my_shuffle' );
 ?>

Wait for Initialization

It is rare that you will want to do anything before the environment is fully initialized and we know who the currently logged in user really is.

If you really need to do some calculation on each page hit, register for the 'APP_INIT' event and perform it then:

 <?

   CCEvents::AddHandler( CC_EVENT_APP_INIT, 'my_app_init_func' );

   function my_app_init_func()
   {
      global $CC_GLOBALS;

      if( CCUser::IsLoggedIn() )
      {
           $CC_GLOBALS['welcome-message'] = 'Hello ' . CCUser::CurrentUserName() . '!';
      }
   }

 ?>

Keep Per Page Code Size at a Minimum

If you plan on having a lot of extensibility code it would be wise for performance reasons to consider what has to go into the .PHP files and what can be put into other files (e.g. '.inc') and loaded on demand.

The typical way to handle this is to put the event registrations in the PHP module and the code in a INC file. You can specify a script module in the third parameter of AddHandler. Assuming this file is <local_files>/lib/my_event_hooks.php

 <?
    CCEvents::AddHandler( CC_EVENT_APP_INIT, 'my_app_init_func', dir(__FILE__) . '/my_code.inc' );
 ?>

Then you create <local_files>/lib/my_code.inc:

 <?

   function my_app_init_func()
   {
      global $CC_GLOBALS;

      if( CCUser::IsLoggedIn() )
      {
           $CC_GLOBALS['my-welcome-message'] = 'Hello ' . CCUser::CurrentUserName() . '!';
      }
   }

 ?>

Useful Reading

These pages have important developer information and code samples:


These pages are developer specific: