Overview

This tutorial will walk through the creation of a feature for ccMixter.org that was added by taking full advantage of template engine and Query API. If you just want to download and install the finished project or want to follow along in your own version of the code you can jump down to the download section.

The idea was to create a quick-and-dirty version of a feature of other remix sites that allow artists to embed "remix me" widgets onto their site. (Typical example is from the Trifonic site.) Those sites use fancy Flash (tm) widgets, but here we aren't aiming so high. We just want a simplified version of that, something that leads remixers to the stems and starts them down the road to uploading.

It might be of interest to developers that from concept to check-in this feature took less than four hours to put together and install on the site. That's because it was all done with the template/query extensibility, how the majority of features on ccMixter are already implemented.

Feature Requirements

For this feature we need an HTML snippet that will:

• List the remixes of a given artist with the ability to stream, download and find out more about the remix.
• Show a link for downloading stems
• Show a link for uploading a remix.

This last step is a little tricky. What other sites do is direct users to a screen that allows them to register an account with the site in the same transaction as upload their remix. We won't be quite so fancy and just create a screen that directs users to either create an account or, if they already have an account, submit the remix.

Implementation Spec

To create this feature we will create several templates and use the Query API to call them. Here are the templates we want to make:

• A Remix Me template - this will be embedded into the user's blog or web site. It will have to be 'straight' HTML and assume nothing about styles or layout.
• A get my stems template - when the user clicks on 'get my stems' this will popup a window with a list of download-able samples from the artist.
• A upload my remix template - this will live on the ccHost installation site and direct the remixer to either the login/register screens or the 'Submit Remix' screen depending on whether they are logged in already.
• In addition to those we'll create a page on our installation with instructions for our users about how to install the embedding's snippets into their blogs.

Regarding this last page: it just so happens that the way we will craft this feature it will actually appear in the list of optional embedding in the publicize feature, so it's technically not needed, but the feature is just sexy enough that we'll create it's own instruction page, hopefully inspiring ccMixter users to give it go.

Making the Templates

Embedding Template

The template we embed onto the user's blogs will be the most complicated and most important so we'll start there.

What we're aiming for is a query that will look something like:

 api/query?t=remix_me&user=<user_name>

So that we can we can wrap that in a <script> tag on the user's blog:

 <script src="<query_url>?t=remix_me&user=<user_name>&f=docwrite"></script>

Making it 'publicize' Compatible

ccHost already has a feature for generating these types of embedding at the publicize command. (You can see it action at ccMixter.) If we do this feature right, it will just slip into the 'format' drop down.

In order to this we need to have certain things in place:

• The template must reside in a directory called formats below our skins directory.
• The meta section of the template just specify type = format
• The same meta section must have a 'desc' field with a one-line description
• The template should be amenable to either remixes by our user or of our user.

Unfortunately this last point is a drag because, really, we only care about the remixes of our user. Ah well, the template will act a little funny but we'll make up for below.

Since this feature is about remixes of a given artist and it really doesn't make sense to do it for remixes by the user, we'll also specify that remixesof parameter as a requirement of the query.

So given that, we put the following shell of the template into <local_files>/skins/formats/remix_me.tpl:

 %%
   [meta]
     type          = format
     desc          = _('Remix ME (use with Other Peoples Remixes...)')
     required_args = remixesof
   [/meta]
 %%

Displaying the remixes

We'll want to loop over the records and display the remixes of by name and remixer. Because we are embedding into random blogs we want to keep everything self contained (no calls to CSS files, no outside scripts and the safest layout mechanism possible. That means (forgive me) <table>. We'll also want to control the overflow so we'll make extensive use of the %chop% template macro when displaying names:

 <table cellpadding="0" cellpadding="0">
   %loop(records,R)%
     <tr>
        <td>%chop(#R/upload_name,23)%</td>
        <td>%text(str_by)% </td>
        <td>%chop(#R/user_real_name,12)% </td>

 %end_loop% </table> You're now ready to take a peak. Pick a user that has been remixed in your installation and try: api/query?t=formats/remix_me.tpl&remixes=<user_name> (See [Cchost/concepts/Templates#Embedded_Macros_vs._Paths|why you need the .tpl extension].)

Customizing the Dataview

Until now we're using the default dataview but since we want a 'download' link to the remixes we'll a different set of columns.

Download the Source

The source for the latest version of feature is available scattered about the ccHost SVN repository. The version that this tutorial uses is available from (ZIP).

Installation instructions:

• Unzip the source ZIP file on your local directory and copy the files to <local_files>/skins maintaining the directory structure.
• Log in as admin to your ccHost installation (if not already)
• Click on Manage Site, then Banner and Footers, then Banner Text, Footers, etc.
• In the header of the form click on clicking here.
• Type in the text: 'remix-me-title' (without the quotes)
• Click on 'Submit' (this should bring you back to the 'Edit Banners...' form).
• Again, in the header of the clicking here
• Type in the text: 'remix-me-logo' (without the quotes)
• Click on 'Sumbit'
• Now at the bottom of this form you should see the new fields you just enetered.
  • For the title enter something like 'Remix Me' - this will be the text that is displayed in the embedding on the users' sites.
  • For the logo enter the fully qualified URL to any logo you want to appear in the embedding. This is optional and you can fill it in later.

Now your "remix me" feature is ready to go. You should see it as an option when you browse to publicize/<user_name> and also when you browse to api/query?t=remix_me_embed&user=<user_name> which you put into your menu for registered users.