Docs Home

Install

Upgrade

Troubleshoot

Customize

Admins

Devs

Content

Query

Templates

Commands

Skins

ccHost always uses the Query API to display uploaded user content. Whenever you see any information about user content in any context, it is being run through the query engine.

The first step in a query is to formulate the request. The request has two parts: 1) what part of the content you are interested in and 2) a template to use when displaying the results. The query engine performs a database query that satisfies the query and hands the results off to the the template engine. The template system uses the template requested to do a merge of the data with a specific format and layout. That format might be an RSS feed, an HTML list of links, a Flash (tm) MP3 player with a playlist attached or it may involve filling up a whole page of information about the results.

In ccHost, the most common of this last category, the page-oriented query scenarios, are abstracted to the following:

• An upload page is the detailed view for an upload. An example of this page at ccMixter.
• The upload listings is the default page listings for a query result involving multiple records. Here is an example, again, at ccMixter.
• The query browser is an interactive view that allows users to easily filter and sort an abbreviated version the listing. You see this in action at ccMixter's remix browser.

Upload Page

The 'upload page' is the template that ccHost will use when someone has requested to see the details of upload using the files command. For example:

http://ccmixter.org/files/victor/1134

It is used as the link behind every upload title in the system.

The query API equivalent is

<your_instllation_root>/api/query?t=list_file&ids=<upload_id>&title=<upload_title>

The list_file template name is not the name of physical template, but is a configuration setting that maps to the physical template to be used for the upload page.

Admins

You can tell ccHost which template to use for the list_file template name by browsing to admin/skin/settings and selecting from on of the options under Upload Page Format.

The skin developer of your current skin profile has probably pre-selected a specific upload page because of formatting considerations so a different choice might not be a good fit for your current skin profile.

Skin/Template Writers

In most cases this url is available in a record as the file_page_url field:

 // create a list of links to the upload page
 %loop(records,R)%
     <a href="%(#R/file_page_url)%"> %(#R/upload_name)% </a><br />
 %end_loop%

In order to create your upload page template you can use the one based on the custom query template walk through's 'details' template in the Hello World example. Make a copy of that and put into <local_files>/skins/custom_upload_page.tpl

Or you can ccskins/shared/formats/upload_page_shared.tpl to <local_files>/skins/custom_upload_page.tpl (Optionally copy the <style> block from ccskins/shared/formats/upload_page_wide.php or the narrow version if that's what you prefer)

Either way, mark the template as being of page type with the following header:

   %%
    [meta]
       type = page
       desc = _('My custom upload page')
       dataview = upload_page
    [/meta]
   %%

• type = page tells ccHost this template is available for use as the Upload Page (but doesn't select it, you'll do that later)
• The desc is strictly for your and the site admins' benefit so you can recognize this template.
• We select dataview = upload_page because there are many fields not in the default dataview that will be helpful when displaying all the details of the record

Don't forget to select your template in the admin screens mentioned above.

Developers

In order to hook the display of upload page regardless of skin configuration you have your chance to do at the beginning of the session, after the environment has been configured. Place the following file in <local_files>/lib/init_app_hook.php

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

 function upload_page_hook()
 {
     global $CC_GLOBALS;

     // keep a copy of the admin's version
     $CC_GLOBALS['real-upload-page'] = $CC_GLOBALS['list_file'];

     // set the mapping to our hook
     $CC_GLOBALS['list_file'] = 'YOUR_LOCAL_FILES/skins/upload_page_hook.php';
 }

Then create the hook file at <local_files>/skins/upload_page_hook.php

 <?      
     // $A is an array of the context variables passed in to the template
     $record = $A['records'][0];

     // Your $record munging code goes here

     // $T is the template object that represents this session:
     $T->Call('real-upload-page');
 ?>

Upload Listing

The 'upload listings' is the default template when display the results of query involving multiple records. It is used by query engine when the format is page (which is the default format).

For example, the default query with no parameters:

api/query

Actually expands to:

api/query?t=list_files&f=page&sort=date&ord=desc

The list_files template name is not the name of physical template, but is a configuration setting that maps to the physical template to be used for the upload listings.

The template is used throughout ccHost, typically mapped to 'friendly' versions of urls. Below is a table of some of the uses of the upload listings template.

Example	Query equivalent
/tags/<tag_list>	/api/query?tags=<tag_list>&title=Tag: <tag_list>
/people/<user_name>/uploads	/api/query?user=<user_name>&title=<user_real_name>
/files	/api/query?title=Latest Files

Admins

You can tell ccHost which template to use for the list_files template name by browsing to admin/skin/settings and selecting from on of the options under Upload Listing Format.

The skin developer of your current skin profile has probably pre-selected a specific upload listing because of formatting considerations so a different choice might not be a good fit for your current skin profile.

Skin/Template Writers

In order to create your upload listings template you can use the one based on the custom query template walk through's 'master' template in the Hello World example. Make a copy of that and put into <local_files>/skins/custom_upload_listing.tpl

Or you can copy ccskins/shared/formats/upload_list_wide.tpl (or the narrow version) to <local_files>/skins/custom_upload_listing.tpl

Mark the template as being of list type with the following header:

   %%
    [meta]
       type = list
       desc = _('My custom upload listing')
       dataview = upload_list_wide
    [/meta]
   %%

• type = list tells ccHost this template is available for use as the Upload Listing (but doesn't select it, you'll do that later)
• The desc is strictly for your and the site admins' benefit so you can recognize this template.
• We select dataview = upload_list_wide because there are many fields not in the default dataview that will be helpful when displaying all the details of the record. The upload_list_narrow might also work for you because it will be have better performance characteristics but fewer fields available.

Don't forget to select your template in the admin screens mentioned above.

Developers

In order to hook the display of upload listings regardless of skin configuration you have your chance to do at the beginning of the session, after the environment has been configured. Place the following code in <local_files>/lib/init_app_hook.php

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

 function upload_listing_hook()
 {
     global $CC_GLOBALS;

     // keep a copy of the admin's version
     $CC_GLOBALS['real-upload-listings'] = $CC_GLOBALS['list_files'];

     // set the mapping to our hook
     $CC_GLOBALS['list_files'] = 'YOUR_LOCAL_FILES/skins/upload_page_hook.php';
 }

Then create the hook file at <local_files>/skins/upload_listing_hook.php

 <?      
     // $A is an array of the context variables passed in to the template
     $records = $A['records'];

     foreach( $records as $record )
     {
       // Your $record munging code goes here
     }

     // $T is the template object that represents this session:
     $T->Call('real-upload-listings');
 ?>

Query Browser

The query browser is an interactive screen that collects query parameters from the user, executes the query, then displays the results all on one screen. This allows users to quickly filter and sort through the uploaded user content.

The query browser's default command is simply browse, for example: http://ccmixter.org/browse However admins can create options that control which filters are visible and the template to use for the content display. These options sets can be appended to the browse command browse?optset=<option_set_name> and admins can 'hide' them in navigation tabs or menu options.

You can also specify starting queries. For example browse?tags=rock+drums or browse?user=teru&reqtags=remix

Admin

To create an option set:

• Browse to admin/browse
• Click on 'Add Option Set'
• Fill out the form

No doubt, a lot of experimentation will be involved here as you get familiar with what each value does.

Option	Notes
Name	The 'name' is important because it will be used in the browse URL's 'optset' parameter. If no optset parameter is in the URL then the optset called 'default' is assumed
Template	Select the template that will be used to show results
Style	Select the style sheet
Def. limit	Enter the initial amount to display in the results area
Playlist but.	Check this if you want to have the 'Save to playlist' button this only applies to sites with playlists enabled).
Req. tags	These tags will be added to every query made, the user can not edit these.
Types	Click on the "Edit types" to bring up a popup that allows you edit what the user will see in the 'Types' select box and what tags they map to.
Filter on User	Check this to include the 'User' look up field
Filter on License	Check this to include the 'License' look up field

Skin/Template Writers

Add a style choice

To add a style sheet to the list of 'styles' in the admin options screens:

1. Copy ccskins/shared/css/qbrowser_narrow.css to <local_files>/skins/css/my_browser_styles.css
2. Edit the 'desc' line at the top to something meaningful to you
3. Optionally edit the css import urls

The most important thing is that the meta information at the top of the style sheet includes type = query_browser_styles so the query browser admin screen can find it.

The top of your css file should look something like:

 /*
 [meta]
   desc =  _('My wizbang query browser style')
   type = query_browser_styles
 [/meta]
 */

Add a listing template

To add a listing choice to the list of choices in the admin options screens:

• Copy ccskins/shared/formats/simple_qbrowser.tpl to <local_files>/skins/formats/my_browser_results.tpl
• Edit the 'desc' line at the top to something meaningful to you
• Optionally change the 'dataview' line to 'default' instead of 'playlist_line' which has limited information per record.