How to Create a Web Site with RubyFrontier

Personally, I think RubyFrontier is pretty simple, but that’s because I’ve been using Frontier for so long that I’m used to it. If you’re not acquainted with Frontier, you might choke at first on the technical details of the RubyFrontier documentation. So here, in the interests of just getting you started by hook or by crook, are the actual steps that I take when I set out to write a new Web site with RubyFrontier.

(Before reading, you really should watch the screencast. One moving picture with narration is worth a lot more than 1000 words!)

Think. Plan ahead a little bit. Can you envision at least a few pages of the Web site and what each page will be about? This will be a more satisfying experience if you can start with at least two or three pages and have them refer to each other.
Create the source folder. In TextMate, tell RubyFrontier to make a new Web site.
Configure #ftpSite.yaml. Okay, you’re now in the source folder’s TextMate project. Immediately, look at #ftpSite.yaml. Change the :folder entry to be the path to a folder on your hard disk where you want the Web site created when you generate pages.
Test. Immediately render the firstpage.txt page object that comes in your new RubyFrontier source folder: select the page, and choose RubyFrontier > Publish Page. The rendered Web page should appear in your browser. Make sure it’s being saved where you expect it. Even better, select this page and choose RubyFrontier > Publish Site. Examine the default site to see how some of its features are implemented; these are features you may want to imitate.
Make some page objects. Create some .txt files at the same level as the existing firstpage.txt. You can delete firstpage.txt and the other existing pages now if you wish. Or, keep them around until you’ve understood the features they demonstrate.
Make titles. Immediately, give every .txt page object that you just created a first line #title directive. Ideally, every page object should have a unique filename and a unique #title, though this is not required. So, for example, the first line of this page object is:
```
     #title "How to Create a Web Site with RubyFrontier"
```
Pick an HTML strategy. Stop and decide how you want to code HTML for your pages. Are you going to hand-code HTML? That’s fine; you can take advantage of TextMate’s HTML editing to help you. Or would you prefer to write text and let the text be turned into HTML for you by Markdown? That’s fine too; TextMate includes Markdown (and SmartyPants), and the default pageFilter and finalFilter (scripts in the #filters folder) are set up to let you use them. Or perhaps you’d like to use kramdown (I recommend this instead of Markdown, now that it has matured)? Or possibly you want to hand-code your HTML, but abbreviate it by using Haml? The existing pages in the default site are all set up for you to do any of these, and show you how to get started. (Or perhaps you have some other transformative engine you want to use to generate HTML? Fine, but then it’s going to be up to you to create a mechanism for implementing this.)
Write. Create some content in each of the pages.
Make links. Pages can refer to each other via links using their simple filenames or titles. For example, suppose a page object file is called otherpage.txt. Then, in pure HTML you can say <a href="otherpage">this kind of thing</a>; in Markdown or kramdown you can also say [this kind of thing](otherpage).
Keep testing. As you work, keep saying RubyFrontier > Publish Page to check that things are going okay. If a link to another page fails, it might be because you’ve never published it (a page doesn’t go into the autoglossary until it is published). Totally ignore the look of the page! You’ll fix the CSS and the template in later steps. Oh, one more thing: To regenerate every page of the site, choose RubyFrontier > Publish Site.
Images. To add an image to a page, at first, keep it simple. Put the image file in the #images folder. In the page object, say (if, for example, the image file is called myimage.png):
```
      <%= imageref("myimage") %>
```
CSS. Okay, by now you are probably becoming heartily sick of the default look of the pages you’re generating and you’re ready to fix the CSS and the template. For the CSS, create a .css file in the #stylesheets folder. Let’s suppose you call it normal.css. To make a page use it, insert at the start of the page the directive line #linkstylesheets "normal", or to make all pages use it, add this line to #prefs.yaml:
```
     :linkstylesheets: normal
```
(The value, “normal”, must match the name of the stylesheet file.)
Template. Editing the template is trickier. It will really help if you have some idea what you want the template to do. You can directly edit the existing #template.txt file if you wish. It is already quite powerful to begin with. The <p id="bodytext"> tag is where each page’s content is inserted into the template. The preceding and following pageheader() and pagefooter() calls are generating HTML and bringing a lot of other RubyFrontier features into play, so initially you should keep them too. Anything you write, therefore, needs to be after the pageheader() call and before the pagefooter() call. You might, for example, wrap the <p id="bodytext"> pseudo-tag in some kind of table or div structure. The template also demonstrates an extremely simple automatic mechanism for generating a link to the next and previous pages at the same level (by means of a macro).
Macros. Sooner or later you’re going to want to write a macro. In the template or page object, where you want the macro to be evaluated, put:
```
     <%= mymacro() %>
```
We’ve called the macro mymacro, so in the #tools folder create a Ruby script file called mymacro.rb. Give it a top-level method:
```
     def mymacro()
       "Hello, world!"
     end
```
Render the page (RubyFrontier > Publish Page). As you can see, the result of the macro script call, the string “Hello, world!”, is substituted for the macro in your template or page object. Now you can proceed to substitute your own functionality in that script. Examine the existing macro in the site, nextprevlinks.rb, and start tracking down how it works; this might ultimately form the basis of some of your own automatic navigation functionality.

At this point your feet are very wet and you’re on your own! You have enough structure to start seriously experimenting. Go back and read all that documentation that you skipped. It should mean a lot more to you now. Also, the source folder for this documentation is included in RubyFrontier’s source, so you can study it to see how it works (it’s pretty simple).