ccHost documentation

This document is a continuation of the ccHost Administrators Guide. If nothing else you need to familiarize yourself with Customizing Files and Using the ccHost Query/Formatting Engine. If you need to do anything more than the most rudimentary XHTML output then you also need know the material in XHTML in ccHost and Tutorial: Create a New Skin

While it is tempting to dig around in ccHost code to cut/paste out pieces there are many places that today would be considered, er, less than 'best practices.' By reading this document you can at least begin to recognize what is supposed to be happening in some of the 'older' code.

Directory Structure

Each ccHost installation has a set of system directories that start with cc prefix. You should only ever touch the cc* directories in dire emergencies.

Your installation has a set of directories where the system will look for custom code, XHTML templates, log files, temp files, etc. Before starting work on customizing your site, go to Global Settings then Paths and take a look around. When this document refers to your viewfile Path, Plugins Path, etc. it means the values in the Paths admin screen (aka user directories).

How files are found:

When looking for specific files, the default behavoir is that user directories are searched in the order specified in the Paths admin screen. The first matching filename will be used. Subdirectories are not searched with one exception mentioned below.
Any file with a .php extension (aka module) anywhere in the Plugins Path will be loaded each and every page (or AJAX) request. The ordre of directories in Plugins Path will be honored, but actual the actual order the files are loaded within each directory is system dependent so you should not assume an order.
Running code at the top of the module is officially a Bad Idea. You should wait for the CC_EVENT_APP_INIT event to occur before even thinking about executing custom code.
The .php files in the system directory ccextras will is loaded first, then the Plugins Path user directores.
The viewfile (alias docs) command uses viewfile Paths to search for the requested document. If the requested file is not found, the system will try again with an .xml extension (assuming the request had no extension). So the following requests will all yeild the same result:
```
http://your_install/media/docs/query              
http://your_install/media/docs/query.xml
http://your_install/media/viewfile/query
http://your_install/media/viewfile/query.xml
```
When looking for a template from PHP code the Skins Path user directories are searched in the order specified by the user. However, when a template is referenced from within another template, the directory of the calling template will be searched first, then, if not found, the user directories.
For the template (t) parameter of a Query request, the Skins Path is searched in order, adding a .xml extension if needed. If not found an additional search of subdirectories specifically called "formats" will be used.

Develepment Environment

Enabling Debug Mode

In order to enable debugging on a development non-production machine, put the following code into a module in your Plugins Path:

<?  CCDebug::Enable(true); ?>

Inspecting Variables

With debugging enabled, you can inspect any variable on the screen using CCDebug::PrintVar or in the log using CCDebug::LogVar or send any message to the log using CCDebug::Log.

CCDebug::PrintVar will stop execution at the point it is called and display the variable in the browser. You can not pass a constant, it must be a variable (or object or array, etc.) that can be a PHP reference.

HINT: If you want to inspect more than one variable at a time, put them into an array.

// Some examples of 
function foo()
{
    CCDebug::PrintVar($_POST);
}
 
function bar()
{
    global $CC_GLOBALS;
 
    CCDebug::PrintVar($CC_GLOBALS);
}
 
function some_method_1($arg1, $arg2, $arg3 )
{
    // this will execute in any mode
    $value1 = $arg1 + 10;    
 
    // this will only work in debug mode
    CCDebug::PrintVar($value1);  
 
    // this will not execute in debug mode
    $value2 = $arg2 - 10;    
}
 
function some_method_2($arg1, $arg2, $arg3 )
{
    $x[] = $arg1;
    $x[] = $arg2;
    CCDebug::PrintVar($x);
}
 
function some_method_2($arg1 )
{
    // This won't work, the var must be a reference
    CCDebug::PrintVar('some arg: ' . $arg1);
 
    // this is fine
    $x = 'some arg: ' . $arg1;
    CCDebug::PrintVar($x);
}
 
function called_from_template($arg1)
{
    // if you are debugging code that is part of the
    // template display or called from a PHPTAL
    // template then you must specify
    // that the call is "not template safe"
 
    CCDebug::PrintVar($arg1, false);
}

CCDebug::LogVar and CCDebug::Log will continue execution passed the point they are called and put the result into the log. (The log file is called cc-log.txt in Logfile Directory.)

function some_method_1($arg1, $arg2, $arg3 )
{
    // code will execute
    $value1 = $arg1 + 10; 
 
    CCDebug::LogVar('this is the value:', $value1);
 
    // so will this
    $value2 = $arg2 - 10; 
}
 
function some_method_2($arg1, $arg2, $arg3 )
{
    // code will execute
    $value1 = $arg1 + 10; 
 
    CCDebug::Log("I'm here at line " . __LINE__ );
 
    // so will this
    $value2 = $arg2 - 10; 
}

Displaying a Stack Trace

There's a lot of common code in ccHost and sometimes it's difficult to figure out who is calling what in what context. If you're seeing an error in common code make sure to (turn on debug mode) and insert the following line where the error is occurring:

CCDebug::StackTrace();

Create a Quick Test Bed

Sometimes you just want to see if your idea will work at all. To create a quick and dirty test bed start by creating a module with this code.

CCEvents::AddHandler(CC_EVENT_APP_INIT,  'just_testing' );
 
function just_testing()
{
    if( empty($_GET['test']) || !CCUser::IsAdmin()))
        return;
 
     // your code here....
 
}

To invoke your test bed browse to: http://your_cchost_install/?test=1

Code Modules

Create a New Module

Create any file with .php extension and put it into Plugins Path. You're done.

Create a URL and Bind it to a Method

// Tell ccHost you have a URL to map:
CCEvents::AddHandler( CC_EVENT_MAP_URLS, 
                      array( 'myclass', 'OnMapUrls' ) );
 
class myclass
{
  function OnMapUrls()
  {
 
    // this will be called when ccHost needs to know about
    // url mappings, it is only called when an admin does
    // updates with ?update=1 
    //
     CCEvents::MapUrl( ccp('some', 'url'),
             array( 'myclass', 'some_url_handler') ,
             CC_MUST_BE_LOGGED_IN
            );
  }
 
  // this is your custom code that will be called
  // when someone browses to some/url
  //
    function some_url_handler($required, $optional='')
  {
     // some random code:
     CCPage::SetTitle('Hello $required!');
     if( empty($optional) )
       CCPage::Prompt("hello world!");
     else
       CCPage::Prompt("hello $optional!");
  }}

The last parameter is an access flag that must be one of the following:

CC_MUST_BE_LOGGED_IN
CC_ONLY_NOT_LOGGED_IN
CC_DONT_CARE_LOGGED_IN
CC_ADMIN_ONLY

To register the new binding browse to: http://example.com/?update=1. To see this action you can call any of the following urls:

http://example.com/media/some/url/cchost
http://example.com/media/some/url/cchost/mom
http://example.com/media/some/url/goodbye/marvin

Database

Create a New Database Column

Here are the steps to add a new database column into an existing ccHost table.

First: create a file whose name is in the format: update_unique_part.inc and put that into ccextras directory.

For the unique_part you should use something that identifies you and a version number:

ccextras/update_joesoft_v_1_0.inc
ccextras/update_janeplugins_v_3_2a.inc

In that module create a class derived from CCUpdate and implement the Update method that is named exactly the same name as the unique_part of the file name:

// columns required by joesoft 
 
class joesoft_v_1_0 extends CCUpdate
{
    function Update()
    {
    }
}

Next you want to call the inherited _check_for_field() method. The prototype is:

function _check_for_field( $table_name,
                                 $column_name,
                                 $column_description )

Let's say you want to add an column for 'age' to the users table:

// columns required by joesoft 
 
class joesoft_v_1_0 extends CCUpdate
{
    function Update()
    {
        $this->_check_for_field(
                        'cc_tbl_user', 
                        'user_age', 
                        'INT(4) unsigned');
    }
}

When someone installs your plugin they will have to (logged in as admin) update their site by browsing to: http://cchost_installation/?update=1

Create a New Database Table

To add an entirely new table to a ccHost installation follow the same steps to Create a New Database Column (Create a New Database Column) except for the code in Update which will look something like this:

// table required by joesoft 
 
class joesoft_v_1_0 extends CCUpdate
{
  function Update()
  {
   $sql = '
    CREATE TABLE joes_table
    (
      jt_id    int(11) unsigned  NOT NULL auto_increment,
      jt_user  int(11) unsigned  NOT NULL,
      jt_age   int(4)  unsigned  NOT NULL,
      jt_allow_im  int(2)  unsigned  NOT NULL,
      jt_im    varchar(4) NOT NULL,
      jt_location  varchar(255) NOT NULL,
 
      PRIMARY KEY jt_id (jt_id)
    )
    ';
 
    CCDatabase::Query($sql);
  }
}

It is strongly suggested that you create a ccHost table wrapper for the class. After you create a new module (Create a New Module) you should create a class derived from CCTable:

class JSJoesTable extends CCTable
{
  function JSJoesTable()
  {
     $this->CCTable( 'joes_table',  // mysql table name
             'jt_id'   // PRIMARY KEY
           );
 
  }
 
  // create a singleton factory
    function & GetTable()
  {
    static $_table;
    if( empty($_table) )
      $_table = new JSJoesTable();
    return $_table;
  }
}

Insert a Record Into a Table

All tables in the system follow the same code pattern for row insertion:

function AddUserAge($user_id, $age)
{
    $joestable =& JSJoesTable::GetTable();
    $args['jt_user'] = $user_id;
    $args['jt_age'] = $age;
    $joestable->Insert($args);
}

If you need to know the key of the new record use NextID:

function AddUserAge($user_id, $age)
{
    $joestable =& JSJoesTable::GetTable();
    $args['jt_id'] = $joestable->NextID();
    $args['jt_user'] = $user_id;
    $args['jt_age'] = $age;
    $joestable->Insert($args);
    return $args['jt_id'];
}

Update a Database Record

All tables in the system follow the same code pattern for row updating. The Update assumes that the argument array contains a primary key (aka 'id') value:

function UpdateAge($jt_id, $age)
{
    $joestable =& JSJoesTable::GetTable();
    $args['jt_id'] = $jt_id;
    $args['jt_age'] = $age;
    $joestable->Update($args);
}

If you don't have the key you'll need to look it up:

function UpdateUserAge($user_id, $age)
{
    $joestable =& JSJoesTable::GetTable();
    $where['jt_user'] = $user_id;
    $jt_id = $joestable->QueryKey($where);
    UpdateAge($jt_id, $age);
}
 
function UpdateAge($jt_id, $age)
{
    $joestable =& JSJoesTable::GetTable();
    $args['jt_id'] = $jt_id;
    $args['jt_age'] = $age;
    $joestable->Update($args);
}

Adding Custom Data To Upload Records

You can add custom data to any upload record without changing the database meta data (adding tables or columns). The upload_extra field in each upload record ("row" vs. "record") designed specifically to hold this kind of custom data. There is also a simple API for setting and getting your data.

To Add Your Custom Data

function add_my_data($my_data,$upload_id)
{
  $uploads =& CCUploads::GetTable();
  $uploads->SetExtraField(
     $upload_id,    // This can also be a reference
                    // to a record  
     'joes_extra',  // The name of your extra field  
     $my_data       // This can be any serializeable type
                    // of data including array.
   );
}

To Retrieve Your Custom Data

function get_my_data($upload_id)
{
  $uploads =& CCUploads::GetTable();
  return $uploads->GetExtraField($upload_id, 'joes_extra');
}

Alternatively, if you are already looking at a record, you can access the data directly:

function get_my_data_from_record(&$record)
{
  if( exist( $record['upload_extra']['joes_extra'] ) )
     return $record['upload_extra']['joes_extra'];
  return null;
}

To Search For Your Custom Data

The only drawback to using this method is that searching for your data is extremely expensive (it takes a long time) and is strongly recommended you don't do it. See the documentation for CCUploads::WhereForSerializedField if you really must or if searching on this data is critical then you should probably consider adding a new column (Create a New Database Column) to cc_tbl_uploads or even better, a new table (Create a New Database Table) instead using the extra field.

If you can get by with just searching for records with presence of your extra data then you can add a system tag to the upload row when you add the data:

function add_my_data($my_data,$upload_id)
{
  $uploads =& CCUploads::GetTable();
  $uploads->SetExtraField($upload_id,
                          'joes_extra',
                          $my_data
                          );
 
  // A terrible name for a useful function:
  // this call will add a tag 'joes_data'
  CCUploadAPI::UpdateCCUD($upload_id,'joes_tag','');
 
}

Now it's just a matter of setting a tag filter to limit results that have your custom data in the extra fields:

function list_recs_with_joes_data()
{
  $uploads =& CCUploads::GetTable();
 
  // Filter results with this tag
  $uploads->SetTagFilter('joes_tag');    
  
  // Empty 'where' gets all tagged records
  $records =& $uploads->GetRecords(''); 
  
  // Don't forget to release the tag filter (!!!)
  $uploads->SetTagFilter('');            
  
  // $records now points to all uploads with our data
  $count = count($records);              
  for( $i = 0; $i < $count; $i++)
  {
    $record =& $records[$i];
    $joes_data = $record['upload_extra']['joes_data'];
    //....

Editing and Deleting Your Custom Data

Editing and deleting the data has some non-obvious implications whether you use the tagging method above or not. This method puts some of the basics together:

function update_extra_data($upload_id, $my_data)
{
  $uploads =& CCUploads::GetTable();
 
  // let's see what's currently there: 
 
  $current_data = $uploads->GetExtraField($upload_id,'joes_data');
 
  if( empty($my_data) )
  {
    // delete the tag:
 
    CCUploadAPI::UpdateCCUD($upload_id,'','joes_tag');
 
    if( !empty($current_data) )
    {
      // something is there now, let's clear it:
 
      $uploads->SetExtraField($upload_id,'joes_data','');
    }}
  else
  {
    // do we need to add a tag? 
 
    if( empty($current_data) )
      CCUploadAPI::UpdateCCUD($upload_id,'joes_tag','');  // yup
 
    // set the extra data 
    $uploads->SetExtraField($upload_id,'joes_data',$my_data);
 
  }
}

Forms

Display a Form

Create a class that derives that from CCForm. The name of the class must in this specific form:

2-letter-prefix form_name Form (no spaces)
 
class CCJoesEditForm extends CCForm  // this is ok
class xxEditAgeForm  extends CCForm  // this is ok
 
class Joe   extends CCForm           // this is not
class xxJoe extends CCForm

Fields are created in the constructor of the form object:

class JSJoesEditForm extends CCForm
{
  function JSJoesEditForm()
  {
    $this->CCForm();
 
    $fields = array(
       'age' => array(
          'label'   => 'Age',
          'form_tip'  => 'Enter your age here',
          'formatter' => 'textedit',
          'flags'   => CCFF_REQUIRED,
          ),
       'allow_im' => array(
          'label'   => 'Enable Instant Messaging',
          'form_tip'  => 'Enable instant messages notifications',
          'formatter' => 'checkbox',
          'flags'   => CCFF_NONE,
          ),
       'im' => array(
          'label'   => 'IM Service',
          'formatter' => 'select',
          'options'   => array(
                   'aol' => 'Americal Online',
                   'msn' => 'Microsoft',
                   'irc' => 'Independent Relay Crisis'
                   ),
          'flags'   => CCFF_NONE,
          ),
      );
 
    $this->AddFormFields($fields);
  }
}

A 'formatter' is the thing that generates the html for the field and validates the value during submit. There are many standard and built in generators. See cclib/cc-form.php for a list functions that start with generator_ for the standard ones.

The 'flags' field is very important and can lead to a lot of confusion if used incorrectly. See the documentation AddFormFields in cclib/cc-form.php for what is possible. All flags begin with CCFF_ prefix.

To display your form:

function EditJSInfo()
{
    CCPage::SetTitle('Edit Special User Info');
 
    $form = new JSJoesEditForm();
 
    CCPage::AddForm( $form->GenerateForm() );
}

Populate a Form

There are several ways to populate a form you've created (Display a Form). By far the most efficient way is to use PopulateValues. In order for PopulateValues to work you first have to mark the fields you expect to populate with CCFF_POPULATE flag

'age' => array(
        'label'     => 'Age',
        'form_tip'  => 'Enter your age here',
        'formatter' => 'textedit',
        'flags'     => CCFF_REQUIRED | CCFF_POPULATE,
        ),
'allow_im' => array(
        'label'     => 'Enable Instant Messagings',
        'formatter' => 'checkbox',
        'flags'     => CCFF_POPULATE,
        ),
'im' => array(
    'label'     => 'IM Service',
    'formatter' => 'select',
    'options'   => array(
                     'aol' => 'Americal Online',
                     'msn' => 'Microsoft',
                     'irc' => 'Independent Relay Crisis'
                     ),
    'flags'     => CCFF_POPULATE,
    ),

Now you're ready to populate:

function EditJSInfo($age, $allow_im, $im )
{
    CCPage::SetTitle('Edit Special User Info');
 
    $form = new JSJoesEditForm();
 
    $values['age'] = $age;
    $values['allow_im'] = $allow_im;
    $values['im'] = $im;
    $form->PopulateValues($values);
 
    CCPage::AddForm( $form->GenerateForm() );
}

HINT: If you are populating values from a database row (Create a New Database Table), then your life will get much simpler if name the fields the same as the database columns:

class JSJoesEditForm extends CCForm
{
  function JSJoesEditForm()
  {
  $this->CCForm();
 
  $fields = array(
     'jt_age' => array(
      'label'   => 'Age',
      'form_tip'  => 'Enter your age here',
      'formatter' => 'textedit',
      'flags'   => CCFF_REQUIRED | CCFF_POPULATE,
      ),
     'jt_allow_im' => array(
      'label'   => 'Enable Instant Messagings',
      'formatter' => 'checkbox',
      'flags'   => CCFF_POPULATE,
      ),
     'jt_im' => array(
      'label'   => 'IM Service',
      'formatter' => 'select',
      'options'   => array(
           'aol' => 'Americal Online',
           'msn' => 'Microsoft',
           'irc' => 'Independent Relay Crisis'
           ),
      'flags'   => CCFF_POPULATE,
      ),
    );
 
  $this->AddFormFields($fields);
  }
}

Now the results of doing a query for a row can be used directly to populate the form:

function EditJSInfo($jt_id )
{
    CCPage::SetTitle('Edit Special User Info');
 
    $form = new JSJoesEditForm();
 
    $joestable =& JSJoesTable::GetTable();
    $values = $joestable->QueryKeyRow($jt_id);
    $form->PopulateValues($values);
 
    CCPage::AddForm( $form->GenerateForm() );
}

Handling Form Submit

To handle a user submit of a form you've created (Display a Form) we'll use the same method we use to populate the form (Populate a Form), only now we'll check if we are processing the submit.

You can use the same URL to display the form initially and handle the submit by mapping one URL (Create a URL and Bind it to a Method) to this method.

For (marginal) security reasons, the name of the form in lower case is in PHP's $_POST array so you want to check for that to see if you are in fact, process the submit:

function EditJSInfo($jt_id )
{
  CCPage::SetTitle('Edit Special User Info');
 
  $form = new JSJoesEditForm();
 
  if( empty($_POST['joesedit']) )
  {
    // this is first time we are displaying the form
 
    $show_form = true;
  }
  else
  {
    // we are in submit...
 
    $show_form = false;
  }
 
  if( $show_form )
  {
    // populate the form from a database
 
    $joestable =& JSJoesTable::GetTable();
    $values = $joestable->QueryKeyRow($jt_id);
    $form->PopulateValues($values);
 
    CCPage::AddForm( $form->GenerateForm() );
  }
}

You'll want to validate the fields first before you get the values. If the form did not validate then ccHost automatically re-populates the data from the user's input and marks the fields that did not validate, but you have to redisplay the form. Here's what all that looks like:

function EditJSInfo($jt_id )
{
  CCPage::SetTitle('Edit Special User Info');
 
  $form = new JSJoesEditForm();
 
  if( empty($_POST['joesedit']) )
  {
    // this is first time we are displaying the form
 
    $show_form = true;
 
    // get the values from the database
 
    $need_values = true;
  }
  else
  {
    // we are in submit...
 
    if( $form->ValidateFields() )
    {
      // great, let's get the user's inputs...
 
      $form->GetFormValues($values);
 
      // process user values here...
 
      $joestable =& JSJoesTable::GetTable();
      $values['jt_id'] = $jt_id; // Update requires the key
      $joestable->Update($values);
 
      CCPage::Prompt("Your special information has been saved");
 
      $show_form = false;
    }
    else
    {
      // wups, have to show the form again
      // ccHost will display all the errors automatically
 
      $show_form = true;
 
      // do not populate the form from the database
 
      $need_values = false;
 
    }}
 
  if( $show_form )
  {
    if( $need_values )
    {
      // populate the form from a database
 
      $joestable =& JSJoesTable::GetTable();
      $values = $joestable->QueryKeyRow($jt_id);
      $form->PopulateValues($values);
    }
 
    CCPage::AddForm( $form->GenerateForm() );
  }
}

NOTE: The GetFormValues method won't work at all until after you call ValidateFields so you always have to call both to get the user values.

Dynamically Insert a Form Field

You can dynamically add a field to an existing form (e.g. the user profile or one of the upload forms). In order to do this you need to have an understanding of how forms work in general (Display a Form).

Create a new module (Create a New Module) and put the following lines at the top:

CCEvents::AddHandler(CC_EVENT_FORM_FIELDS,    array( 'myclass', 'OnFormFields'));
CCEvents::AddHandler(CC_EVENT_FORM_POPULATE,  array( 'myclass', 'OnFormPopulate') );
CCEvents::AddHandler(CC_EVENT_FORM_VERIFY,    array( 'myclass', 'OnFormVerify') );

Now create a class with those methods

class myclass
{
    function OnFormFields(&$form,&$fields)
    {
    }
 
    function OnFormPopulate(&$form,&$values)
    {
    }
 
    function OnFormVerify(&$form,&$isvalid)
    {
    }
}

Since your code will be called whenever a form is displayed you'll have to check to see if it's the form you care about (in this case the form used to edit user profile):

class myclass
{
    function OnFormFields(&$form,&$fields)
    {
        if( strtolower( get_class($form) ) != 'ccuserprofileform' )
          return;
    }
 
    function OnFormPopulate(&$form,&$values)
    {
        if( strtolower( get_class($form) ) != 'ccuserprofileform' )
          return;
    }
 
 
    function OnFormVerify(&$form,&$isvalid)
    {
        if( strtolower( get_class($form) ) != 'ccuserprofileform' )
          return;
    }
}

For each handler you can add the code required

class myclass
{
  // called when form object is being constructed
 
  
  function OnFormFields(&$form,&$fields)
  {
    if( strtolower( get_class($form) ) != 'ccuserprofileform' )
      return;
 
    // add our field into the form:
 
    $fields['jt_location'] =
          array( 'label'    => 'Location',
               'form_tip'   => 'Where are you?',
               'formatter'  => 'textedit',
               'flags'    => CCFF_NONE);
  }
 
 
  // called when form object is being displayed
  // for the first time
 
  
  function OnFormPopulate(&$form,&$values)
  {
    if( strtolower( get_class($form) ) != 'ccuserprofileform' )
      return;
 
    // do what you have to translate what's in $values
    // to a value the user expects...
 
    // look up the user's info in our table
 
    $joestable =& new JSJoesTable::GetTable();
    $where['jt_user'] = $values['user_id'];
    $location = $joestable->QueryItem('jt_location', $where);
 
    // now, set the value into the form:
 
    $form->SetFormValue('jt_location',$location);
  }
 
 
   called on form submit after the rest of the
  // form has validated (or not)
 
 
  
  function OnFormVerify(&$form,&$isvalid)
  {
    if( strtolower( get_class($form) ) != 'ccuserprofileform' )
      return;
 
    // this is the safe way to get a value from
    // the submitted form:
 
    $location = CCUtil::StripText($_POST['jt_location']);
 
    // do what you have to validate the data
 
    $isvalid_location = my_check_location_func($location);
 
    if( $isvalid_location )
    {
      // our data validated
 
      if( $isvalid )
      {
        // so did the rest of the form, let's save
        // our location data
 
        // get the user id from the form:
 
        $user_id = $form->GetFormValue( 'user_id' );
 
        // get an instance of our table
 
        $joestable =& new JSJoesTable::GetTable();
 
        // get the key for this user 
        // so we can do the update
 
        $args['jt_user'] = $user_id;
        $args['jt_id']   = $joestable->QueryKey($args);
 
        // save the data to the table
 
        $args['jt_location'] = $location;
 
        $joestable->Update($args);
      }}
    else
    {
      // our data did not validate,
      // tell the user why:
 
      $form->SetFieldError('jt_location',
            'The location must be on Earth');
    }
 
    $isvalid |= $isvalid_location;
  }
}

X/HTML

If you are totally unfamiliar with PHPTAL you will likely get pretty frustrated pretty fast.

Display HTML (Squirt)

Bind a URL to a method and you can squirt directly into the page:

function just_show_it()
{
    $html ='
<h3>Some hacked in HTML</h3>
<p>This will be in the client area.</p>
';
 
    CCPage::PageArg('body_html',$html,'show_body_html');
}

Display HTML (viewfile)

Put an XML file into the viewfile Path and you can invoke php code from within it. (See the admin Query tutorial for an example.) The advantage of this method is that you don't have to bind a new URL to see the results, just use the viewfile (a.k.a. docs) command. The disadvantage is that this method is totally unsuitable for even mildly complex code.

Display HTML (Skin Macro)

Bind a URL to a method and invoke a macro that is known to the current skin:

function show_my_files($extra_tags='')
{
    if( !empty($extra_tags) )
        $extra_tags = ", $extra_tags";
 
    // retrieve the records...
    //
    require_once('cclib/cc-query.php');
    $query = new CCQuery();
    list( $records ) = $query->Query(array('f'=>'php','tags'=>"remix$exrra_tags"));
 
    // munge it with your special touch...
    //
    for( $i = 0; $i < count($records);
    {
        // do some custom special code with $record[$i] = 
    }
 
    // parameters:
    //    'records' -- this is the name of variable used in the template
    //                 the template expects this to be a specific thing
    //                 so you can't just make up a name
    //    $records  -- this is the data passed into the template
    //
    // 'list_files' -- this is the name of the template macro. The actual
    //                 location of the file is all handled by the 
    //                 template engine which knows about stuff like 
    //                 the current skin
    //
    CCPage::PageArg('records',$records,'list_files');
}

Display HTML (Custom Template Macro)

Put an XML template with phpTAL metal:block macros into the Skins Path. Bind a URL to a method and invoke those macros from PHP.

<metal:block define-macro="my_macro" >
    <!-- local_files/skin/my_template.xml -->
    <select>
       <option repeat="record records" value="record/upload_id" >
            ${record/upload_name}
       </option>
    </select>
</metal:block>

function use_my_template($extra_tags='')
{
    if( !empty($extra_tags) )
        $extra_tags = ", $extra_tags";
 
    // retrieve the records...
    //
    require_once('cclib/cc-query.php');
    $query = new CCQuery();
    list( $records ) = $query->Query(array('f'=>'php','tags'=>"remix$exrra_tags"));
 
    // Tell the skin where to find your macro
    //
    // This says: When I ask for 'some_name' I really
    // mean 'my_template.xml/my_macro'
    //
    CCPage::PageArg('some_name', 'my_template.xml/my_macro' );
 
    // This says: invoke the macro mapped to 'some_name'
    // passing in the data in $records and call it 
    // 'records'
    //
    CCPage::PageArg('records',$records,'list_files');
}

Display HTML (For a Query)

If the all you are listing out are upload records you definitely use the Query API and a custom template. You don't need to bind any urls or write any PHP code at all to set that up. The admin docs have a example of how that works.

AJAX in ccHost

ccHost uses prototype.js "as is" on the client for AJAX requests.

To return JSON use the Zend JSON encoder already included in ccHost

Returning JSON

{
    // setup data as native PHP
    //
        $return_vals = array( 'msg' => 'hello world' );
 
    // encode as JSON
        require_once('cclib/zend/json-encoder.php');
    $json =  CCZend_Json_Encoder::encode($return_vals);
  
    // JSON wants the data in the header
        header( "X-JSON: $text");
    header( 'Content-type: text/plain');
    print($text);
 
    // exit the session so nothing else gets printed
        exit;
}

Returning HTML (Snippet)

To return a snippet of HTML create a template macro in your Skins Path. Then invoke it using the special CCTemplateMacro class.

<metal:block define-macro="print_msg" >
    <!-- local_files/skin/my_template.xml -->
    <div class="message"> ${args/msg} </div>
</metal:block>

{
    // data to send into template
    //
        $args = array( 'msg' => 'hello world' );
 
    // Using this class you will have access to
    // all the current skins macros
    //
        $template = new CCTemplateMacro( 'my_template.xml', 'print_msg' );
 
    // This call presumes the macro is waiting for
    // a set a variables called 'args'
    // 
        $template->SetAllAndPrint('args',$args);
 
    // exit the session so nothing gets printed
        exit;
}

Returning HTML (Formatted Snippet)

To return a snippet of HTML that has all the formatting and scripts of the current skin, create a template macro in your Skins Path. Then invoke it as did for placing a macro on a page but call {@CCPage::ShowHeaderFooter} with false,false to chop off the banner, menus and footers. This leaves the <head> section of the skin in tact allowing you to enjoy the benefits of the style sheets and javascript references of the current skin. The method is useful for popups.

function use_my_template($extra_tags='')
{
    if( !empty($extra_tags) )
        $extra_tags = ", $extra_tags";
 
    // retrieve the records...
    //
    require_once('cclib/cc-query.php');
    $query = new CCQuery();
    list( $records ) = $query->Query(array('f'=>'php','tags'=>"remix$exrra_tags"));
 
    // Tell the skin where to find your macro
    //
    // This says: When I ask for 'some_name' I really
    // mean 'my_template.xml/my_macro'
    //
    CCPage::PageArg('some_name', 'my_template.xml/my_macro' );
 
    // This says: invoke the macro mapped to 'some_name'
    // passing in the data in $records and call it 
    // 'records'
    //
    CCPage::PageArg('records',$records,'list_files');
 
    // We will print the page, but without 'adornments'
    //
    CCPage::ShowHeaderFooter(false,false);
}

Terminology

"row" vs. "record"

The CCTable object has several methods with the word 'row' in it, QueryRows, QueryRow and QueryKeyRow. Whenever you see the word 'row' in the code it (almost) always refers to a database table row as it is stored in the database (a.k.a the 'raw' data). Retrieving a row is generally a very quick operation but the data in the row is of specialized, limited use.

{
  $uploads =& CCUploads::GetTable();
  // get the upload with the upload_id of '101'
    $row = $uploads->QueryKeyRow(101); 
  $is_published = $row['upload_published'];
  $is_banned    = $row['upload_banned'];
}

Meanwhile a 'record' is a row that has been heavily massaged. Retrieving the record is much more heavy weight operation but results in a lot more data that should have just about everything you ever wanted to know about that upload, user, topic, etc.

{
  $uploads =& CCUploads::GetTable();
  // get the upload with the upload_id of '101'
    $record = $uploads->GetRecordFromKey(101); 
  $args['upload_href'] = $record['file_page_url'];
  $args['upload_text'] = $record['upload_name'];
  $args['user_href']   = $record['artist_page_url'];
  $args['user_text']   = $record['user_real_name'];
  //...

In order to get fully familiar with the what kind of data is available in both rows and records, it is highly recommended that you set up a debug environment (Develepment Environment) and dump the contents using the GetRecordFromRow method. First the row:

{
  $uploads =& CCUploads::GetTable();
  // get the upload with the upload_id of '101'
    $row = $uploads->QueryKeyRow(101); 
  CCDebug::PrintVar($row);
  //...

...then the record:

{
  $uploads =& CCUploads::GetTable();
  // get the upload with the upload_id of '101'
    $row = $uploads->QueryKeyRow(101); 
  $record =& $uploads->GetRecordFromRow($row);
  CCDebug::PrintVar($record);
  //...

If you determine that you really need the records and not the rows then you can skip the conversion step and call GetRecords:

{
  $uploads =& CCUploads::GetTable();
  $where = "upload_name LIKE '%sunny%'";
  $records =& $uploads->GetRecords($where); // Returns an array
  // Don't use foreach with records, it's too expensive
    $count = count($records);
  for( $i = 0; $i < $count; $i++ )
  {
      $record =& $records[$i];
      //...

"upload" vs "file"

An 'upload' is a database row that represents the meta information that the user entered for their submission. It has the name, tags, description, etc. stored in it. Use the CCUploads table object to access this data.

An upload can have more than one physical file stored on your server. Users upload these files using the 'Manage Files' menu option on the upload's main page. Each file has it's own specific meta data such as the file format, the physical name, system tags, etc. The recommended way of accessing the specific data about a file is through the files field of an upload record ("row" vs. "record"):

{
  $uploads =& CCUploads::GetTable();
  $where = "upload_name LIKE '%sunny%'";
  $records =& $uploads->GetRecords($where);
  $count = count($records);
  for( $i = 0; $i < $count; $i++ )
  {
      $record =& $records[$i];
      $files =& $record['files'];
      $fcount = count($files);
      for( $n = 0; $n < $fcount; $n++ )
      {
         $file =& $files[$n];
         //...

To get familiar with the contents of the file record you should set up a debug environment (Develepment Environment) to inspect the data:

{
  $uploads =& CCUploads::GetTable();
  $where = "upload_name LIKE '%sunny%'";
  $records =& $uploads->GetRecords($where);
  $count = count($records);
  for( $i = 0; $i < $count; $i++ )
  {
      $record =& $records[$i];
      CCDebug::PrintVar($record['files']);
      //...

"key" vs "id"

The terms 'key' and 'id' are used interchangeably throughout ccHost code. They both refer to the PRIMARY KEY column in any table which are unique numeric references within the table.

ccHost - Developer Cookbook

A (hopefully) simple breakdown of common operations.

Table of Contents

Read Me First