Cchost/developer/Custom Listings

This article describes a DRAFT under discussion; contents, specifications and recommendations may change until the public discussion is complete.

One of the first things that many sites want to customize is way that uploads listings and upload pages appear on the site. The typical scenario for the first 4 versions of ccHost goes something like this:

• A developer does some gifted reverse engineering and finds the ccHost default listing page and hacks away directly at that template.
• A short time later that same developer is filled with regret.

In ccHost 5 we tried to make it a less frustrating task with better results. The upload pages and upload listings are actually just query API templates. Therefore, before you get any further, we strongly recommend that do the query template walk through. This should take you about 20 minutes, but it will be well worth it and make the job of making your custom listings go much smoother.

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. This section explains how to create your own version of that and hook it up into the system.

Step 1. Create a Template

Creating from scratch

Starting you own version from scratch may be more work up front, but you will have a lot more control over the output of your own site this way. If you are familiar with HTML/CSS it will be much better and easier than you may think. Just sayin.

To start your own customized Upload Page, follow the instructions in the custom query template walk through to create a new template based on the 'details' template in the Hello World example.

OR Hack the system Upload Page

Even if you plan on hacking through this, we still highly recommend spending 20 minutes with the custom query template walk through to understand the architecture of how ccHost is displaying records.

The absolute worst thing you can do is hack directly on one of the files under ccskins. That will never pay off. You have been warned.

• Copy 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) and put that near the top of the file.

Step 2. Edit the meta header

Make sure you have the following to the top of the page:

   %%
    [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

Step 3. Select your Upload Page template into the system

You need to inform the ccHost configuration that you intend to use this page as the template when a user browses to a upload using the files command.

• Browse to <your_installation_root>/admin/skins/settings
• At Upload Page Format select My custom upload page
• Click on the Submit Basic Skin Settings button.

Step 4. Confirm your template is setup properly

Browse to <your_installation_root>/files/<user_name>/<file_id> to make sure it's your template that is set to that command.

HINT: Any files link will do, like in the Sidebar Extra 'Latest Uploads'.

Step 5. Fill out your template

Using the %inspect(#R)% macro syntax you can see what variables are available for display