BlueShoes Application Framework - Cmt

Bs_FormTemplateParser

Bs_Object
   |
  +-- Bs_XmlParser
     |
    +-- Bs_FormTemplateParser

Template Parser Class

public class Bs_FormTemplateParser extends Bs_XmlParser

Template Parser Class
dependencies: Bs_XmlParser, Bs_String, Bs_ContentBlock, Bs_Dir,Bs_FormHandler (which starts the require of all the form stuff),Bs_TemplateParser,//Bs_NavigationSitethe following tags are defined:o) bs_navigation- used to build the site navigation- is closed directly.- properties:- function= the function name to call.- example:<bs_navigation function="getSiteLeftNavigation"/>o) bs_content- used for content blocks.- is closed directly.- properties:- name= the internally used form name. has to be set.- type= not sure if this is of any use or just a hint for the webmaster.- example:<bs_content name="fasttrackTrialSignup" type="form"/>o) bs_form- used for forms.- has to be closed using </bs_form>.- can 'hold' bs_input tags.- properties:- name= the internally used form name. has to be set.- mode= one of 'add', 'edit', 'delete'. should be set.- example:<bs_form name="formName" mode="add"> ... </bs_form>o) bs_input- used for forms.- is closed directly.- properties:- name= the internally used element name. has to be set.- type= one of 'element', 'caption', 'text', 'error', 'help'. default is 'element'.- elementlist= list of elements you want to have in the returned output. useful forradio buttons if you don't want all of them, or just one.give the keys of the elements you want.- example:<bs_input name="elementName" type="element"/><bs_input name="elementName" type="element" elementlist="us,ca,de"/>o) bs_forminfomaybe you better use that only in 'done' templates. i think that they can also beused else, but ... dunno.- used for forms.- is closed directly.- properties:- type= one of 'recordId', 'usedTime', 'viewCount'.- example:<bs_forminfo type="recordId"/>o) bs_formerrors- used in forms.- is closed directly.- properties:- caption= the internally used element name. has to be set.- //type=- example:<bs_formerrors caption="Input Errors:"/>o) bs_include- used to include source code that gets parsed from bs. is donein an extra loop to have everything together before we start.can be recursive.- is closed directly.- properties:- src= can be a file (relative or absolute) on the currentmachine or in the network, or can be an url.- examples:<bs_include src="file:../templates/someFile.tpl.html"/><bs_include src="url:http://www.domain.com/file.txt"/>o) bs_require- same as bs_include but it won't be parsed from bs. not donein an extra loop either. so it's faster but less fun.

Authors andrej arn <andrej@arn.li>

Version 4.0.$id$

Copyright blueshoes.org

Methods inherited from Bs_XmlParser

bs_xmlparser, gettagname, iscommentedout, parsetag, parseproperties

Methods inherited from Bs_Object

isex, isexception, tostring, tohtml, persist, unpersist, bs_object, bbsetoutput, bbawake, bbisawake, bbxmsg, bbxfunctionstart, bbxfunctionend, bbxecho, bbxvar, bbxvardump, bbforcetrace, bbbufferstart, bbbufferget, bbbufferendflush, bbbufferendclean

Public Method Summary
void	Bs_FormTemplateParser([ integer $pageID, string $page ]) Constructor.
bool	loadTemplateFromFullpath(string $fullPath) loads the template from the given absolute fullpath.
void	parse([ string $debug ]) it's not a real parser, it just searches for <bs ...> tags. fills $this->tags.
bool	applyTag(int $tagKey, string $tagString) applies a tag to $this->templateString.

Private Method Summary
bool	loadTemplate(string $template, [ string $type, array $options, string $walkSubdirs ]) loads the content of a template into $this->templateString.
string	_getTemplatePath() finds out where the templates are or should be and returns the fullpath
bool	apply([ string $language, string $form, string $editable ]) has to be called after parse(). means $this->tags must be set already, somehow.

Fields inherited from Bs_XmlParser

$htmlutil

Public Field Summary
string	$templatePath the absolute path to the template directory. if not set than
string	$caseFolding OVERWRITES PARENT CLASS!

Private Field Summary
object [unknown]	$Bs_String reference to the globally used pseudostatic class.
int	$pageID the page id for which this instance of templateparser is used.
object [unknown]	$_page reference to the Bs_Page object that uses this template parser.
string	$templateString the content of the template file as one string.
array	$tags has this structure:
integer	$_offset used in applyTag(). everytime we add something, the tags below move more down.
unknown	$this

Private Constant Summary
BS_FORMTEMPLATEPARSER_VERSION	>>`4.0.$x$`<<	Warning: documentation is missing.

Public Method Details

Bs_FormTemplateParser

public void Bs_FormTemplateParser( [ integer $pageID, string $page ] )

Constructor.

Parameter

integer	$pageID	`= >>0<<`
	default is 0

string	$page	`= >>NULL<<`
	the page object that uses this template parser. PASS IT BY REFERENCE.

Returns

void

loadTemplateFromFullpath

public bool loadTemplateFromFullpath( string $fullPath )

loads the template from the given absolute fullpath.

Parameter

string	$fullPath
	(absolute fullpath to template)

Returns

bool

TRUE on success
@throw bs_exception on failure

parse

public void parse( [ string $debug ] )

it's not a real parser, it just searches for <bs ...> tags. fills $this->tags.
you cannot comment out a whole block using . but you can comment outtags using <!tag>.of course $this->templateString has to be set already, which can be done usingloadTemplate().

Parameter

string	$debug	`= >>FALSE<<`
	(default is FALSE). prints out debug information directly to the screen.

Returns

void

applyTag

public bool applyTag( int $tagKey, string $tagString )

applies a tag to $this->templateString.

Parameter

int	$tagKey
	the key of $this->tags for which we insert the tag.

string	$tagString
	the new string to insert into $this->templateString.

Returns

bool

TRUE if the tag was inserted successfully, FALSE if not (key out of bounds or something).

Private Method Details

loadTemplate

private bool loadTemplate( string $template, [ string $type, array $options, string $walkSubdirs ] )

loads the content of a template into $this->templateString.
if you already know the filename/path of the template you can give itwith the first param. you don't need the other params.$status = loadTemplate('products/myProduct.pge.tpl.html');sometimes you don't, you only have the name of your page or form.then you do:$options = array('language'=>'en', 'mode'=>'add');$status = loadTemplate($formName, 'form', $options);and it will search for an appropriate template, also in sub-dirs if specified (slow).the naming of templates goes like this:for pages:syntax: <name-of-page> _ <user> _ <language> .page.tpl. <file-ending>examples: signup__en.page.tpl.htmlsignup__.page.tpl.htmlfor forms:syntax: <name-of-form> _ <mode> _ <state> _ <user> _ <language> .form.tpl. <file-ending>examples: signup_add_form_guest_en.form.tpl.htmlsignup__done__.form.tpl.htmlfor form containers: <name-of-form> _ <name-of-container> _ <mode> _ <state> _ <user> _ <language> .formcontainer.tpl. <file-ending>examples: signup_userdata_add_form_guest_en.formcontainer.tpl.htmlsignup_userdata_____.formcontainer.tpl.htmlname-of-form: the internally used form name. must be given.mode: one of 'add', 'edit', 'delete', or '' (which means it applies for all where no more specific file is available).state: one of 'form', 'preview', 'done'. list not complete yet. i'm not sure if one template can be used for more than one step. guess so.user: not used yet. possible groups are 'guest', 'member', 'admin', 'root' ... would need a session.language: well...file-ending: one of 'html' or 'php'.

Parameter

string	$template
	the filename of the template. may have a part of the path. but no '../' because of security.

string	$type	`= >>'page'<<`
	one of 'page' (default), 'form', 'formcontainer'

array	$options	`= >>array()<<`
	default is an empty array. can be a hash with 0-all of the keys 'mode', 'state', 'user' and 'language'. for 'formcontainer' it also has the key 'name' (=element name).

string	$walkSubdirs	`= >>FALSE<<`
	(go into subdirs recursively? default is FALSE.)

Returns

bool

TRUE on success
@throw bs_exception on failure

_getTemplatePath

private string _getTemplatePath( )

finds out where the templates are or should be and returns the fullpath
to that location.

Returns

string

Throws bool FALSE

apply

private bool apply( [ string $language, string $form, string $editable ] )

has to be called after parse(). means $this->tags must be set already, somehow.
of course also $this->templateString has to be set, which can be done usingloadTemplate().

Parameter

string	$language	`= >>NULL,<<`
	if set it will be applied where appropriate.

string	$form	`= >>NULL,<<`
	the form to use for the forms where no name is set in the xml code or where the name equals to the one of the form. pass it byref.

string	$editable	`= >>FALSE<<`
	default is FALSE. if content blocks should be editable or not.

Returns

bool

TRUE @throw bs_exception (at least at the moment)

Public Field Details
$templatePath
public string $templatePath >><< the absolute path to the template directory. if not set than this class will try to find them usinggetAbsolutePath() . '../templates/'which kinda sucks. so you better set that...

$caseFolding
public string $caseFolding >>`FALSE`<< OVERWRITES PARENT CLASS! should this class do case folding? (make all tags and attributes upper case)default is FALSE. (parent uses TRUE!!)i don't want to use XML_OPTION_CASE_FOLDING here.

Private Field Details
$Bs_String
private object [unknown] $Bs_String >><< reference to the globally used pseudostatic class.

$pageID
private int $pageID >><< the page id for which this instance of templateparser is used. set in the constructor.

$_page
private object [unknown] $_page >><< reference to the Bs_Page object that uses this template parser. i'm not sure if there is always one. so don't be it eather.

$templateString
private string $templateString >><< the content of the template file as one string.

$tags
private array $tags >><< has this structure: $tags[0]['tag'] = 'bs_form';$tags[0]['properties'] = hash output from Bs_Html->parseTag();$tags[0]['subTags'][] = other tags (hashes) like this one.$tags[0]['posStart'] = 105;$tags[0]['posEnd'] = 123;

$_offset
private integer $_offset >><< used in applyTag(). everytime we add something, the tags below move more down. that's what the offset is for.

$this
private unknown $this >><<

Private Constant Details
BS_FORMTEMPLATEPARSER_VERSION `define( BS_FORMTEMPLATEPARSER_VERSION, >>4.0.$x$<< )` Case: default: case sensitive

PHPDoc 1.0beta

BlueShoes Application Framework - Cmt

Bs_FormTemplateParser

public class Bs_FormTemplateParser extends Bs_XmlParser

Methods inherited from Bs_XmlParser

Methods inherited from Bs_Object

Public Method Summary

Bs_FormTemplateParser([ integer $pageID, string $page ])

loadTemplateFromFullpath(string $fullPath)

parse([ string $debug ])

applyTag(int $tagKey, string $tagString)

Private Method Summary

loadTemplate(string $template, [ string $type, array $options, string $walkSubdirs ])

_getTemplatePath()

apply([ string $language, string $form, string $editable ])

Fields inherited from Bs_XmlParser

Public Field Summary

$templatePath

$caseFolding

Private Field Summary

$Bs_String

$pageID

$_page

$templateString

$tags

$_offset

$this

Private Constant Summary

Public Method Details

Bs_FormTemplateParser

loadTemplateFromFullpath

parse

applyTag

Private Method Details

loadTemplate

_getTemplatePath

apply

Public Field Details

$templatePath

$caseFolding

Private Field Details

$Bs_String

$pageID

$_page

$templateString

$tags

$_offset

$this

Private Constant Details

BS_FORMTEMPLATEPARSER_VERSION