Creating components

What is a component?

A component is a reusable element that can be used when building evaluations' templates. A few sample components, including templates to render tweets, Twitter users, and searches on Twitter are included in Clockwork Raven, but it's easy to add your own.

Who can add components?

You must have access to the server running Clockwork Raven to add templates, and you must be able to restart Clockwork Raven. We plan to add support for user-created templates that can be added via the Clockwork Raven web interface in the future.

How do I add a component?

There are three steps to creating a component.

Step 1: Creating the HTML template

Create a template for the HTML. Out of the box, ERb and HAML are supported, but you can add other templating engines to your Gemfile and then use those if you like. Put your template in app/views/components/ and call it _<name>.html.haml for a HAML template or _<name>.html.erb for an ERb template (note that <name> is whatever you want to call your template).

Your component will be able to take parameters from the user when the user uses it an a template. You can access these parameters with data['<parameter name>'].

If your components needs to insert a Javascript library or CSS styles into the head of the page, use the require_header helper. require_header takes a name and a block, and will inject the block into the page header exactly once, even if the user inserts multiple copies of your component into their template. Make sure your name is unique: there can only be one header for a given name. Note that jQuery and Bootstrap are always included -- no need to add a header for them. Also note that these components are sent to Mechanical Turk, you any files you reference (e.g. Javascript files) will need to accesible from outside Clockwork Raven.

Here's a sample ERb template:

<%# app/views/components/_my_comp.html.erb %>
<% require_header :my_awesome_header do %>
  <script type="text/javascript" src="static.mywebsite.com/js/some-script.js"></script>
<% end %>
<p>
  The value of the first parameter was <%= data['param1'] %>
</p>
<% if data['param2'] %>
  <p>
    The value of the second parameter was <%= data['param2'] %>
  </p>
<% else %>
  <p>
    You didn't provide a second parameter.
  </p>
<% end %>

Step 2: registering with the manifest

Add an entry to the manifest file, app/views/components/manifest.yml, for your template. It's pretty easy to see the format from that file. You create an entry with the same name as your template file (but without the leading _ or the trailing .html.erb. The name should be a symbol (start with :). That entry has a :desc entry with a friendly description of your component. It also has a :vars entry which lists the parameters your component expects. Each entry in :vars has a description (:desc) and a boolean (:required) to indicate whether the parameter is required. Here's what the manifest entry would look like for the above component:

:my_comp:
  :desc: My Awesome Component
  :vars:
    :param1:
      :desc: First parameter
      :required: true
    :param2:
      :desc: Second parameter
      :required: false

Step 3: Restart the server

You'll need to restart your server and your Resque workers to pick up the new component.

Made an awesome component?

Made a really awesome component? Submit a pull request or send us an email and we'll see about including it in Clockwork Raven if we think it'll be useful to many users.