Title: Core Concepts
Page: core-concepts

This chapter introduces the techniques and concepts Nukumi2 users
need.  After an overview of TopicTrees, the most fundamental thing to
Nukumi2, Clotheslines and Tangerine templates will be explained.

Reading this chapter is very important to grasp Nukumi2, read it
carefully and don't hesitate to skip back to it later on.


## TopicTrees

A TopicTree is essentially a hierarchic structure, just like your
filesystem: But instead of directory names, we say "topics" and
instead of files we say "objects".

Every topic contains zero or more objects.  In case of Nukumi2, these
objects will probably contain the main content of the site.
Besides, topics can have a name and a description.

Topics appear in two kinds: absolute and non-absolute.  Absolute
topics are like a directory names, while non-absolute topics are more
like wildcards.

Samples for absolute topics and their interpretation:

	/books			# All things about books

	/books/ruby		# Ruby-related books

	/books/ruby/2004	# Ruby books that appeared in 2004

	/category/useless	# All things that are categorized as
				# "useless".

Samples for non-absolute topics:

	books			# All things whose topics contain "books"
	
	/books/*/2004		# All books that appeared in 2004

	/category		# Everything that is categorized

TopicTrees are essential to Nukumi2.  Numumi2 could be described as a
*topictree publisher*, as it takes the path given in the URL and maps
it to a topic whose objects get published then.


## Clotheslines

TopicTrees can contain lots of different objects, but usually, this is
not needed.  Usually, Nukumi2 stores objects of class Nukumi2::Entry
there, that is, Blog entries.

Bloggers have been known to have pretty varying taste, so there are
many different text formats they write in.  From plain old text and
HTML over various plain text formats (Dubbed Clothes in Ruby speak)
and people that even blog writing `.doc`s, everything exists.

Nukumi2 basically supports all of these.  Nukumi2 entries are totally
independent of the text format you use.  However, there must be some
way to tell Nukumi2 how to actually convert the input data to the
requested output data.  This is done using Clotheslines.

Clotheslines chain multiple *filters* together.  These filters need to
respect to the (only informally defined) Clothes API.  See Appendix A
for details on how to write your own filters.

Various filters you can use include:

  * BlueCloth: Convert text marked up using Markdown to HTML.

  * RedCloth: Convert text marked up using Textile to HTML.

  * RubyPants: Educate quotes, making \"foo\" look like "foo".

  * *(XXX add more)*


## Templating with Tangerine

Nukumi2 uses by default the Tangerine templating engine.  All the
default templates are written in Tangerine.  In case you don't like
Tangerine or already have your templates in a different format, you
can change the complete templating system as well.

Tangerine, as used by Nukumi2, uses directories to store the
templates.  Templates reside in the directory
<code>templates/<var>flavor</var>/</code>, where <var>flavor</var> is
the kind of output format, for example `html`, `rss` or `atom`.

In this directory, there should be at least two files: `content-type`,
which simply contains a line for the HTTP `Content-Type:` header and
`page`, which will include the main page template that gets called on
every request.

Tangerine templates are not totally codeless, they include minimal
representation logic.  Ordinary users should do fine if they simply
adjust the non-code parts of the templates; if you want to get deeper
and totally customize Nukumi2 to your needs, you'll need to know about
the exact semantics of Tangerine, described in Appendix B.

Overriding certain parts of the template is possible of course, see
"Template Overriding" for that.