Publishing

Going live

Up until now, every time we have looked at Frontier's output in our browser, we have done it through the Preview Page command. This command, however, is useful only up to a point.

The HTML documents that it makes are placed into folders in a sort of catch-all folder called Websites, in the same folder as Frontier itself; this folder (Websites) is really just a temporary holding place, and you should throw it away from time to time. A "real" rendering of your site would go into a folder you specifically designate with #ftpSite.

Even more important, "real" rendering gives you a way to render your entire site at once.

And we are coming now to some features of Frontier's Web site management that really make sense only in terms of the site as a whole, so it would drive you mad to have to render the site one page at a time.

"Real" rendering of this kind is called "publishing." It is a little more work than previewing a page, but not much. You select a single page and choose Publish Page from the Web menu, or, to render your whole site at once, select anywhere in your site (anywhere that isn't itself a table) and choose Publish Table.

But don't try it yet, because first we have to prepare our #ftpSite.

Where to build your site

Open the myFirstSite.#ftpSite table and look inside.

The #ftpSite.isLocal entry tells Frontier whether or not it is to create the pages onto your hard disk.

The alternative, corresponding to an isLocal value of false, would be for Frontier to launch your FTP client program (such as Fetch or Anarchie) and instruct it to upload the pages over the Internet as it renders them! This is a very convenient feature when it's needed. At this writing this works only on Macs, but an automated connection to one or more Windows FTP clients is, fingers-crossed, on its way.

We need now to set the two values #ftpSite.folder and #ftpSite.url.

The value at #ftpSite.folder represents the folder on your hard disk into which Frontier will place the Web pages as they are rendered. A default value has been silently created for you, so that you could start publishing if you wanted to. But now we want to give it a real value.

(The default value is to publish into the Websites folder that's in the Frontier folder. But that's really where page previews should go, and not your published sites.)

Unfortunately, it's tough to remember and type an entire pathname accurately, especially when you're looking at it in such a small space. Here is a handy shortcut; it involves talking to Frontier in UserTalk, though, so I'm not going to explain what you're actually doing.

Go to your desktop and create the folder you want to render into, if it doesn't exist already. Now come back to Frontier and, from the Main menu, choose Quick Script. The Quick Script window appears (this is Frontier's "command-line" interface). If there's anything in it, select and backspace to get rid of it, and now type exactly the following:

   file.getFolderDialog 
    ("", @websites.myfirstsite.["#ftpsite"].folder)

Hit the Run button at the right of the QuickScript window, and use the resulting dialog to select the desired folder; its path will then have been entered as the value of #ftpsite.folder.

As for #ftpSite.url, this will be used by Frontier for various tasks where it needs to know the actual URL your site will occupy when it's on the Internet. If you know what this is, you should type it in for the value of #ftpSite.url now. Remember to put "http://" or "file:///"; in other words, if your site will be located at http://www.borg.com/mysite/, put "http://www.borg.com/mysite/" (without the quotes).

Now you can close #ftpSite and forget about it.

Publishing your entire site

Let's try publishing the whole site now. If you have been following along in this tutorial, you've made many changes in our practice site, so let's go back and clean up and take stock for a moment, so that we're working with the same set of documents.

You should have a default page whose #title is "Welcome." You should have a secondPage whose #title is "My Second Page" and which contains a renderObject macro which embeds thirdPage. You should have a thirdPage which is an outline, has no #renderOutlineWith directive, and has no #title. And you should have a fourthPage which is an outline, and has a #renderOutlineWith "tableOutliner" directive; I believe we neglected to give this a #title so call it "My Fourth Page."

Now select anywhere in the site table (but don't select anything that's a table!) and choose Publish Table. After checking with you to make sure you really want to do this (and to make sure it's got the right table), Frontier will churn away for a bit, and then put up a dialog telling you it's finished (this may seem silly, but when you have a huge site to publish you'll be glad to be told when the rendering process is finally over).

You'll notice that the browser is not showing you the rendered page; if you publish just one page, Frontier sends it to the browser but doesn't bring the browser to the front, and if you publish an entire site, Frontier doesn't tell the browser about it at all.

You can go to the folder and double-click any of the .html files to open them with your browser. (On a Mac you may need to change the value of user.html.prefs.textFileCreator to match the creator code for your Web browser.)

Viewing source

If you're using OSAMenu on the Macintosh, you get an extra feature at this point. A common problem is that, with an HTML file, sometimes you want to see it in the browser so you can look at the formatting, and sometimes you want to see it in a text editor so you can examine the actual HTML.

Frontier gives you menu items in the Finder's extra Scripts menu that let you do this; with an HTML document selected, you can choose either View in Browser or Edit as Text File. The first time you choose Edit as Text File you'll be asked for an application to act as your editor; from then on, Frontier knows what application to send text to.

Even without OSAMenu, but still on the Mac, you get an equivalent feature from within your browser; when Frontier is running, the browser has an extra Scripts menu, one of whose items, Edit Local File, lets you open with a text editor the file you're currently looking at.

Of course, on Windows and Mac you can always choose "View Source" from within your web browser. Or use NotePad or BBEdit to directly open a .html file.

Site structure

A thing you should experiment with at this point is the way the structure of the whole site on disk mirrors the structure of the whole site in the table.

To see this, try putting fourthPage in a table of its own. In myFirstSite, make a new subtable using New Sub-Table from the Table menu. Call it "sub" (without the quotes). Cut fourthPage out of myFirstSite and paste it into the "sub" table. (Get rid of any "item #1" entry that may have arisen.) Now go back to the myFirstSite table and publish the whole site, and examine its structure. There is a subfolder called "sub," and fourthPage.html is inside it, just as in the site table.

Now move fourthPage out of the "sub" table back into the myFirstSite table, and delete the "sub" table. Publish the whole site. Ooops! The "sub" table is still there, with a copy of fourthPage.html still inside it!!

Frontier creates files and folders to reflect the structure of your site table, but it does not get rid of any files and folders (except when they are overwritten by the creation process). It is up to you to clean out your site if the structure changes; Frontier won't do it for you.

This also has to do with why I warned you not to select a subtable by accident when you choose Publish Table. If, for instance, you were to select "glossary" and say Publish Table, you would wind up with a glossary subfolder in your site on disk, perhaps with some odd things inside it.

That's intentional, because it allows you to rebuild just one subtable of your site. But Frontier will take you literally if you tell it to publish the tools or glossary or images subtable or any other subtable that isn't normally publish, so be careful.

That's what the dialog at the start of the Publish Table process is for -- it gives you chance to realize you've made a mistake. (Of course if you're like me you'll just blindly hit OK anyway!)

Hiding things

There's another problem. We have rendered thirdPage, as thirdPage.html. Since the only purpose of thirdPage right now is to be an element embedded in secondPage, we need to "hide" thirdPage somehow so that it doesn't get included in the publishing.

Let's fix this. Cut thirdPage out of the myFirstSite table, open myFirstSite.#tools (create it if it doesn't exist) and Paste thirdPage in there. (Get rid of any "item #1" entry that may have arisen.)

Now, go back into secondPage and change its reference to thirdPage (in the renderObject call) so that it correctly reaches thirdPage; otherwise secondPage won't include thirdPage, as it is supposed to. By now I shouldn't have to tell you how to do this, so it is left as an exercise.

Publish the site again. You should find that secondPage is able to include thirdPage but thirdPage has not been rendered as a separate file. That's what we wanted.

Things inside the tools, images, and glossary folders are not rendered when a site is published.

Publishing via FTP

If you like, you can combine publishing and uploading via FTP. You do this by adding some new entries to your #ftpSite table, then changing the value of "isLocal" in your #ftpSite table to "false" (no quotes), starting up Fetch or Anarchie and your browser, and publishing in the normal way.

What are the entries you need to add to the #ftpSite table? You already have "folder," which is the folder on your hard disk where you do local releases; now you add "directory," which is the path (using slashes as separators) to the directory on the remote machine where you will put the material (since one often does not enter an FTP site at the directory used for Web stuff). You already have "URL," which tells how Web users see your material; now you add "domain," which is the machine as seen by your FTP client. And you need "account" (your FTP username) and "password."

Here, for instance, is how I publish and upload in one move to a Web site I take care of (all of the names and numbers are disguised, so don't try using them yourself!):

account	mattn
directory	/usr/www/apache/htdocs/
domain	206.31.218.123
folder	HD:local build:
isLocal	false
password	haha
url	www.snarf.com/

When I choose Publish Page, Frontier publishes the page into the local folder (using the folder entry), then uses my FTP client to upload it (using the domain and the directory entries), then uses my browser to show it to me over the net (using the URL entry).

One word about this: imageRef doesn't upload images over the net for you as it is called. You'll need to find the images on disk and upload them yourself with your FTP client.