Packages » Package html

Package html

Description:
The HTML package is the Document interface implementation and allows you to generate responce documents from template files. It supports custom tags to render complex, iterable and conditional content, multiple client types, gzipping of documents and server-side caching of templates.

See also:

Authors:
  • Dennis Popel

Interfaces:
  • HTMLInputFieldRenderer
    This interface must be implemented by all InputFields that are compatible with the HTMLDocument. The renderers may return either raw HTML strings or instances of HTMLElements wich will be inserted in place of the corresponding HTMLInput tags in the source template.

Classes:
  • HTMLAbstractDocument
    This is the base class for documents that the html package produces. This class is abstract and encapsulates templates processing. Its children classes will override several methods that provide metainformation (like headers) to the consumer of the document.
  • HTMLDateTime
    This tag displays formatted date. The template variable name holding the timestamp to display is passed via the key attribute, and the format is specified by the format attribute. Note that the timestamp must always be the UNIX timestamp, i.e., it is considered to be the GMT time (exactly as returned by the time() function). The time displayed will be adjusted to the timezone of the document's locale. If no timestamp given (i.e., the key attribute points to an invalid template variable), the current time will be displayed. If there is no locale set for the document, this tag will use strftime function to format the date and time according to the value of the format attribute. If there is no format attribute specified, this tag will revert to the locale's default; if there is no locale, it will use the "%H:%M:%S GMT" format string. Note
    Since the format string uses the '%' symbol, make sure you have not template variables named like first format specifier or include a leading space in the format attribute. The format string is the same as for PHP strftime function (also see I18NLocale::formatDateTime for notes). Since 1.2.0.Beta this tag supports the mode attribute, which, if present, must contain either 'date' or 'time' strings. If so, the meaning and values for the format attribute change: it must be either 'short', 'long' or 'full'. If these conditions are met, this tag will use the I18NLocale::formatDate or I18NLocale::formatTime methods depending on the value of the mode attribute. The format specifier will be either I18N::SHORT, I18N::LONG or I18N::FULL depending on the value of the format attribute value.
  • HTMLDocument
    This class produces HTML documents.
  • HTMLIfInputFieldError
    This is a conditional tag that will display its body only if the specified form input field did not validate (was filled incorrectly). It can be used only within the HTMLShowForm tag. Its sole attribute, key denotes the name of the input filed in the form.
  • HTMLIfInputFieldErrors
    This is a conditional tag that will display its body only if the specified form is invalid. The form is denoted by the key attribute, which holds the template variable name of the actual form.
  • HTMLIfNotSet
    This is a conditional tag that will display its body if the template variable denoted by the key attribute evaluates to false ir is null.
  • HTMLIfNotUser
    This is a conditional tag that will display its body if there is no user in the current session.
  • HTMLIfSet
    This is a conditional tag that will display its body if the template variable denoted by the key attribute evaluates to true (is not false and is not null).
  • HTMLIfUser
    This is a conditional tag that will display its body if there is current user in the current session. The optional role attribute can be used to enforce additional check of the user's role via a call to User::isRole.
  • HTMLImage
    This tag is used to embed dynamic images that are generated by other action rather that are static files. You specify the location of the action with the key attribute that must point to a valid Location object. Since 1.1.1 you also can show resource images. This tag will employ content negotiation techniques to allow the remote client to cache the image. To show a resource image, you specify the name attribute and optionally the package attribute to locate the image. If you do not specify the package then this tag will assume the image is located in the package where the default action was declared (i.e., it will analyze the action.default configuration option from the freeform package. If in the template there is no alt attribute, this tag will set it to the file name of the image.
  • HTMLIncludeFile
    Include an external template file into the current template
  • HTMLInput
    This tag displays a single input field of the form. The only required is the name attribute that specifies the name of the template variable that holds the InputField object. Along this attribute you may specify styling and scripting attributes that will be preserved in the resulting HTML tag. Note that you cannot specify the type or value attributes in the tag.

    This tag can only be used within the HTMLShowForm tag.
  • HTMLIterableInfo
    This class encapsulates information needed for the HTMLShowPagination tag to render custom URLs for pagination links. By default, this tag will render URLs based on the current page URL, with special parameter page pointing to the requested page number. Using this class you can force HTMLShowPagination to render custom URLs (including extra parameters and even another Action).
  • HTMLLink
    This class represents a tag that creates a hyperlink to another action. The only required attribute is the key that specifies the name of the template variable that holds a Location object of the destination action. You may also include styling and scripting attributes that will be preserved in the resulting a tag.
  • HTMLNumberFormat
    This tag is used to format numbers and prices in locale-specific manner. It tries to get the document's locale and use it to format the number. The number to format is denoted by the key attribute that should hold the name of the template variable containing the value. Immediate value can be specified by the value attribute. By setting the mode attribute to price, this tag will format the value as if it were price.
  • HTMLPHPSource
    This tag is used to automatically highlight PHP source in your templates. You use it like any other formatting tag, just enclose the code you want to highlight with this tag:
     <HTMLPHPSource>
        $x = $y + 2;
        $z = doMath($x, $y);
        print $z;
     </HTMLPHPSource>
              Please note you do not enclose the source with the PHP open and close tags! You can also use template variables inside this tag, if you preset them with valid fragment of PHP source code. Please note that inside this tag you will not be able to use the less-than sign as the parser will consider it a beginning of a new tag. Instead, just use the < entity reference like: $x <= 10
  • HTMLPINode
  • HTMLRSSDocument
    This class produces RSS documents.
  • HTMLRegion
    This tag allows you to define regions within your templates. A region can be shown later in the template, possibly at several places. The concept of region is similar to that of an included template; however, regions are parsed only once, when they are declared with this tag, while included files are parsed every time they get loaded by HTMLIncludeFile tag. Regions are declared and retrieved by names. It is possible to create a region outside the template (programatically) and to set it via a call to HTMLDocument::setRegion to later show those regions in the resulting document. You show regions with the HTMLShowRegion tag in the template. The region can be forced to be shown by setting this tag's show attribute to true. Names are declared with the name attribute of this tag. For example,
     <HTMLRegion name="header">
       <b>Welcome to our site</b>
       <hr />
     </HTMLRegion>
              will create a header region in the document. You can show this region later with the following markup:
     <HTMLShowRegion name="header" />
              that will display
       <b>Welcome to our site</b>
       <hr />
              Regions are handy when it comes to repeatable content, especially when the same template is used by more than one HTMLShowIterable tags. For example, freddy uses the same region for displaying list of classes and interfaces in the package viewer: the classes and interfaces are presented by the same data types but stored in two different Iterables. Note
    You should not use HTMLIncludeFile within a region for performance reasons. The difference between the two is in that that the region is parsed only once upon its definition while the included file is parsed on every inclusion. You can define all your common regions in a single external template file and include it into every page with the HTMLIncudeFile tag; in the page, you can reuse the regions as you need to improve performance.
  • HTMLShowForm
    This is the tag to show input form in the HTMLDocument. In the template, open the form like:
     <HTMLShowForm key="(name of the template variable that holds Form object)">
       <HTMLInput name="(name of the template variable that holds InputField object)" />
       ...
     </HTMLShowForm>
              Note that you will have to prepare template variable and declare the HTMLShowForm's key attribute to be the name of the variable. You can also include the styling and scripting attributes, but not the method, enctype or action attributes. You use the HTMLInput tags to display input fields. Note that the only required attribute is "name" that must match the name of the field as it was added to the form. The HTMLInput will detect the InputField's type and supply corresponding html code to display textares, passwords, check boxes, file upload and select fields.
  • HTMLShowHtml
    This tag allows you to display variables that contain markup which you don't want to get escaped. Normally, when you display variable contents in a template with {%varName} notation, content of that variable is passed through htmlSpecialChars() function. If, however, that variable contains HTML that you do want to display, you can use this tag like:
    <?

         ...
     <    HTMLShowHtml key="varName" />
     ...
     
    ?>     Please note, however, that if the variable contains invalid HTML, the validity of the resulting document can change.
  • HTMLShowImage
    This is a helper action that implements the Document interface to display a resource image by the HTMLImage tag. Requires proper installation of GD. The images served will be marked with the ETag response header, and upon subsequent requests, it will be compared with the If-None-Match request header; and if there is a match, only the HTTP/1.1 304 Not Modified header will be returned.
  • HTMLShowIterable
    This tag is used to iterate over on Iterable and repeat its content on each iteration. You specify the iterable in the sole key attribute of this tag which holds the template variable name of the iterable object. If the value returned by the Iterable::getNext() is non-scalar (i.e., it is an array or an object), its key-value pairs or properties will be extracted into the current variable stack so that they can be later accessed by the {%varName} construct. If the value returned is scalar, it will be available via the {%html.showiterable.value} variable in the body of this tag. The tag will also maintain current position counter in the {%html.showiterable.position} variable. If the iterable is an instance of the PaginatedIterable then the position counter will hold the actual (real) position of iterable, taking into account current page number. Besides, the following variables will be defined: {%html.showiterable.start} - the starting row number
    {%html.showiterable.end} - the ending row number
    {%html.showiterable.page} - the current page
    {%html.showiterable.pagescount} - the total number of pages in the iterable
    {%html.showiterable.total} - the total number of rows in the iterable (regardless of paging)


    This tag also recognizes some pseudo-tags:
    • separator - defines a piece of markup that will be output after each iteration if there still are more items
    • ifnotempty - defines a piece of markup that will be output before the first iteration
    • ifempty - defines a piece of markup that will be output if the iterable is empty
    • ifodd - will be displayed on every odd iteration
    • ifeven - will be displayed on every even iteration
  • HTMLShowObject
    This tag is used to extract key-value pairs of an array or properties of an object into the current variable stack so that you can access them atomically by the {%varName} construct. Its only attribute, key, keeps the name of the template variable that holds the actual array or object to display.

    Since 1.2.0.RC this tag will also call all public getXXXX()/isXXXX methods of the object which do not accept parameters and expose their values thru the corresponding XXXX template variables (for example, the return value of the $obj::getProperty() method will be available as the property template variable). Please note that the first letter of the template variable will be lowercased. Also this tag will create a special template variable, __this, which will contain the object/array itself.
  • HTMLShowPagination
    This tag is used to display a pagination bar for a PaginatedIterable. It allows you to easily format the pagination bar, display stylish header or footer, use images for prev/next/first/last links etc. Essentially it will generate a series of Location objects that will point to the current action but will have a special parameter page set to point to different page numbers. So doing, you will have just one action that can easily display differene pages of a longer iterable. It requires the key attribute to be present and to point to a paginated iterable object. You can optionally specify the displaypages attribute to set the number of page links shown on a single page. If there are more pages than this value, the entire bar will scroll, trying to place the current page number in the center. For every page number, the following variables are created: {%html.showpagination.link} - the Location object for every page
    {%html.showpagination.page} - the current page number


    This tag also recognizes some pseudo-tags:
    • separator - defines a piece of markup that will be output after each iteration if there still are more pages
    • ifnotempty - defines a piece of markup that will be output before the first iteration
    • ifempty - defines a piece of markup that will be output if the iterable is empty
    • firstpage - will be displayed before everything else; you can create the link to the first page here
    • prevpage - will be displayed after firstpage pseudo-tag; use it to create a link to the previous page
    • nextpage - will be displayed after the bar; you can create the link to the next page here
    • lastpage - will be displayed last; use it to create a link to the last page
    • current - will be displayed for the iterable's current page; you can use this pseudotag to specially format the 'current' page. In case you do not provide this pseudotag, the current page link will be rendered like all other links
    Inside the last foru pseudo-tags you use the {%html.showpagination.link} and {%html.showpagination.page} variables to create the links.
  • HTMLShowRegion
    This tag displays previously defined region with the name specified in the name attribute
  • HTMLTag
    The HTMLTag is the base class of tags in HTML Document API. It allows you to control various aspects of tag behaviour and create complex views with a single tag. The tags effectively constitute the View components in the MVC architecture.

    All tags can have children - either other tags (i.e, HTMLTag or its subclasses instances) or text nodes (HTMLTextNodes). The tag can be exposed (this means that its open and close html tag strings will be output) and/or enabled (this means that the tag will not output anything).

    Instances of HTMLTag and subclasses are created once per document lifetime by the template parser. If it discovers a tag whose name matches a HTMLTag subclass, it will instantiate it and add it to the tag tree. After the parser builds the tag tree, the HTMLDocument will process the tags. It starts from the root element (the
  • The HTMLTag::onOpen() method is called. This is where all internal states are set if the tag sees it can not display its body, the onOpen() should return HTMLTag::SKIP_BODY; otherwise it sould return HTMLTag::PROCESS_BODY;
  • If the tag returns PROCESS_BODY, its HTMLTag::isExposed() method is checked whether to include the html open/close tags in the responce (for example, HTMLShowIterable is not exposed, so you will not see it nowhere in the responce)
  • If the tag has children:
    1. its HTMLTag::onBeforeBody() method is called;
    2. its children are processed;
    3. its HTMLTag::onAfterBody() method is called;
    4. if the HTMLTag::isRepeatBody() returns true, the step 3 is repeated
  • if the tag's body was processed, the HTMLTag::onClose() method is called to reset all internal states.
    • The tag is processed only if it is enabled (HTMLTag::isEnabled() returns true). The HTMLTag supports access to document variables in its attributes. If an attribute contains a value in form '%variableName', then the tag will try to find the specified variable in the document stack in a call to HTMLTag::getAttribute(). Tags can change their names and attributes when the template processes them. For instance, HTMLLink tag (a and remove the key attribute and add the href attribute. However, it should be noted that the same instance can be processed multiple times in a template, so it is important to restore the tag state and its children state in the HTMLTag::onClose() method. Also tags must preserve same name after HTMLTag::onOpen() and HTMLTag::onClose() because the template generates html markup after these methods. There are many situations when the tags are constructed not by the parser from the template, but by another tags that render compex views. In these cases the attributes can contain non-string values also; the created tags can access these values to render their representation according to their semantics. NOTE: you must add all custom tag class names to the .spi file so that the runtime will be able to resolve them
  • HTMLTextNode
    This is the text node that represents text sections in source template. This class has some features that allow to use it for programming custom tags. The text node, if discovered by parser, is set to non-raw mode that means that when displaying the node content, all markup characters will be escaped with htmlSpecialChars() and template variables will be interpolated. Custom tags can create child text nodes and set them to raw mode so that they will be able to contain markup elements. This is useful if you want to create a tag that highlights PHP source - you can design it so that it will add a child text node, set it to raw mode, pump the PHP source through source hiliter (which will return html-formatted string) and feed the result to the setContent() method. If this text node will be processed by the HTMLDocument, the hiliting will be displayed. If the node were in non-raw mode, the HTML source would appear instead.