librelist archives

Re: [nesta] Categories behavior unexpected

From:

Graham Ashton

Date:

2011-06-18 @ 22:40

On 17 Jun 2011, at 13:23, Nathanael D. Jones wrote:

> I've been wrestling to get categories to work. I'm trying to use them to
display release notes in a sorted manner.

One page per release, with each page in the releases category documenting 
a version?

> All the files are in the /content/pages/releases folder, and each one 
has 'categories:releases' in the metadata.
> 
> I have to admit, I initially expected them to work like tags.

They do, to an extent, if that's how you want them to work. They're better
than that though.

> My current understanding of them is below:
> 
> a) You must specify the category in the metadata of each page

Correct. I think I need to write a fairly clear explanation of this and 
add it to this section of the docs:

http://nestacms.com/docs/creating-content

> b) The page must also be in a root-level subfolder that exactly matches 
the category name. (seems redundant if we have to also specify the 
metadata)

I'm not totally sure what you mean here, but I suspect this is wrong.

If you had files that look like this:

  content/pages/potato.mdown
  content/pages/foo/index.mdown  (equivalent to pages/foo.mdown)
  content/pages/foo/bar.mdown
  content/pages/blog-post.mdown

then you could assign any other page (irrespective of where it lives on 
disk) to the following categories:

  potato
  foo
  foo/bar
  blog-post

In other words, a category is just the path to any page on your site, 
relative to the root URL. A page can be assigned to multiple categories, 
so this would be a perfectly legal thing to say (in any page):

  Categories: potato, foo, foo/bar, blog-post

Structuring your URLs is up to you, so putting pages within their main 
category's folder is optional, but will help your visitors. The URL is 
part of the web's UI, after all.

If you want to control the order in which a category page lists the pages 
that have been assigned to it, you can specify the sort order with the 
priority. See the metadata reference for more on that:

http://nestacms.com/docs/creating-content/metadata-reference#categories

I'm not totally comfortable with the way priorities work (it can be fiddly
to re-order things), but I couldn't come up with a better API and needed 
the feature for Nesta's own site.

> c) Only the parent 'category' page can actually list the articles based 
on category. This page must be physically named the same as the category.

To iterate over the pages that are assigned to a category page, you need 
to ask the Nesta::Page object for the category page what the pages are, 
yes.

But that doesn't make it difficult to do. I just wrote this app.rb file 
for Stefan in another thread, that defines a helper method you can call 
from within any .haml file (either in your content folder, or in a view in
your views folder):

module Nesta
  class App
    helpers do
      def pages_in(path)
        Nesta::Page.find_by_path(path).pages
      end
    end
  end
end

See that thread for more context.

When I write some docs on how to use categories (in which I should clearly
explain the rationale, and why they're so much better than tags) perhaps I
should include this snippet of code...

> These restrictions make categories very single-purpose and not very re-usable.

Come back to me if you still see it this way, as if categories don't cover
it I'd be interested to understand more about how you'd like to use them.

> (Pardon my ruby, I'm a newbie).

There was nothing wrong with it.

Cheers,
Graham