BasePage (LazyJ Web Templates API)

Base class for the HTML templates.

Basically this class parses a given template, looks for tags like:
<<:tag option1 option2 ...:>>
and replaces tag with a supplied value, applying all formatting options that follow the tag name.

Formatting options are implementations of the StringFormat class that were previously registered into this class via registerExactTag(String, StringFormat) or registerRegexpTag(String, StringFormat).

Current tags and their corresponding implementing classes:
Exact tags (in the order of their most-probable use):

esc : Esc : HTML-escaped version of the string
enc : Enc : URL-encoded version of the string
js : JS : JS-escaped version of the string
dash : Dash : the same string with any sequence of non-alphanumeric characters replaced by a single dash
under : Under : the same string with any sequence of non-alphanumeric characters replaced by a single underscore
checked : Checked : "checked" if the value is >=1
nicedate : NiceDate : nice representation of the date only
date : Date : nicely formatted date
time : Time : show only the time from the given date
dot : Dot : display a long value as groups of 3 digits separated by dot
size : Size : consider that the value is a file size, in bytes, display it in a human readable format
uenc : UEnc : URL-decoded version of the string
res : (internal class) : the HTML template (.res file) indicated by the tag is loaded

Regexp tags:

date.+ : Date : the leftover is the SimpleDateFormat formating string, with spaces replaced by underscores
cut[0-9]+ : Cut : take only the first N characters from the string, ignoring HTML tags and keeping only A,B,FONT,U and I from them
ddot[0-9]+ : DDot : display a double number with the given number of digits after the decimal point
strip([,a-z]*) : Strip : strip HTML tags from the text, optionally leaving some of them behind. See the class description for details

Special tag:

db : this field will be loaded from the database on a fillFromDB(DBFunctions) call

You are strongly encouraged to extend this base class and override getResDir(), to avoid hard coding template paths everywhere in your application.

Please be aware that templates are by default cached. While the code automatically detects changed files on disk and reloads them, it might take a few seconds until the changes are detected. So if you are in the development phase you can use the BasePage(OutputStream, String, boolean) with the last argument to false to prevent the framework from caching the contents. For base performance switch back to true as soon as you finished changing the templates.

Sample code (build a small table filled with DB contents):


 BasePage p = new BasePage(osOut, "/path/to/general/template.res", true);

 BasePage pLine = new BasePage(null, "/path/to/a/single/line/template.res", false);

 

 DB db = new DB("SELECT id,username,lastlogin FROM users;");

 

 while (db.moveNext()){

     pLine.fillFromDB(db);

     p.append(pLine);

 }

 

 p.write();

pLine could point to a file containing something like:


 <tr>

     <td><<:id db:>></td>

     <td><<:username db esc:>></td>

     <td><<:lastlogin db nicedate:>> <<:lastlogin db time:>></td>

 </tr>

Since:: 2006-10-06
Author:: costing

Field Summary
`java.util.Map<java.lang.String,java.lang.StringBuilder>`	`mValues` Values for the tags
`protected java.io.OutputStream`	`os` Output stream, to write the generated HTML to.
`java.util.Set<java.lang.String>`	`sComments` What are the sections that are commented out?
`java.lang.String`	`sFile` Original file that was used to read the contents from.
`protected java.io.Writer`	`writer` For writing to a Writer instead of a OutputStream (from a JSP page for example).

Constructor Summary
`BasePage()` Create an empty holder to whatever.
`BasePage(java.io.OutputStream osOut, java.lang.String sTemplateFile)` Create a page by reading the contents of the given file.
`BasePage(java.io.OutputStream osOut, java.lang.String sTemplateFile, boolean bCached)` Create a page by reading the contents of the given file.
`BasePage(java.lang.String sTemplateFile)` Create a page by reading the contents of the given file.

Method Summary
`void`	`append(java.lang.Object oValue)` Append a value to the default tag, "content"
`void`	`append(java.lang.String sTag, java.lang.Object oValue)` Append a value to a tag.
`void`	`append(java.lang.String sTagName, java.lang.Object oValue, boolean bBeginning)` Append a value to a tag, at the start or at the end.
`static void`	`clear()` Clear the page templates cache
`void`	`comment(java.lang.String sTagName, boolean bShow)` Shortcut for easy hiding of pieces of html.
`void`	`fillFromDB(DBFunctions db)` For all the tags that have the "db" option attached to them try to get the columns with the same name from the database row.
`java.lang.StringBuilder`	`getContents()` Apply the dynamic values to the initial template to obtain a StringBuilder representation of the final data.
`static BasePage`	`getPage(java.lang.String sTemplate)` Create a page based on a predefined template.
`protected java.lang.String`	`getResDir()` This method should be overriden by an object internal to each zone, that knows where all the HTML templates for that zone reside.
`java.util.Set<java.lang.String>`	`getTagsSet()` Get the set of all tags in the template
`static void`	`main(java.lang.String[] args)` Testing code
`void`	`modify(java.util.Map<?,?> m)` Set a bulk of tags in one move.
`void`	`modify(java.lang.String sTag, java.lang.Object oValue)` Assign a value to a tag, only if this tag wasn't assigned at a previous time.
`static void`	`registerExactTag(java.lang.String sOption, StringFormat sf)` This allows the programmer to implement new formatting options and to dynamically make them visible by registering them here.
`static boolean`	`registerRegexpTag(java.lang.String sPattern, StringFormat sf)` This allows the programmer to implement new formatting options and to dynamically make them visible by registering them here.
`void`	`reset()` Cancel any changes done to the template.
`void`	`setCallingServlet(ExtendedServlet servlet)` If a page contains modules that need access to the request / response this is the way to make it work.
`void`	`setOutputStream(java.io.OutputStream osOut)` If at a later time the user (programmer) decides that this object is to write itself into an output stream it can call this method.
`void`	`setWriter(java.io.Writer writer)` If you want to write directly to a writer (for example from a JSP).
`java.lang.String`	`toString()` Override the default toString() to obtain the dynamic data applied over the original template.
`boolean`	`write()` Try to send the generated content to the given output stream, assuming UTF-8 charset.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

os

protected java.io.OutputStream os

Output stream, to write the generated HTML to.

writer

protected java.io.Writer writer

For writing to a Writer instead of a OutputStream (from a JSP page for example).

sFile

public java.lang.String sFile

Original file that was used to read the contents from.

mValues

public final java.util.Map<java.lang.String,java.lang.StringBuilder> mValues

Values for the tags

sComments

public final java.util.Set<java.lang.String> sComments

What are the sections that are commented out?

See Also:: comment(String, boolean)

Constructor Detail

BasePage

public BasePage()

Create an empty holder to whatever. It is equivalent to a file that only has:
<<:content:>>

BasePage

public BasePage(java.lang.String sTemplateFile)

Create a page by reading the contents of the given file.

Parameters:: sTemplateFile - file to read.

BasePage

public BasePage(java.io.OutputStream osOut,
                java.lang.String sTemplateFile)

Create a page by reading the contents of the given file. When calling write() later on this object, the generated contents will be written to the given OutputStream, if this is not null.

Parameters:: osOut - stream to write the generated HTML to at the end; sTemplateFile - file name to read the template from

BasePage

public BasePage(java.io.OutputStream osOut,
                java.lang.String sTemplateFile,
                boolean bCached)

Create a page by reading the contents of the given file. When calling write() later on this object, the generated contents will be written to the given OutputStream, if this is not null. With this constructor you can control whether or not the contents of this file is kept precompiled in memory. The default behavior of the simpler constructors is to cache everything. This is generally a good idea, since the original files are anyway monitored for changes and the contents is automatically reloaded if the underlying file is changed (1 minute between checks).

Parameters:: osOut - stream to write the generated HTML to at the end; sTemplateFile - file name to read the template from; bCached - controls the caching of this file

Method Detail

getResDir

protected java.lang.String getResDir()

This method should be overriden by an object internal to each zone, that knows where all the HTML templates for that zone reside. The base implementation returns the empty string, making it usable if you want to give the full path to a template file.

Returns:: the full path to the base folder where the templates can be found

main

public static void main(java.lang.String[] args)

Testing code

Parameters:: args - ignored

setOutputStream

public void setOutputStream(java.io.OutputStream osOut)

If at a later time the user (programmer) decides that this object is to write itself into an output stream it can call this method. This is normally done via one of the constructors that have the OutputStream parameter.

Parameters:: osOut - output stream to write the contents to

setWriter

public void setWriter(java.io.Writer writer)

If you want to write directly to a writer (for example from a JSP).

Parameters:: writer -

modify

public void modify(java.lang.String sTag,
                   java.lang.Object oValue)

Assign a value to a tag, only if this tag wasn't assigned at a previous time. In other words only the first assignment to a tag is considered.

Parameters:: sTag - tag to assign a value to; oValue - the value to assign. If null then the empty string will be put in the map.
See Also:: append(String, Object, boolean)

modify

public void modify(java.util.Map<?,?> m)

Set a bulk of tags in one move.

Parameters:: m - the <tag, value> mapping

append

public void append(java.lang.Object oValue)

Append a value to the default tag, "content"

Parameters:: oValue - value to be appended to the default tag.

append

public void append(java.lang.String sTag,
                   java.lang.Object oValue)

Append a value to a tag.

Parameters:: sTag - tag name; oValue - value to append

append

public void append(java.lang.String sTagName,
                   java.lang.Object oValue,
                   boolean bBeginning)

Append a value to a tag, at the start or at the end.

Specified by:: append in interface TemplatePage

Parameters:: sTagName - tag name; oValue - value to append; bBeginning - true to add at the start, false to add at the end

getContents

public java.lang.StringBuilder getContents()

Apply the dynamic values to the initial template to obtain a StringBuilder representation of the final data.

Specified by:: getContents in interface Page

Returns:: a StringBuilder with the final contents

toString

public java.lang.String toString()

Override the default toString() to obtain the dynamic data applied over the original template.

Overrides:: toString in class java.lang.Object

Returns:: the final form of the template + dynamic data

write

public boolean write()

Try to send the generated content to the given output stream, assuming UTF-8 charset. If both the output stream and the writer are set, send the result to both of them.

Returns:: true if everything was OK, false on any error or if no output medium was defined.

reset

public void reset()

Cancel any changes done to the template. You should use this when, in the code, you realize that the previous calls to modify(String, Object), append(String, Object) etc are not going to be used and you have to prepare the object for the next iteration.

Since:: 1.0.5

comment

public void comment(java.lang.String sTagName,
                    boolean bShow)

Shortcut for easy hiding of pieces of html. It will act on TAGNAME_start and TAGNAME_end tags in the template. If the flag is true then the contents will be displayed. If not everything between *_start and *_end will be cut. At the same time it will do the oposite on "!TAGNAME_start" and "!TAGNAME_end" (like an if/else clause in the template).

Parameters:: sTagName - base name of the two tags; bShow - true if you want to display the contents, false if you want to hide it

fillFromDB

public void fillFromDB(DBFunctions db)

For all the tags that have the "db" option attached to them try to get the columns with the same name from the database row.

Parameters:: db - a database object that holds the result of a select query, having the same column names as the tags you want to fill

registerExactTag

public static final void registerExactTag(java.lang.String sOption,
                                          StringFormat sf)

This allows the programmer to implement new formatting options and to dynamically make them visible by registering them here. The option needs to exactly match the name given here, in lowecase.

Parameters:: sOption - option for which to add formatting name; sf - an instance of the formatting class for this option

registerRegexpTag

public static final boolean registerRegexpTag(java.lang.String sPattern,
                                              StringFormat sf)

This allows the programmer to implement new formatting options and to dynamically make them visible by registering them here. The option can be in this case a dynamic value that matches some regexp pattern. For example "cutN", "ddotX" are

Parameters:: sPattern - pattern that the option matches; sf - an instance of the formatting class for this option
Returns:: true if the pattern could be correctly compiled, false if the pattern is not ok

setCallingServlet

public void setCallingServlet(ExtendedServlet servlet)

If a page contains modules that need access to the request / response this is the way to make it work.

Parameters:: servlet -

clear

public static void clear()

Clear the page templates cache

Since:: 1.0.2

getTagsSet

public java.util.Set<java.lang.String> getTagsSet()

Get the set of all tags in the template

Returns:: all tags in the template
Since:: 1.0.6

getPage

public static BasePage getPage(java.lang.String sTemplate)

Create a page based on a predefined template. Use this constructor when the contents is not on disk, but be aware that in this case the template is not cached!

Parameters:: sTemplate -
Returns:: the compiled template/page

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

lazyj.page Class BasePage

os

writer

sFile

mValues

sComments

BasePage

BasePage

BasePage

BasePage

getResDir

main

setOutputStream

setWriter

modify

modify

append

append

append

getContents

toString

write

reset

comment

fillFromDB

registerExactTag

registerRegexpTag

setCallingServlet

clear

getTagsSet

getPage

lazyj.page
Class BasePage