Smalltalk/X Webserver

Documentation of class 'HTML::TreeBuilder':

Class: TreeBuilder (in HTML)

Inheritance
Description
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--HTML::AbstractTreeBuilder
      |
      +--HTML::TreeBuilder

Package:: stx:goodies/webServer/htmlTree

Category:: Net-Documents-HTML-TreeBuilder

Version:: rev: 1.140 date: 2023/10/31 11:23:55; user: cg; file: HTML__TreeBuilder.st directory: goodies/webServer/htmlTree; module: stx stc-classLibrary: htmlTree

Description:

HTML tree builder - makes it easier to construct valid HTML-trees.
This class helps to generate html; it provides a message protocol similar to
html itself (i.e. tr; td; tdEdn; trEnd etc.)

How to use:
    1) instantiate a builder with
            HTML::TreeBuilder newDocument
        or 'by hand':
            HTML::TreeBuilder new beginWith:(Document new).

    2) start adding elements to the tree.
       the element-adding protocol looks like the name of the elements;
       for example, #body adds a body-element, #a adds an anchor, #div adds a div element, etc.
       When added, the element becomes the so called 'current' element in the builder.

    3) possibly add attribute(s) to the current element
       For very common attributes like fgcolor, bgcolor, align etc. corresponding protocol
       is available; e.g. align:, fgcolor:, ref: etc.
       Thus, to create a div and set its align attribute, write
            div; align:'left'
       The general interface (for other attributes) is
            attribute:name is:value

    4) close the current element
       Except for br and p (which can be added without corresponding closing elements),
       all other elements must be closed via a corresponding elementEnd message to the builder.
       e.g.
            div; span; text:'foo'; spanEnd; divEnd;

    5) for some very common elements, the opening+closing can be done in a combined message with
       an argument. Thus, a shortcut for
            div; text:'hello'; divEnd
       is:
            div:'hello'
        You can provide a block as argument, so all stuff generated inside becomes child(ren) of
        the outer element:
            div:[ builder text:'hello'; span:'foo'; text:'bla' ]

    6) when finished, use htmlString to have the final html string.

See examples

copyrightCOPYRIGHT (c) 2005 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

return a treebuilder for building a div
(i.e. it starts already with a div top tre element).
This can be used to modularize building of documents, by letting
subbuilder build individual divs, which are later embedded into the
main document

Usage example(s):

     HTML::TreeBuilder newDiv
         style:'border-width: 1px;';
         div;
             text:'Hello World';
         divEnd;
         htmlString

newDocument

return a treebuilder for building a document
(i.e. it starts already with a document top tre element).
This is the normal way to start building.

Usage example(s):

     HTML::TreeBuilder newDocument
         body;
             div:'Hello World';
         bodyEnd;        
         htmlString

Instance protocol:

accessing

currentForm

if inside a form element, return that one.
Otherwise, return nil

htmlString

html of the generated tree so far.
Usually, that is called when the tree building is finished and
the generated html is either to be stored into a file or
to be sent back from a webservice request

Usage example(s):

    GenerateIndentedHTML := true.
    GenerateIndentedHTML := false.

    HTML::TreeBuilder newDocument
        body;
          div;
            text:'Hello World';
          divEnd;
        bodyEnd;
        htmlString

htmlStringWithIndent

html of the generated tree so far.
Usually, that is called when the tree building is finished and
the generated html is either to be stored into a file or
to be sent back from a webservice request

Usage example(s):

    HTML::TreeBuilder newDocument
        body;
          div;
            text:'Hello World';
          divEnd;
        bodyEnd;
        htmlStringWithIndent

htmlStringWithIndent: aBoolean

html of the generated tree so far.
Usually, that is called when the tree building is finished and
the generated html is either to be stored into a file or
to be sent back from a webservice request

assertions

assertCurrentElement: testSelector
assertCurrentElement: testSelector from: caller

attributes

accesskey: accessKeyAttribute

add an 'accesskey=...' attribute to the current element

action: actionURLText

add an 'action=...' attribute to the current (form) element.

Usage example(s):

     HTML::TreeBuilder newDocument
        body;
            form; action:'foo'; formEnd;
        bodyEnd;
        htmlString

align: align

add an 'align=...' attribute to the current element.
The alignment can be left, center, right.

alt: altText

add an 'alt=...' attribute to the current (image) element.

autocomplete: onOffString

add an 'autocomplete=...' attribute to the current element.
if onOffSTring = 'off' gives the browser a hint to not store an input field.
NOTE: this is not W3C standard!

bgColor: colorText

add a 'bgcolor=...' attribute to the current element.

bgcolor: colorText

add a 'bgcolor=...' attribute to the current element.

border: borderWidthInPixels

add a 'border=...' attribute to the current element.

cellPadding: anInteger

add a 'cellpadding=...' attribute to the current element.

cellSpacing: anInteger

add a 'cellspacing=...' attribute to the current element.

cellpadding: cellpadding

add a 'cellpadding=...' attribute to the current element.

cellspacing: cellspacing

add a 'cellspacing=...' attribute to the current element.

checked: aBoolean

add a 'checked=...' attribute to the current element.

class: classString

add a 'class=...' attribute to the current element.

cols: n

add a 'cols=...' attribute to the current element.

colspan: n

add a 'colspan=...' attribute to the current element.

content: contentText

add a 'content=...' attribute to the current element.

crossorigin

add an 'crossorigin' attribute to the current script element.

disabled: aBoolean

add a 'disabled=...' attribute to the current element.

enctype: enctypeText

add an 'enctype=...' attribute to the current element.

for: targetID

add an 'for=...' attribute to the current element.

frameborder: frameborder

add an 'frameborder=...' attribute to the current element.

framespacing: framespacing

add an 'framespacing=...' attribute to the current element.

height: aNumberOrPercentString

add an 'height=...' attribute to the current element.

href: href

add an 'href=...' attribute to the current element.

http_equiv: httpEquivText

add an 'http-equiv=...' attribute to the current meta element.

language: source

add an 'language=...' attribute to the current element.

leftMargin: leftMargin

add an 'leftmargin=...' attribute to the current element.

leftmargin: leftMargin

add an 'leftmargin=...' attribute to the current element.

marginheight: marginheight

add an 'marginheight=...' attribute to the current element.

marginwidth: marginwidth

add an 'marginwidth=...' attribute to the current element.

maxLength: sz

add an 'maxlength=...' attribute to the current element.

media: typeString

add an 'media=...' attribute to the current element.

method: methodText

add an 'method=...' attribute to the current (form) element.

multiple: multiple

add an 'multiple=...' attribute to the current element.

nlsValue: nlsString

add an 'value=...' attribute to the current element.
The given string will be translated to a national language via the
resource information in the instvar optionalResources

noshade

add an 'noshade' attribute to the current element.

nowrap

add an 'noshade' attribute to the current element.

onLoad: action

add an 'onLoad=' attribute to the current element.

onSubmit: action

add an 'onSubmit=' attribute to the current element.

rel: relText

add a 'rel=' attribute to the current element.

rows: n

add a 'rows=' attribute to the current element.

rowspan: n

add a 'rowspan=' attribute to the current element.

rules: rulesText

add a 'rules=' attribute to the current table element.

script: aJavaScript

add a script to the current anchor element.

scrolling: aBooleanOrStringOrSymbol

add a 'scrolling=' attribute to the current element.

selected

add a 'selected' attribute to the current element.

selected: aBoolean

add a 'selected=' attribute to the current element.

size: sz

add a 'size=' attribute to the current element.

src: source

add a 'src=' attribute to the current element.

style: moreStyle

add a 'style=' attribute to the current element.
This may be sent multiple times to add more styles to the same element

Usage example(s):

     HTML::TreeBuilder new
        div style:'vertical-align: middle;';
        text:'hello';
        divEnd;
        htmlString

tabindex: anInteger

add a 'tabindex=' attribute to the current element.

target: targetText

add a 'target=' attribute to the current element.

title: titleText

add a 'title=' attribute to the current element.

tooltip: tooltipText

tooltip: defaults to a title here; can be redefined for nicer tooltips
(multipline, using a hiver-visible div) in subclasses

type: typeString

add a 'type=' attribute to the current element.

valign: align

Set the vertical align of the table/cell (top|middle|bottom|baseline).

value: valueString

add a 'value=' attribute to the current element.

vspace: verticalSpace

add a 'vspace=' attribute to the current element.

width: aNumberOrPercentString

add a 'with=' attribute to the current element.

building

a

start an anchor <a> element

a: textOrBlock

add <a> ... </a>.
If the argument textOrBlock is a string, then it will be added as text-child of the anchor.
Otherwise, it is supposed to be a block which is evaluated.
The block is then responsible for adding alements as required.

Usage example(s):

     HTML::TreeBuilder newDocument
         a:[ Time now printString ];
         htmlString

a: textOrBlock href: href

add an anchor with text and hyper link

aEnd

finish the current anchor element

blockQuote

start a blockquote element

blockQuote: textOrBlock

finish a blockquote

start a body element

add a body element

finish the body

add a <br>

br: timesRepeat

center

center: textOrBlock

centerEnd

comment: aComment

commentAttribute: aComment

div

this is undefined behavior (block inside inline)

div: textOrBlock

divEnd

doesNotUnderstand: aMessage

not sure, if it's a good idea to fix things on the fly...

embed

embed: objectSourceURL

h1

h1: textOrBlock

h1End

h2

h2: textOrBlock

img: imageSourceURL

you have to use <object data="algerie.svg" type="image/svg+xml"></object>

noBr

noBr: textOrBlock

object: aString type: typeString

p

p: someTextOrBlock

HTML::TreeBuilder htmlContentsOf:[:html |
html p:'hello world'
]

Usage example(s):

     HTML::TreeBuilder htmlContentsOf:[:html |
        html p:[ html rawText:' ' ]
     ]

Usage example(s):

     HTML::TreeBuilder htmlContentsOf:[:html |
        html p:[ html center; text:'hello'; centerEnd ]
     ]

pEnd

pre

pre: someTextOrBlock

span: textOrBlock

spanEnd

building-conditional

forEach: collection do: action
if: condition then: action: allows us to write:
page
div;
if:[Date today dayInWeek == 1] then:[page nlsText:'foobar']
divEnd

i.e.: no need to break out of the cascade and start again
if: condition then: action else: action2: allows us to write:
page
div;
if:[Date today dayInWeek == 1] then:[page nlsText:'foobar']
divEnd

i.e.: no need to break out of the cascade and start again
while: condition do: action: allows us to write:
page
div;
if:[Date today dayInWeek == 1] then:[page nlsText:'foobar']
divEnd

i.e.: no need to break out of the cascade and start again

building-forms

button

buttonEnd

form

cannot be nested

Usage example(s):

convert values of this form to url encoded values (by javascript -> a static encoding 
     independent of the browser) if they include anything > 127.  
     this is a workaround to be independent of the encoding defined in the meta data.
     because the browsers (ff, ie, chrome) do encode the url(get) & post data 
     dependent on the defined encoding or if none encoding is defined,
     they encode it like they prefer -> unknown behavior...

     even if we set #encType:'application/x-www-form-urlencoded', the browser
     will do different encodings depending on the encoding defined in the meta data

     so #decodeFields: does not know how to handle its input. input for e.g.:
        '%E4' did the user enter '%E4'? is this value the character ä (228)? does '%E4' starts a 3 byte utf8 sequence? 
            for e.g. the browser does escape $ä to a 2 byte utf8 sequence -> %c3%a4

     to be able to do it 100% correct, 
     #decodeFields: needs to know the #encType, the meta encoding and all specific browser behaviors -> impossible
     the following workaround works in any case (as long as stx applications do communicate with each other) 

     -> see HTTPRequest #decodeFields

building-head

base: add a base element to the current element.
head
headEnd
link: add a link element
meta: add a meta element

building-lists

dl: start a dl-list
dlEnd: finish a dl-list
ol: start an ol-list
olEnd: finish an ol-list
ul: start a ul-list
ulEnd: finish a ul-list

building-tables

caption
captionEnd
col
colgroup
colgroupEnd
li
liEnd
table
tableEnd
tbody
tbodyEnd
td
tdEnd
tfoot
tfootEnd
th
thEnd
thead
theadEnd
tr
trEnd

building-text attributes

bold: start a bold element
bold: textOrBlock
boldEnd: finish a bold element
code
code: textOrBlock
codeEnd
strong
strong: textOrBlock
strongEnd

instance release

release

obsolete

display: aDisplayStringOrBoolean: arg must be one of true, false or the strings: 'block', 'none', 'inline-block'

** This is an obsolete interface - do not use it (it may vanish in future versions) **
visibility: visibilityStringOrBooleanOrBlock: arg must be one of true, false or the strings: 'visible', 'hidden', 'collapse'

** This is an obsolete interface - do not use it (it may vanish in future versions) **

printing & storing

printHtmlOn: aStream

html of the generated tree so far.
Usually, that is called when the tree building is finished and
the generated html is either to be stored into a file or sent back
from a webservice request

Usage example(s):

 HTML::TreeBuilder newDocument
     body;
       div;
         text:'Hello World';
       divEnd;
     bodyEnd;
     printHtmlOn:Transcript

setup

beginDocument

start building with an initial document-element as root element

Usage example(s):

     |b|

     b := self new beginDocument.
     b
       table;
        tr;
         td;
         tdEnd;
         td;
         tdEnd;
        trEnd;
       tableEnd.
     b htmlString

Examples:

     |b|

     b := HTML::TreeBuilder new.
     b
        html;
          head;
          headEnd;
          body;
            table;
              tr;
                td; text:'hello'; tdEnd;
                td; text:'world'; tdEnd;
              trEnd;
            tableEnd;
          bodyEnd;
        htmlEnd.
     b htmlString inspect.

     |b|

     b := HTML::TreeBuilder new beginWith:(Document new).
     b 
        head;
        headEnd;
        body;
          table;
            tr;
              td; tdEnd;
              td; tdEnd;
            trEnd;
          tableEnd;
        bodyEnd.
     b rootElement inspect.
     b htmlString inspect.

     |b|

     b := HTML::TreeBuilder new.
     b 
        span;
          table;
            tr;
              td; tdEnd;
              td; tdEnd;
            trEnd;
          tableEnd;
        spanEnd.
     b rootElement inspect.

     |b|

     b := HTML::TreeBuilder new beginWith:(Body new).
     b 
        textArea;
           rawText:'line1';
           rawText:'line2';
           rawText:'line3';
           rawText:'line4
line5
line6';
        textAreaEnd.
     b rootElement printOn:Transcript.
     b rootElement htmlString inspect.

     HTML::TreeBuilder htmlContentsOf:[:html | 
        html
            body;
                h1:'headLine';
                p; text:'Hello world'; pEnd;
            bodyEnd.
     ].

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 19 May 2024 20:36:35 GMT

Smalltalk/X Webserver

Documentation of class 'HTML::TreeBuilder':

Class: TreeBuilder (in HTML)

Inheritance:

Description:

copyright

Class protocol:

Instance protocol:

Examples: