Using the ccHost Query/Formatting Engine

This documenation refers to ccHost 4.5. There are serious changes coming in 5.0 Make sure to keep tabs at the ccHost Wiki

ccQFE Overview

Examples

In the Browser

Navigator tabs

Templates and HTML files (Native)

Templates and HTML files (AJAX)

Templates and HTML files (Universal/"Publicize")

ccQFE Overview

To be truly productive (and creative!) with a ccHost installation it is very important that you become familar with the ccHost Query/Formatter Engine (ccQFE) because it is the way to get information about uploads in your system.

ccQFE can be employed for features large and small. The ccQFE powers much of ccMixter, from the navigation tabs, Remix Radio, Publicize, Playlists, Picks Page, Song of the Day, Sample Browser, and dozens of other places.

The ccQFE works likes this: queries requests go in, formatted data comes out.

All the query requesta are done through URL type query strings (e.g. ?tags=remix&user=teru is how you request remixes uploaded by a user with a login name of 'teru'). And that format doesn't change no matter where you are asking from, the browser, a XHTML template or even specialized plug-ins.

One of the parameters is always a 'format' (or 'f' for short) so that you can control what the results will look like. So tags=remix&user=teru&f=rss means you want the results to be returned as an RSS/Podcast feed.

The formatted output can be in one of any number of formats such as native PHP, comma separated plain text, RSS, Atom, XSPF and JSON. You can also ask for an endless (and customizable) number of HTML snippets or other text based formats.

A complete and in sync version of the reference documenation for the Query Engine is included in your ccHost installation at docs/query.

Experimation is key to success. There are hundreds, maybe thousands of permutations of request parameters and output formats. Some work better (if at all) then others so get used to writing a lot of '?' and '&' on your way to finding the best combinations for your site.

Examples

In the Browser

The base url is api/query and parameters are added using standard URL query string parameters. The following will display the oldest remixes using the default skin:

http://your_installation/media/api/query?tags=remix&sort=date&dir=ASC

You can change the title of the display:

http://your_installation/media/api/query?tags=remix&sort=date&dir=ASC&title=Oldest Uploads

Navigator tabs

When creating and editing navigator tabs specify Query as the Function and use the Data field to enter your query request. The default format is 'page' which will return a page of results formatted with the standard upload listing. See Tutorial: Gallery View

HINT: You can also embed a query into an XHTML template using any of the methods below, then use the Execute URL as the Function and docs/your_template as the 'Data' field.

Templates and HTML files (Native)

Create a file in your viewfile directory called testquery.xml

In that file place the following:

<!-- 1. --> <div>
<!-- 2. --> <!-- this display the highest rated remixes on the site -->
<!-- 3. -->   <tal:block define="records php:cc_query_fmt('tags=remix&sort=score&dir=desc&limit=5');" />
<!-- 4. -->   <ol>
<!-- 5. -->     <li tal:repeat="R records">
<!-- 6. -->         <a href="${R/file_page_url}">${R/upload_name}</a>
<!-- 7. -->     </li>
<!-- 8. -->   </ol>
<!-- 9. --> </div>

Browse to docs/testquery (didn't work??)

Lines 1. and 9. are necessary to make this a complete XML document ( See XHTML in ccHost )

The acutal query request is done on line 3. In it we ask for:

tags=remix - uploads with the tag 'remix'

sort=score - sorted by user scores

ord=desc - sort by putting the highest score first

limit=5 - get no more than 5 records

The default output format for cc_query_fmt is native records (PHP arrays) so we didn't specify any other type.

We called the resulting array records and on live 5. we tell the template engine to iterate over the array and put each one into a variable called R.

If you have a template file that you want to reuse in you use the phpTAL's include syntax. The following code will display the details for a specific record using a pre-cooked template that expects a variable called records

<div>
<!-- 2 -->   <tal:block define="records php:cc_query_fmt('ids=8445');" />
<!-- 3 -->   <phptal:block include="string:formats/detail.xml" />
</div>

Templates and HTML files (AJAX)

If you find yourself reusing the same snippet of template in multiple places around your site you have the option to save the snippet to your server and invoke it via AJAX.

Create a file in your viewfile directory called testajaxquery.xml

In that file place the following:

<div>
<!-- 2 -->   <div id="target"></div>
<!-- 3 -->   <script>
<!-- 4 -->   //<!--
<!-- 5 -->     new Ajax.Updater( 'target', 
<!-- 6 -->       '${home-url}api/query${q}tags=remix&sort=score&ord=desc&f=html&t=links&limit=5',
<!-- 7 -->       { method: 'get' } );
<!-- 8 -->   // -->
<!-- 9 -->   </script>
</div>

Browse to docs/testajaxquery (didn't work??)

The code new Ajax.Updater is from the prototype.js library that ccHost uses for fancy Javascript magic.

The acutal query request is done on line 6. In it we ask for the same thing as the Native example above. The difference is that we specifiy an output format of html and specifically request a template snippet called links.

See ${home-url} vs. ${root-url} and ${q} for an explanation of some of the other syntax.

f=html - return the results as HTML

t=links - links is the name of a template. The actual file is in your installation at cctemplates/formats/links/links.xml. You can create your templates snippets like this and put them into your skins directory to get the same effect.

Templates and HTML files (Universal/"Publicize")

You can get the same results from the query engine even if you want to include the same information on another web page (like your blog or myspace page) with the following code:

<script 
   src="http://yourserver.com/media/>tags=remix&sort=score&ord=desc&f=docwrite&t=links&limit=5" 
   type="text/javascript" ><script>

This will have the effect of injecting the results directly onto the page.

Using the ccHost Query/Formatting Engine

Table of Contents

ccQFE Overview

Examples

In the Browser

Navigator tabs

Templates and HTML files (Native)

Templates and HTML files (AJAX)

Templates and HTML files (Universal/"Publicize")