lazyj.page

Class BasePage

java.lang.Object

lazyj.page.BasePage

All Implemented Interfaces:

Page, TemplatePage

Direct Known Subclasses:

ModulePage

public class BasePage
extends java.lang.Object
implements TemplatePage

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
• ntobr : NtoBR) : convert text new lines to html new lines
• 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

Fields

Modifier and Type	Field and Description
java.util.Map<java.lang.String,java.lang.Object>	commonValues Common values across iterations
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

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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.
java.util.Set<java.lang.String>	getDBTags() Get the template fields that have the "db" option.
static BasePage	getPage(java.lang.String sTemplate) Create a page based on a predefined template.
protected java.lang.String	getResDir() This method should be overridden 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.
java.lang.Object	set(java.lang.String sTag, java.lang.Object oValue) Set a value that is not cleaned between write() or append() of this object (so it can be used across all lines in a table for example).
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.
java.lang.Object	unset(java.lang.String sTag)
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

commonValues

public java.util.Map<java.lang.String,java.lang.Object> commonValues

Common values across iterations

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 overridden 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 -

set

public java.lang.Object set(java.lang.String sTag,
                   java.lang.Object oValue)

Set a value that is not cleaned between write() or append() of this object (so it can be used across all lines in a table for example). Values explicitly set in the loop with functions like append(String, Object) or modify(String, Object) will have precedence over the common values.

Parameters:

sTag - tag that is modified

oValue - set value

Returns:

the previous value

unset

public java.lang.Object unset(java.lang.String sTag)

Parameters:

sTag -

Returns:

the previously set value, if any

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

getDBTags

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

Get the template fields that have the "db" option.

Returns:

set of tags, can be null

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