1. Purpose of the Tutorial

Most ccHost installations want more control over customizing the upload listing. In this tutorial we will customize the listing by making a gallery type view instead of the skin-simple (ccMixter type) default without creating a new skin.

This tutorial ties together several elements of the system for a specific goal: to customize the listings of uploads. We'll create a small template, invoke it from a Query request and put the results into a Navigation Tab.

2. Creating the Template

Place the XML below into a file called gallery.xml into your Skins Path.

<tal:block>
<!-- the line about is needed because valid XML always has 
     an 'outter most' tag -->

<!-- Below is our macro for displaying records in gallery format.
     You can put other macros in this file using the same metal:block
     syntax -->

<metal:block define-macro="gallery">
  <table>

   <!-- Use php to chunk the array into rows and columns -->

   <tal:block define="rows php:array_chunk(${file_records}, 3);" />

   <!-- Use phpTAL to repeat over the rows... -->

   <tr tal:repeat="col rows">

         <!--  ... and columns. The use of the variable name 'record' has a little
               magic in it because it will be used by other macros we invoke below -->

         <td tal:repeat="record col" style="vertical-align:top;width:33%;" >

            <!-- Just for decoration, we make a little border around the cell -->

            <div style="margin:3px;border: 1px solid blue;padding:4px; height:110px;">

              <!-- Artist avatar: -->

              <img src="${record/user_avatar_url}" style="float:left;margin:7px" />

                 <!-- Link and name of the upload: -->

                 <a href="${record/file_page_url}">${record/upload_name}</a><br />

                 <!-- Link and name of the artist: -->

                 by <a href="${record/artist_page_url}">${record/user_real_name}</a><br />
                 <br />

                 <!-- By using tal:condition we make sure the ratings will only show
                      for uploads that have been rated -->

                <div tal:condition="record/ratings_score">
                  
                  <!-- Here we invoke another macro elsewhere in the current skin.
                       That macro happens to expect an upload in a variable called
                       'record' which we defined above using the tal:repeat syntax -->

                  <metal:block use-macro="${ratings_stars}" />

                </div>

                <!-- Below we define a DIV but only if the upload uses samples (parents)
                     which are stored as an array -->

                <div tal:condition="record/has_parents">
                   Uses samples from: 

                   <!-- Iterate over the upload's parents. 

                        We use the sampled artist's name but link to the actual item
                        that was sampled
                   
                        The 'not:' section below is how we put in a 'comma' into the list, 
                        until the end of the list -->

                   <tal:block repeat="P record/remix_parents">
                      <a href="${P/file_page_url}">
                      ${P/user_real_name}</a><tal:block condition="not: repeat/P/end" >, </tal:block>
                   </tal:block>
                </div>

                <!-- This is CSS layout stuff: Since we float the user avatar, we want to make sure
                     the decorative div includes the space below it, so we clear it with a BR -->

                <br style="clear:both;" />

             </div>  
       </td>  <!-- END OF CELL -->

   </tr> <!-- END OF ROW -->
  </table>

  <!-- Add prev/next links -->
  
  <metal:block use-macro="${prev_next_links}" />

</metal:block>

</tal:block>

3. Test the Query

With the template and macro in the proper path we're ready to test what it looks like. See Using the ccHost Query/Formatting Engine.

http://your_install.com/media/api/query?tags=remix&m=galleryt=gallery.xml (pretty-url version)
http://your_install.com?ccm=media/api/querym=galleryt=gallery.xml

The 'page' Output Format

A query request typically specifies an output format. The default format is 'page' which tells ccHost to list the contents in a browser page using the current skin. If you specify a macro parameter, then ccHost will look for that macro in the current skin. If you want to use a macro not in the current skin (like our tutorial) then you have to specify a template parameter as well which refers to the template file to look in for the macro.

Query Explained

1. tags=remix - this specifies that we are only interested in uploads that are tagged remix. You can add other tags separated by a plus sign '+'. (e.g. tags=remix+downtempo
2. t=gallery.xml - 't' is the short form for the query paramater template. The file is assumed to be in your Skins Path.
3. m=gallery - 'm' is the short form for the query paramater macro.

4. Hook Up the Navigator

1. Go to Manage Site
2. Then Navigator Tab Sets
3. Next to the tab set media click on [Edit tabs]
4. Click on Click here to add another tab. Your new tab will appear at the bottom of the list of tabs.
5. Fill out the fields and select Query for 'Function' and under Data type in our query tags=remix&t=gallery.xml&m=galler.