Fragmenta Basics

The essential unit of Fragmenta is a fragment – at its most basic this is a single text file. Below are the contents of a very simple fragment.

Title :: Fragment title
First line of text
Here is another line

The text file can have various fields inside it; the fields are delimited by two colons, so the first line in the example file above defines a Title with the value “Fragment title”. Each fragment is given a title and some text – if no fields are specified on a particular line, that line is treated as part of the Text field. If no title is specified, the fragment name is used. For the fragment show above, using the default template the HTML output would be

<h2>fragment title</h2> <p>Here is the fragment text</p> <p>Here is another line</p>

These fragments are arranged in folders. When generating a website, Fragmenta runs through the source folder (and all folders within it), and inserts all the fragments for that folder into a template within the CPStyles folder (see Templates for more details on how this is chosen). It generates an Index.html file for each folder, containing the fragments within that folder. Note that you can hide fragments if you wish by giving them a ‘List’ field equal to ‘No’. Each text file can be repeated several times throughout the website (making it easy to specify and edit things like page footers without having to edit HTML). For more details about fragments and Templates, see the links in the Topics box at the top of this page.

Encoding

You should always save your text documents as UTF-8, to avoid problems with any foreign accents in the pages displaying incorrectly in browsers. If you use an application like Textmate it will save them in this format by default. If you use TextEdit or another editor, you can set the format it saves in by adjusting the Preferences for that editor.

Standard fields

Although you can add as many fields as you like to fragments, certain fields are used by Fragmenta and have special meaning. You can (optionally) add as many of the folllowing as you like to a fragment :

• title :: The fragment title (defaults to file name)
• date :: The fragment date – given as a string of form 12 December 2009 (defaults to file date)
• id :: The fragment ID used as id of HTML element (default based on file name)
• list :: Should this fragment be listed in the page? (it can still be listed manually if list :: no)
• view :: The name of the template file used (can include path in views folder, e.g. fragment/intro )
• order :: The sort order – can be used to sort fragments on a page (default sorts on title)
• textile :: Should this fragment use Textile to format? (defaults to yes, set to no if not required)

Fragment Images

Picture files will be copied along with the folder to the destination (which is a folder named ‘output’ in the same directory by default). For more details on placing Pictures on your website, see Images. You can also create fragments just using images, rather than text files, for each fragment.

Note that a picture with the same name as a text fragment will be treated as associated with that fragment, and placed together with it if requested in the template. If you don’t have it placed in the fragment template, it won’t appear.