NetCloak Tutorial Creating New Pages- Recipe Example

NetCloak Demo

As an example of how to create new pages on your site with NetCloak Pro, we will build a very simple system for users to share recipes. This tutorial example uses the CREATEDOC directive to create new pages from information sumbitted by users, as well as the MENUDOC directive to automatically build a list of links to the new pages.

The exact same methodology could be applied to a system for posting bulletins, news articles, student essays, personal home pages, discussion forums, or any other system where users of your Web site need to be able to create content for other users. Turn your Web site into more than a collection of Web pages... Make it an interactive resource for your users.

This tutorial assumes that you have already read the FDML Primer and have at least a basic understanding of what an FDML file is and how it functions. So, we're going to jump right into the example.

A Recipe System

The recipe system will have three main components: a menu, recipe pages, and a form where users can add recipes to the system. We'll start with the recipe menu, which will look like this when just a few recipes have been entered.

As you can see, we'll be using very simplistic HTML formatting, to make reading the example as easy as possible.

When a user clicks on one of the recipe links, they will be taken to a full recipe page. We'll prototype this page as well. Here is how the "Rice Crispies" page might look:

Notice that we have created sample pages that can be used as prototypes for building the fully interactive system, as suggested near the end of the FDML Overview. In the final system, the menu page will be automatically maintained and the recipes automatically created, but for now, we hard code the samples.

One more page will be needed, the input form that allows visitors to submit new recipes. Here is what that page will look like:

With this basic three page system, users can review the list of recipes, read (and print out) full recipe descriptions, and submit new recipes to the system. We could specify many additional bells and whistles, but again, the key is to start with a solid, properly working mechanism onto which new features can be added later.

Building The System

Each of the three pages shown above could have been created using any HTML editor or text processor. Let's take a look at the recipe menu page, which is only 16 lines long...

<HTML> <HEAD> <TITLE>Recipe Menu</TITLE> </HEAD> <BODY BGColor=#FFFFFF> <CENTER><H3>Recipes</H3></CENTER> Welcome to our public recipe swap forum. Choose a recipe from the list below, or <A HREF="EnterRecipe.html">add a recipe yourself</A>! <P> <DL>  <DD><A HREF="RiceCrispyTreats.html">Rice Crispy Treats</A> (submitted by Bob on 2/22/00)<P> <DD><A HREF="BreadPudding.html">Bread Pudding</A> (submitted by mary on 2/21/00)<P> <DD><A HREF="WhiteChocolateBrownies.html">White Chocolate Brownies</A> (submitted by Chuck on 2/21/00)<P> </DL> </BODY> </HTML>

Listing 1: The Recipe Menu

The entire page is made up of plain HTML. In the first section are the simple header tags used at the top of virtually all HTML pages, and the second section displays the text at the top of the page. The third section is the list of recipes, in this case formatted using the definition list ("DL") tag. Of note here is the HTML comment ("") which will be used by the FDML file coming up to specify the place in the file where new recipe listings should be added. Finally, the page is completed with end-body and end-HTML tags.

When a user decides to add a recipe, they will click on the "add a recipe yourself" link on the page and be taken to the input form shown above. In HTML, this form looks like this:

<HTML> <HEAD> <TITLE>Recipe Entry</TITLE> </HEAD> <BODY BGColor=#FFFFFF> <CENTER><H3>Recipe Entry</H3></CENTER> <FORM METHOD=POST ACTION="Recipe.fdml"> <B>Author:</B> <BR> <INPUT TYPE="text" NAME="Author" SIZE="30" MAXLENGTH="30"> <P> <B>Recipe Name:</B> <BR> <INPUT TYPE="text" NAME="RecipeName" SIZE="30" MAXLENGTH="30"> <P> <B>Ingredients:</B> (enter each ingredient on a separate line)<BR> <TEXTAREA NAME="Ingredients" ROWS=3 COLS=56></TEXTAREA> <P> <B>Directions:</B><BR> <TEXTAREA NAME="Directions" ROWS=3 COLS=56></TEXTAREA> <P> <CENTER> <INPUT TYPE="submit" VALUE="Submit Recipe"> </CENTER> <P> </FORM> <CENTER><A HREF="RecipeMenu.html">Return To Recipes Menu</A></CENTER> </BODY> </HTML>

Listing 2: The Recipe Entry Form

Here again, the page is standard HTML and begins and ends with the typical HTML/HEAD/BODY tags common to all properly created Web pages. The middle section, set off by <FORM> and </FORM> tags, is the interesting part.

First, the FORM tag itself includes two crucial parameters. The first is METHOD=POST, which tells the browser to use the HTTP POST method for sending the data to the server. The POST method sends the form data to the server in part of the HTTP request that is hidden from the user, and allows a large amount of data to be sent. The other possible method is GET where the form data is sent in the URL. The GET method is limited by the maximum size of a URL. NetCloak does support the GET method, but POST is the best choice for most systems.

After the METHOD, the FORM ACTION is set. This is simply a URL to the FDML file that we will create below. The ACTION URL can be a file-relative partial URL, a root-relative URL, or a fully qualified URL (beginning "http://"). In this case, a file relative URL is used because the FDML is in the same folder as the input form.

Following the FORM command are the four input fields we will need the user to complete. In this example, we specify two fixed length text fields and two scrolling text areas for larger amounts of text. Checkboxes, radio buttons, and other field types are also supported. For a complete overview of HTML input forms, see one of the excellent on-line HTML resources available.

When the user completes the form and clicks submit, the FDML file is invoked and the real work is finally done.

Processing The Form Data

To create the FDML file, we start with the sample recipe we already created:

<HTML> <HEAD> <TITLE>Rice Crispy Treats</TITLE> </HEAD> <BODY BGColor=#FFFFFF> <CENTER><H3>Rice Crispy Treats</H3></CENTER> This recipe submitted by Bob on 2/22/00. <P> <B>Ingredients</B> <P> <UL> <LI>Rice Cripies (4 cups) <LI>Marshmellows (1 16 oz. bag) <LI>Butter (1 stick) </UL> <P> <B>Directions</B> <P> Melt Marshmellows and butter in a sauce pan over low heat. Pour Rice Crispies into a large bowl, and slowly fold in marshmellow sauce, gently stirring. Spoon mixture into greased pan and allow to cool. <P> Cut and serve! <P> <CENTER><A HREF="RecipeMenu.html">Return To Recipes Menu</A></CENTER> </BODY> </HTML>

Listing 3: The "Rice Crispy" Recipe Page

First, we'll remove the Rice Crispy specific text and replace it with NetCloak REPLACE commands. In most cases, a tag is used to tell NetCloak to insert the contents of a field, as entered by the user, at the specified point. For example, the author's name (Bob) in the listing above will be replaced with a command. The variable Author is the name of one of the input fields, and comes from the input form.

The template for the recipe page, with NetCloak commands used in place of the sample text, is:

<HTML> <HEAD> <TITLE><REPLACE RecipeName></TITLE> </HEAD> <BODY BGColor=#FFFFFF> <CENTER><H3>REPLACE RecipeName</H3></CENTER> This recipe submitted by <REPLACE Author> on <DATE>. <P> <B>Ingredients</B> <P> <BULLET Ingredients> <P> <B>Directions</B> <P> <REPLACE Directions> <P> <CENTER><A HREF="RecipeMenu.html">Return To Recipes Menu</A></CENTER> </BODY> </HTML>

Listing 4: The Recipe Template

Notice that <REPLACE RecipeName> is used twice, first in the title of the page and again as the headline of the page. This is perfectly legal, and form variables may be used as many times as you like in any FDML file.

The "this recipe submitted by" line includes the <REPLACE Author> command, followed closely by the NetCloak <DATE> command. This tag, used without parameters, simply inserts the current date into the newly created file.

The Ingredients section includes another new command, <BULLET>. This command is similar to a REPLACE, and inserts the contents of the given input field (in this case, the Ingredients field) at the specified position. BULLET, however, inserts data from the form field with HTML tags to make each line of the input field an item in an unordered list.

The Directions are also inserted using a REPLACE command. Of note here is that the text entered by the user for the directions may include carriage returns. NetCloak automatically converts a single return to an HTML <BR> tag and two consecutive returns to a <P> tag. This maintains the line and paragraph breaks when the directions are inserted into an HTML file.

Now it is time to tell NetCloak what do do with our template. This is done using NetCloak Directives, which "direct" NetCloak to take specified actions. Directives are always placed in a single block at the top of the FDML file, before any text of the template. Here is the directive block for the recipe system:

<CREATEDOC>"<REPLACE_FN RecipeName>.html"</CREATEDOC> <MENUDOC "">"RecipeMenu.html" <DD><A HREF="<HTMLFILENAME>"><REPLACE RecipeName></A> (submitted by <REPLACE Author> on <DATE>)<P> </MENUDOC> <RESPONSE>"ThankYou.html"</RESPONSE>

Listing 5: The Recipe Directive Block

All FDML files must include exactly one "Primary Directive": SENDMAIL, TEXTSTORE, INSERTFILE, or, as in this case, CREATEDOC. The CREATEDOC directive tells NetCloak to create a new HTML page on the server. Inside the and tags, the name of the file to be created is specified.

The filename specified in the CREATEDOC command can be either just a filename (in which case the file created will be placed into the same folder as the FDML file) or a full root-relative path. Paths specified inside FDML tags may not be full URLs. NetCloak processes files using the Mac OS file system, not HTTP, so full URLs are not permitted. Also note that REPLACE commands are permitted inside FDML directives. In fact, they are often required, and a special version of the REPLACE tag, REPLACE_FN, is provided specificallly for use in filenames. The REPLACE_FN tag performs a standard replace function, but also removes characters that may be troublesome in URLs. For example, spaces, which must be encoded in URLs, are removed altogether, so that when a user creates a recipe with the title "Rice Crispy Treats" the REPLACE_FN tag will insert "RiceCrispyTreats". The resulting CREATEDOC command will then be:

<CREATEDOC>"RiceCrispyTreats.html"</CREATEDOC>

Now, the CREATEDOC command tells NetCloak to use the template, process the REPLACE, BULLET, and other insertion commands, and save the file as "RiceCrispyTreats.html" in the specified folder.

The next directive in the block is the MENUDOC command. It tells NetCloak that a menu is being maintained, which will provide a link to the newly created page. Inside the MENUDOC command itself is the HTML comment to look for in the menu page, which specifies where new links should be added. In listing 1 above, you can see that the comment  appears at the top of the list, right where links to newly created recipes should go.

Immediately after the opening MENUDOC tag is the filename of the menu to be updated. Again, this is specified as a root-relative path, although a filename is also sufficient if the menu page is in the same folder as the FDML file.

After the filename of the menu page is the text that should be inserted into the menu. Here, we've taken a line from the menu and replaced the static sample text with NetCloak REPLACE, DATE, and HTMLFILENAME commands, exactly as we did when we made the recipe page template. Specifying the full text of the menu item to be inserted gives you the flexibility to format menu pages any way you like. In this case, the menu is formatted as a definition list, and not only provides a link to the page, but lists the author and the date the recipe was added as well. The HTMLFILENAME command provides an easy way to link to the new page. This command will insert a root-relative path to the new file, and is almost always used inside an anchor hypertext reference ("A HREF") to link inside the MENUDOC command.

The last FDML directive in the block is the RESPONSE comand. This directive simply tells NetCloak what file to return to the user when the input form is submitted. Normally, this will be a very simple page thanking the user for their submission and providing a link or two back to key pages in the system. In this case, for example, a link would be provided to the recipe menu page.

Creating This System Yourself

The system described here makes an excellent starting point for many other similar and simple solutions, and is also a good base upon which to experiment with other NetCloak forms processing solutions. To get the recipe system up and running on your own server, copy the Recipes folder out of the Extras folder included in the NetCloak package into your web server or site's root folder. (Be sure that NetCloak is installed properly, of course.)

Now you are ready to try the system. On any Web browser, go to the recipe menu with the URL:

http://your.server/NetCloak/Recipes/RecipeMenu.html

Of course, you will need to replace "your.server" with the address or domain name of your Web server.

The menu page that appears will be quite short, but that's OK. For now, just click the "add a recipe..." link.

When the recipe entry page appears, fill out the form completely. To see that the system is working, complete the fields as you would if you were entering a real recipe. In particular, enter several ingredients, with each on its own line, and enter a few paragraphs of sample directions. When you are done, click the Submit button.

Notice that the next page displayed is the Thank You page. Return to the recipe menu by clicking the link on the page or the back button in your browser. On the recipe menu page, click "Reload" if the new recipe does not appear. If the recipe is not shown, try a "power reload" by holding down the option key while clicking the reload button (if you are using Netscape Navigator).

The new recipe should now appear on the menu, and clicking on the link should display the full recipe. Go back to the Finder on the Web server and take a look at the Recipes folder... A new file has been added and is named according to the recipe name entered. You can open and edit this file just like any other HTML page on your server.

[ Return To The NetCloak Introduction ]