NAME

WWW::Kontent::Skeleton - Kontent skeleton (syntax-independent document formatting tree) class

SYNOPSIS

my $skel=WWW::Kontent::Skeleton.new();
$skel.add_node(:tagname<header>, :level(1)).add_text("Merlin's beard!");
$skel.add_node(:tagname<paragraph>);
$skel.children[0].add_tag("Hermione cried.");

DESCRIPTION

The skeleton--a simple, passive N-ary tree--is used to pass information about the page's content and formatting to a renderer to be rendered in the appropriate format. The tagname attribute contains a string specifying the formatting code to be applied, and the children attribute contains an array of child nodes--either other WWW::Kontent::Skeleton objects or plain strings containing text. Any other properties of the node are kept in the properties attribute.

Plain strings should be preserved in the actual document as closely as possible; escaping and tagging should be performed so that all content--including whitespace--is displayed.

Valid tagnames

skeleton

This should always be the top-level node of a skeleton, and may also appear within the skeleton. It does not imply any semantic.

null

The null node implies no semantics, but its children should be processed.

paragraph

Represents a paragraph of information.

header

Has one property, level, ranging between 0 and 4, with lower numbers being more important. Level 0 is reserved for the page's title. (Higher levels are possible but may not be supported by all renderers.)

list

Represents a list of some kind. Has one property, type, which may contain any of "bulleted", "numbered", or "definition". Children must be items.

Note: Future versions of Kontent are expected to implement definition lists in a different way than they are currently.

item

Represents an item in a list. In a definition list, the type property can be set to term to indicate the item in question is a term, rather than a definition.

table

Represents a table. Its children are row nodes, whose children are cell nodes.

row

Represents a row in a table. Its children must be cell nodes.

cell

Represents a cell in a table row. If the type property is set to header, the cell should be treated as a header cell.

emphasis

Indicates that its child nodes should be emphasized in some manner, usually by italicizing.

strong

Indicates that its child nodes should be given strong emphasis, usually by bolding.

title

Indicates that its child nodes should be formatted as if they are the title of a book or other work.

struck

Indicates that its child nodes should be crossed out or otherwise visibly "deleted".

superscript

Indicates that its child nodes should be formatted as a superscript.

subscript

Indicates that its child nodes should be formatted as a subscript.

code

Indicates that its child nodes should be formatted as a piece of code. If the type field is set to paragraph, the code should be treated as a separate paragraph and possibly indented.

link

Represents a hyperlink. Has one property, location, containing a Kontent path or fully-qualified URL. (Kontent paths will never have a colon in them, while URLs always will.) If a link node has no children, most renderers will fill in the page's title.

transclude

Represents a transclusion, indicating that the textual content of the page indicated by location should be inserted into the current page. This is usually achieved through use of a subrequest.

form

Creates a fill-in form, which when submitted will return to the same page, mode and format as is currently in use.

textfield

Creates a fill-in field for a string of text. The name property gives the name the field's content should be returned as; value indicates the current value of the field; and label gives an optional text label to be displayed for the field. The type property, when set to the value multiline, tells the renderer that a large, multiple-line block of text should be expected.

boolfield

Creates a fill-in field for a boolean value (often a checkbox). The name, value and label properites work as above.

choicefield

Creates a fill-in field for one of several choices. The name, value and label properties work basically as above. The default rendering is usually a drop-down box; however, if type is set to action, the name will also be forced to equal action, and the form will be submitted once an action is chosen. Action fields are often displayed as a set of buttons.

choice

Each choicefield should have several choices. The value property gives the value associated with this choice; any nodes under this one will be used to determine the label text for the choice.

metafield

A metafield is an invisible field carrying information back to the server. The name and value properties work basically as above.

!

A node whose name consists solely of an exclamation point indicates a warning message, usually meaning that the parser found an error in the markup used to generate the skeleton. Each warning has a message, kept (appropriately enough) in its message property.

Warnings should be displayed in a noticable but non-disruptive fashion; in the HTML renderer, for example, they take the form of a red exclamation point with a tooltip containing the message.

Methods

add_node

Creates a new node and appends it to the current node's list of children. The tag name is passed as the first parameter; any named parameters are treated as node properties.

add_text

Appends one or more text nodes to the current node's list of children.

dump()

Returns an array of strings representing the skeleton from the current node down; each string should be treated as a separate line.

text()

Assembles a string consisting of all text nodes below the current node, concatenated together.

SEE ALSO

WWW::Kontent