External APIs

APIs

Source Code

• Browsable Source Code (Anonymous)

• • Specifically for ccHost:
    • Log in as administrator on your ccHost installation
    • Then do your svn update
    • Browse to http://your_installation?update=1

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

• Report Bugs
• Request Features

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:

• Customize <--- Always check here first
• Variable dumps
• Static Pages
• Configuration files
• Custom Query Templates
• Victor's Dev Setup

These pages are developer specific:

• Common developer HOWTO's
• Working with data
• Hooking Page Render
• Hooking the User Profile

Tutorials

• Tutorial: Hooking File Events
• Tutorial: Replacing the File Verifier
• Tutorial: Ultimate Template
• Tutorial: ccMixter's "Remix Me" Feature Covers custom templates, embedded custom dataview, 'publicize', popup window, nested templates, feature page
• Tutorial: ccMixter's Featured Playlist Covers content topics, database insert, command menus, event handling.