/ 
Text-Forge-2.16
River stage zero No dependents
/ Text::Forge

NAME

Text::Forge Tutorial

SYNOPSIS

We will cover how to write Text::Forge documents. Knowledge of Perl and HTML is assumed.

DESCRIPTION

Text::Forge is a system of creating dynamic web pages. The syntax is simple. This is a feature of the system, not a bug.

Your Page is a Subroutine

Your page is compiled into a subroutine. It may be called, depending on the setup of your server, with arguments. Templates may also be called with arguments. Look in @_ for the actual arguments, just as you would in a regular perl subroutine.

Note that you do not put sub declarations in your page. That is added for you.

Whatever you page prints out, that is what your page shows when rendered.

Normal Text is Double-Quoted

Everything except the escaped perl code is interpreted as double-quoted text.

For instance, Hello, my name is $name! is interpreted as Hello, my name is Jonathan! if $name is 'Jonathan'.

Of course, normal text is printed out so that it shows up on the rendered page.

Construct Overview

There are four constructs to escape perl code in the text page.

Code Block - <% ... %>

The <% ... %> construct allows you to insert regular perl code. The result is not interpreted. A semi-colon is placed at the end of the block. If you want to output something to the page from inside a code block, you can use a print statement.

You can use <% ... %> to use conditional or looping constructs. For example:

<%
  if ($name eq 'Jonathan') {
%>
Hello, author!
<%
  } else {
%>
Hello, reader! I hope you enjoy this tutorial.
<%
  }
%>

The <%$ ... %> construct allows you to insert a perl statement that is then printed to the page. Do not use a semi-colon at the end.

For instance, <%$ customer_name($customer_id) %> will call the customer_name subroutine and print out the result into the text document.

HTML Encode Block - <%= ... %>

The <%= ... %> construct allows you to insert a perl statement that is then rendered HTML safe. That means that characters like &,<, and > are interpreted to the corresponding HTML entity. Do not use a semi-colon at the end.

For instance, <%= 'This is <b>My</b> Biography' %> will change into This is &lt;b&gt;My&lt;\b&gt; Biography, which will show up on the rendered HTML page as This is <b>My</b> Biography.

URI Escape Block - <%? ... %>

The <%? ... %> construct allows you to insert a perl statment that is then URI escaped. Do not use a semi-colon at the end.

The $forge Object

The $forge object is available on every page. There are a few routines that may prove helpful.

$forge->include($template[, @args])

This will include a template. If the first character of the template name is /, it is interpreted as an absolute file location. Otherwise, all the templates in the template include path are searched. You can pass arguments to the templates.

A common idiom to use a template is:

<% $forge->include('page/template', arg1=>$arg1, arg2=>$arg2) %>
$forge->encode_entities($scalar[, $scalar...])

This is used if you are going to encode something over an over again in a page. For instance, someone's name. You cannot tell (unless you look for it) whether they have put in HTML code in their name. So, everytime you use their name you will be tempted to write:

<%= $name %>

A better way is to do this:

<%
  $name = $forge->encode_entities($name);
%>
Hello, $name! I am sure you, $name, thought you were smarter than me. Well,
$name, I got news for you! I encoded your name (which is $name)!
$forge->uri_escape($scalar[, $scalar...])

This is the same as the encode_entities method above, except for escaping strings for URIs.

mod_perl and Text::Forge

I'm including this note not because it needs to be here, but because if you are as new to mod_perl as you are to Text::Forge, it will bite you. You can also find notes about these things in the mod_perl documentation, which you should read if you are going to be using mod_perl.

Don't Use Non-Lexical Variables

First off, don't put non-lexical variables in you page unless you are absolutely sure they won't change. Since you cannot be absolutely sure of anything, don't do it.

Since you may be as new to perl as you are to mod_perl and Text::Forge, I'll spell this out in plain English.

<%
  use strict;
  use Orders;

  my $orders = Orders->get_order($order_id);

  foreach my $order (@$orders) {
%>
Your order for $order->{title} will be ready by $order->{ready_date}.<br/>
<%
  }
%>

Note the statement use strict;. Note the absence of use vars qw(...);. Note that all the variables are declared with my. This will solve 99% of your mod_perl problems.

Don't Declare subs in a Page

Don't declare subs in a page. Just don't do it. It is very bad and it won't work the way you expect it to.

Put it in a module somewhere, and use that module. In fact, any code that does anything useful should be put in a separate module so it can be reused. You should avoid using a lot of code in the page except to get stuff to look right for that page.

This will solve the other 0.9999% of your mod_perl problems. The remaining 0.0001% of your mod_perl problems are left as an exercise for the reader to solve.

SEE ALSO

Text::Forge Style Guide

Text::Forge

AUTHOR

Jonathan Gardner <jgardn@alumni.washington.edu>

COPYRIGHT

Copyright © 2002 Jonathan Gardner

Licensed under the GNU Freedoc License.