Trex Docs

1. Trex is a server.

2. It runs on Linux.

3. It's written in JavaScript.

4. Everything in Trex is an outline.

Trex is Fargo's content management system.

Trex eats outlines, and Fargo is an outline factory. So they were made for each other, but in a loosely-coupled way.

When Fargo 0.80 shipped, we switched all the profile outlines on smallpict.com to be served by Trex. So all the features you see described here are now available in your profile outline.

These docs are for people who want to fully master the CMS that Fargo hooks into at a technical level. It will be possible to use Trex without understanding most of what's here. But if you want to create templates or complex websites, you need to understand what's here.

A lot of it is pretty dense stuff. Like most technical docs, you may have to read it two or three times before fully understanding it.

However we try to include examples that cut through the difficult stuff, and show you the results before you have to master the theory.

You now have a website in addition to all the other things Fargo gives you.

The website lives in your profile outline. Anything that is not in your "profile" sub-outline is accessible over the web.

You'll probably start to figure it out before you get finished reading the docs, and feel free to play around, you can't really hurt anything (we hope) but try to get all the way through the docs. It'll keep us from having to say, in a nice way, to RTFM. :-)

With Trex, we're introducing three new types: html, markdown and presentation.

You set them up the same way you set up any other nodetype, with the type attribute, in the Edit Attributes dialog. To be clear, here's a screen shot.

Here are examples of each of the three types: html, markdown, presentation.

The text underneath a node of type html is sent back as-is, without (much) processing. The exception is that macros and glossary entries (see below) are processed before the text is sent back.

Think of an html node as the equivalent of a text file in a server like Apache.

There's still a lot of information you don't have, but I always like to see a Hello World example as soon as possible to help give me something to think about while I'm reading the docs.

So here's a very simple web page.

Here's a screen shot of the HTML source for that page.

All the examples are available, in OPML, in this file.

All names in Trex are case-insensitive.

If a name would have a hyphen in it, drop the hyphen and innerCase.

For example, User-Agent becomes userAgent.

All Trex content comes from outlines, represented in OPML.

Every node in OPML can have attributes, which are sometimes called atts, if you're into the whole brevity thing.

Macros are delimited with percent signs inside angle brackets.

Example: <%somevalue%>.

There are two kinds of macros, those with parameters and those without.

Example: <%includeHTTP ("http://abc.com/")%>.

You already know about attributes, every headline has them. Some are defined by the software, and you can define your own.

All the attributes that are available when a page is rendered can be included in your page as macros, by enclosing them in <%brackets%>, as described above.

This one uses several macros:

It uses CSS to make the text on the page look a little nicer.

Like all Hello World apps this one is fairly contrived! :-)

Trex is good for web pages, as we have seen, but it's also good for web sites.

You can use the outline structure to organize the content the same way you'd use the file system to organize a site served by Apache, for example.

When Trex gets a request, each element of the slash-separated path is used to a headline in the outline hierarchy.

So if your site is helloworld.smallpict.com, and the path is /blog/2013/05/myFirstPost, we look for a top level item with the text blog, and a subhead of 2013, etc. The process of locating a node this way is called the walk.

At each step the name is normalized, all spaces are removed from the text to try to find the match.

We also look for a name attribute. You can use this feature to give a node a fixed name, allowing the text of the headline to change, without breaking URLs.

The walk goes through includes transparently.

At each step of the walk, we add all the atts from the node to the atts table for the request.

If we encounter two nodes with the same attribute, the inner one wins.

You can refer to any of the atts in the page as a macro.

When you're editing a named outline in Fargo, you'll notice that the eye icon is available in the left margin. It knows how to do the walk for any item in your outline, so you can always view a node by clicking the eye.

How to create a markdown page in Fargo.

1. Create a new headline and set its type attribute to markdown.

2. Enter some markdown text under the headline.

3. Then click the eye icon to view the rendered version of the page.

If all went as planned, you should see the Markdown rendering of the text.

Here's an example page with a standard Markdown demo document.

As before, the source text is in this OPML file.

We are using the Pagedown library, as in Fargo. This time the library is included in the server software, Trex.

Looking forward to seeing how you use it! :-)

When you're working on websites, you find there are bits of text that appear all over the place. Rather than having to type them every time, we have a structure called the glossary, that allows you to define them once and use them in many places. And if you need to change something, you can change it where it's defined and it automatically changes in all the places its referenced.

Let's say you want to define a re-usable bit that contains a link to your home page.

1. Create a headline at the top level of your outline called #glossary.

2. Indented under it enter a line that says "myhome" (include the quotes).

3. Indented under that, enter a line containing the link. Example:

There's a #glossary in the example file containing this item.

Now to use it, enter the text into one of your pages: "myhome" (again include the quotes). I've done that in Example 6.

Here are some facts about glossary entries:

1. They can include macros.

2. You can use them in markdown pages and html pages.

3. They can contain Markdown text and it will be processed in Markdown pages.

4. You don't have to use double quotes to delimit them. It's a straight string substitution. However it's probably a good idea to use some kind of delimiter so you don't get substitutions in random and unexpected places.

5. They are case-insensitive, so "MyHome" is the same as "myhome".

6. When you write about glossaries, you can include or leave off the #, but you can't leave it off in your outline. ;-)

A lot of websites have menus at the top of the page with links to other pages and other sites. Trex makes it easy to create and update menus, and share them among different pages.

To use the feature create a #menus headline at the top level of your outline.

One level under that enter the name of a menu. One level under that, provide the text you want to appear in the productname section of the menu, and beneath that a series of link nodes. These are the items that will appear in your menu.

Here's a screen shot of the menus table in the example.

When you want to associate a menu with a page or a group of pages, set the menuName attribute to the name of the menu you want to use.

There must be a <%menu%> macro in the template that the page is rendered with.

An example is here. And as usual the source is in this OPML file.

The menus we generate are compatible with the Bootstrap Toolkit navbar structure.

All of the head elements of the OPML file that the page comes from are available. For example, if the page has a title element, you would reference it as <%opmlTitle%>.

All of the documented OPML head elements are initialized to the empty string, so if they aren't present in the file your page came from they will be empty.

The address of the OPML file is <%opmlUrl%>.

The text of the parent node of the page, the one with the type attribute, is <%text%>.

All HTTP headers are available with the http prefix. If the name is hyphenated, the hyphen is not included in the name. So the User-Agent header is named <%httpUserAgent%>.

<%httpHost%>

<%httpPath%>

<%httpUserAgent%>

<%now%>

<%opmlDateCreated%>

<%opmlDateModified%>

<%opmlDescription%>

<%opmlLink%>

<%opmlLongTitle%>

<%opmlOwnerEmail%>

<%opmlOwnerId%>

<%opmlOwnerName%>

<%opmlTitle%>

<%opmlUrl%>

<%text%>

<%useBootstrap%>

<%useFontAwesome%>

<%useJQuery%>

<%useRules%>

<%disqusComments (groupname)%>

<%icon (name)%> -- name is the Font-Awesome name for the icon.

<%includeHTTP (url)%> -- includes the contents of an HTTP request in the page.

<%prevNextLinks ()%> -- generates links to the previous and next page in the hierarchy.

A template is an outline that contains an HTML wrapper.

The name of the template maps to a node type. So if you have a headline with type greenroom, Trex will look for a template with that name. If it finds it, it replaces the contents of the special <%bodytext%> macro with the text below the headline.

Trex has one built-in template as of 6/4/13, markdown. We will have a few more. You can override any built-in template.

Your templates are in a top-level outline called #templates. Its sub-heads are names of templates, and underneath each name is the template definition, which is an HTML wrapper.

Templates can contain macros, and can reference glossary elements.

If you want the text under the node to flow through the Markdown processor, add a method attribute to the headline with the value markdown.

Templates can contain rules. This feature is explained in the Rules section, below.

The example outline has a #templates section at the top level. It contains one template called greenroom.

This example uses that template. It has a method attribute of markdown, so the text passes through the markdown processor before being passed through the template.

A nodetype maps to the name of a template. So if I make something of type greenroom, as seen earlier, I can invoke the template by putting the type greenroom on a headline. When rendered it will flow through that template.

What flows through the template in the <%bodytext%> macro is determined by the method attribute. Possible values are: outline, markdown, presentation. But you don't always have to specify it, because there are defaults.

1. If the type is markdown, and no method is specified, the text flows through the Markdown processor.

2. If the type is presentation, and no method is specified, the presentation method applies.

3. If the type is html, no matter what the method, the text flows directly to the page. No template is used.

4. In all other cases, if no method is specified, the outline method is used.

5. Regardless of type, macro and glossary substitutions are performed.

The method attribute can be set as an attribute on the node or any of its parents.

If you're creating a custom template for pages that are going to be rendered with the outline method, you should include the <%useBootstrap%> and <%useRules%> macros in the <head> section of the template.

<%useBootstrap%>
<%useRules%>

They brings in styles and scripts that are used in rendering rules-based outlines. Your pages might not look very good without them.

Any line in an outline that begins with a # does not flow through to the page.

#hairColor "brown"

Then the name becomes an attribute and can be referenced as a <%hairColor%>.

It can also be used inside an outline appearing on a page, to set a value that's picked up as a macro in the page.

This feature is especially useful when an entire outline is a website, and there's no containing headline to attach attributes to.

It also makes it easy to group all your global values in one place, easily edited by the outliner,

We expect Trex to be used to create blogging systems. Comments are an important part of blogging, so we've built a special connection through macros to the Disqus commenting system.

You can include a comments section in a template through the <%comments%> macro.

By default it uses our Disqus group, but you can override that with the disqusGroupName attribute.

#disqusGroupName "yourgroupname"

The domain attribute makes it possible to host more than one website within a single outline.

1. Using your ISP's domain system, point a domain, say test.hello.com, to trex.fargo.io.

2. Set the domain attribute on any headline within your outline to test.hello.com.

When you go to http://test.hello.com/ in the browser, you should see the rendering of that headline.

As an example, I pointed fargotest.scripting.com to an example page.

Another nodetype that we have a built-in template for is outline.

Here's an example of an outline rendered using this template.

If you look at the source, you'll see that all we did was set the type of the node to outline, and Trex took care of the rest.

But there's a lot more to outline rendering, as you would expect from a CMS built around outlines.

And the key to that are what we call rules.

We have a case study that explains how to create a presentation.

Rules control how an outline is formatted. You can create a rule that says, for example, that all the headlines at level 1 and 2 are bold. You can set fonts, indents, spacing, alignment of text.

Rules can say that all headlines are expanded when the outline is displayed, or only the first two levels of headlines. And you can have a section expanded even if its siblings are not. A rule can say that only the headlines after a certain point are boldface.

Rules are to outlines what CSS is to HTML.

Whenever Trex sees a line that contains <rules> it processes that section as a rules set. Under the <rules> element are any numbers of <rule> elements. And underneath each <rule> are any number of rules.

Here's an example of a rules section:

A complete list of all the rules is on a separate page.

Rules are scoped. They apply only to the level they are present in. Outer levels are not effected by the rules at an inner level.

They accumulate. Inner rules override outer rules.

You can specify scope of a rule with the level and to attributes. Headlines at the same level as the <rules> element are level 1. Subheads of those are level 2. You can use the value infinity to cause a rule to apply to everything below a certain level.

All CSS properties are valid rules.

Glossary elements can contain rules. (As of 6/5/13, not implemented.)

Templates can contain rules. If the first item under a template definition is literally <rules> then Trex pulls those out of the template when rendering, and applies those rules before rendering the outline. They become the default for any outline rendered by that template.

There's a type, redirect, that's not like the others. It isn't rendered, there's no method for it. When the walk ends on one, we redirect to the HTTP address specified by the url attribute.

We generate a temporary redirect, HTTP code 302.

This example uses the Bootstrap Toolkit grid to arrange text on the page.

This example tries to include pretty much everything we have. ;-)

If you have questions about Trex, please join the smallpicture-web list.

You can post a comment here, but questions are more likely to be answered sooner on the mail list.

As we add features and fix bugs, we post docs to the worknotes site for Trex.

There's also a worknotes site for Fargo.

This section will develop over time.

Thanks to Jeffrey Kishner and Andrew Shell, our two most fastidious early testers of Trex, who put up with missing features and missing docs, and stuff that didn't work. And of course breakage! We always need the help of courageous users while we boot up a complex piece of software like Trex.

Thanks to Matt Neuburg who wrote the Frontier book for O'Reilly. As I wrote the docs here I thought often of Matt's writing. Especially the meticulous way he documented The Walk, which is such a central part of the website framework in Frontier, as it is a central part of the Trex today. It's the main event loop of a web server.

Dave Winer, New York NY, June 18, 2013