Rules for Editing XHTML

The template engine used by ccHost is extremely sensitive to the strict rules of XML so consider this section a kind of Do's and Don'ts. But keep in mind these are not merely suggestions, if you don't follow these rules your pages will not display and the site will be broken until you fix these issues.

<table colspan="3">

<option selected="selected">

Variables Available in XHTML

You can individualize your pages by using variables that are recalculated every time the page is rendered. For example, if the user is logged you can personalize the page based on if they have uploaded anything to your site.

Rather than list the possible variables here, you can employ the same method used by skin writers as described at the ccHost Wiki to print out all the variables available in your system using the ?dump_page=1 query.

You can access these variables on your page with this syntax:

${variable_name}

For example:

<h1>Welcome to ${site-title}</h1>
<h2>${site-description}</h2>

To make certain blocks conditional, use the tal:condition attribute on any XHTML tag. In the following example the DIV will only appear if the system detects the presence of the 'logged_in_as' variable. If that variable is there we assume the entire 'user_*' record is available to us:

<div tal:condition="logged_in_as" >Hello ${user_real_name}</div>

Note that in the tal:condition attribute you do not use the ${} syntax, just the variable name.

Alternately, you can use the not: syntax (do not forget the ':') to show something else:

<div tal:condition="not: logged_in_as" >
   Hey you should <a href="${home-url}register">register with us!</a>
</div>

${home-url} vs. ${root-url} and ${q}

There are two variables that represent the site's URL in the XHTML templates:

home-url includes the current virtual root and accounts for pretty URLs while root-url does neither. In both cases they including the trailing backslash.

Typical home-url expands to something like http://myserver.com/cchost?ccm=/media/, typical root-url for the same page is http://myserver.com/cchost/.

Always use the home-url whenever you can. The one exception is physical files on your server like images, style sheets, etc. in which case you want to start with root-url

The variable simply called q (lower case 'q') which stands for 'question mark.' It maps to either '?' or '&' depending on whether you are configured to use pretty-urls or not. You should use it instead of the actual '?' character whenever you are building urls in templates.

<a href="${home-url}api/query${q}tags=remix">See remixes...</a>

Working With Dynamic Data in XHTML

You can work with dynamic data retrieved from the ccHost system in two steps:

1. Get the data from ccHost into a template variable using a tal:block tag.
2. Display the template variable using XHTML tags using the tal:repeat for arrays and lists.

Get the Dynamic Data

For this step there are several PHP functions in ccHost for retrieving dynamic data that are defined in cc-custom.php. The official developer documenation for these functions can be found here.

Custom Dynamic Data

If the functions provided in ccHost aren't doing it for you and you don't mind writing a little PHP script then it's very easy to get custom dynamic information onto one of your pages.

Let's take a scenario where you want to display the newest members of you community on your home page. To start, create a file called mylib.php in the ccextras directory. That has the following code in it:

<?
 
// return the newest five users...
function my_get_users()
{
   $users =& CCUsers::GetTable();
   $users->SetOffsetAndLimit(0,5);
   return $users->GetRecords('');
}
 
?>

Now the function my_get_users() is available to any template in the system but you'll want to be editing home.xml (which of course is the copy in your private files directory, right??).

Getting and displaying the data is exactly the same idea as the standard way, this time we'll check if they have an avatar and display it:

<tal:block define="records php:my_get_users()" /> 

<h2>Our newest users are:</h2>

<div tal:repeat="record records">
  <div tal:condition="record/user_avatar_url">
     <img src="${record/user_avatar_url" />
  </div>
  ${record/user_real_name}
  <p>
    Check 'em out 
    <a href="${record/artist_page_url}">here</a>!
  </p>
</div>

Of course this is a very simple example and the PHP script can get very complicated, very quickly but it does prove the point.