sapwood

Resources

Resources are a new addition to Sapwood as of v1.3. They are content-rich metadata that support a content-rich, many-to-many relationship with pages.

In other words resources provide the missing link to be able to create a many-to-many association among pages.

A Little Background

To give you some background, I ran into two scenarios in which the only thing holding someone back from using Sapwood was that they couldn't have content-rich associations among pages.

In the first scenario, all the site needed were tags. They had a blog and needed to tag articles. That was simple enough, and I had planned to add a rigid tag feature in 1.3 or 1.4 anyways.

The second scenario followed quickly. That site needed recipes, where recipe would have been a template, and the recipes its pages. Each recipe was to have many ingredients. There were two quirks:

First, the ingredients needed to link to one another such that there could exist a view that would list all the recipes one ingredient had. This meant that the traditional one-to-many relationship would not suffice (because the ingredient needed to be associated with more than one recipe).

Second, while each ingredient needed that link, the association between the ingredient and a recipe would have a varying quantity. In other words, not only did the ingredient need unique data, but the association between the recipe and the ingredient also needed unique data.

In Rails, this is a straightforward problem. We would create a model called RecipeIngredient and it would hold the association along with the quantity.

To build it into Sapwood was a challenge, but it worked! Now, resources handle that many-to-many association for you. And, what's better is they eliminate the need for any hard-coded tag feature, because you get to determine when and how you want to use tags.

Resource Types

Adding resources works very similarly to templates. In that way, a resource is to a page as a resource type is to a template.

So, the first thing you need to do is define your resource type, say Tag.

Creating Resource Types

You'll notice that resource types act very similarly to templates, with fewer features.

Title & Method Name

The title is an arbitrary name for the resource type, although it is used to generate the method name if you leave that blank. For example, Tag would be your title and then tag would be filled in as your method_name.

The method name is used to access the resources of this resource type from any given page. See Accessing Resources below for more info.

Show View, Order Method & Direction

Just like templates, you can choose for resource types to have a show view. Here's how it works:

If there is no root-level page with a slug matching the resource type's method name, then there will be a view at yoursite.com/[plural_method_name] which is meant to be the index view for all resources of that resource type. And your view template should follow that structure.

For example, if you have a Tag resource type with a show view, then you will have a view at yoursite.com/tags, which will look for a view file named tags.html.erb.

Furthermore, each resource created for that resource type will be available at yoursite.com/[plural_method_name]/[resource_slug], assuming, once again, there is no page with a matching path.

This view looks for the singular method name. So, in our example, this would render a tag.html.erb view file, while your current resource would be the specific tag that had a slug matching the last URL segment.

Don't forget, Sapwood leaves this maintenance up to you. If you have a Tag resource, it's up to you to make sure you don't have a Tag page at the root of your site.

Linking to Templates

Access to resources are set on templates. For example, if you have an Article template, you might want to make a Tag resource available to it. You do this in the template's settings.

If set, for each resource type a template has access to, the page of that template will get a new tab where it can associate itself to a particular resource. This is also where the association fields are filled in, if necessary.

Creating Resources

Remember, Tag was a resource type. But, creating a specific tag, like red, would be done under the resource type in the Resources section of the builder. This is the only place they can be added (for now).

Resource Fields

Resource fields are the fields set on the resource itself, not on the association between a page and a resource.

Like templates, resources have protected fields. But, really there are only two: title and slug. We use the slug to generate view URLs if necessary.

So, for example, if you have an Ingredient resource type, you might want a URL field for that ingredient, pointing to some wiki about the ingredient.

Association Fields

In contrast, association fields are the fields set on the link between the page and a resource. Sometimes, like in the case of a simple tagging system, you won't need any. Other times, like with ingredients, you might need extra data (where an ingredient might want a quantity field).

Using Resources

When working in a view template, you know you have the current_page object. That object has metaprogrammed methods on it relating to any resource to which it has access.

For example, if an article is allowed to have tags, then you can get to a particular article's tags by calling current_page.tags.

What you are actually returned is an object representing the association, not the resource itself. However, the association has access to its resource's methods. So, if you have a recipe and you want its ingredients, this will work:

<% current_page.recipes.each do |r| %>
  <li>
    <%= r.quantity %>
    <%= content_tag(:span, r.title) %>
  </li>
<% end %>

Notice that this is accessing quantity, which would be an association field, and title, which would be a resource field.


As usual, if you have any questions about resources, ask me.