eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'HTML::TreeBuilder':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: TreeBuilder (in HTML)


Inheritance:

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

Package:
stx:goodies/webServer/htmlTree
Category:
Net-Documents-HTML-TreeBuilder
Version:
rev: 1.118 date: 2019/07/13 12:20:51
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


Class protocol:

constants
o  prefixOfUrlEscapedInputField

html generation
o  htmlContentsOf: aBlock
inject a new builder into a block, return what is generated there

usage example(s):

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

instance creation
o  newDiv
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

o  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
o  currentForm
if inside a form element, return that one.
Otherwise, return nil

o  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 sent back
from a webservice request

usage example(s):

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

attributes
o  accesskey: accessKeyAttribute
add an 'accesskey=...' attribute to the current element

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

usage example(s):

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

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

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

o  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!

o  bgcolor: colorText
add a 'bgcolor=...' attribute to the current element.

o  border: borderWidthInPixels
add a 'border=...' attribute to the current element.

o  cellPadding: anInteger
add a 'cellpadding=...' attribute to the current element.

o  cellSpacing: anInteger
add a 'cellspacing=...' attribute to the current element.

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

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

o  checked: aBoolean
add a 'checked=...' attribute to the current element.

o  class: classString
add a 'class=...' attribute to the current element.

o  cols: n
add a 'cols=...' attribute to the current element.

o  colspan: n
add a 'colspan=...' attribute to the current element.

o  content: contentText
add a 'content=...' attribute to the current element.

o  disabled: aBoolean
add a 'disabled=...' attribute to the current element.

o  enctype: enctypeText
add an 'enctype=...' attribute to the current element.

o  for: targetID
add an 'for=...' attribute to the current element.

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

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

o  height: aNumberOrPercentString
add an 'height=...' attribute to the current element.

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

o  http_equiv: httpEquivText
add an 'http-equiv=...' attribute to the current meta element.

o  language: source
add an 'language=...' attribute to the current element.

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

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

o  maxLength: sz
add an 'maxlength=...' attribute to the current element.

o  media: typeString
add an 'media=...' attribute to the current element.

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

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

o  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

o  noshade
add an 'noshade' attribute to the current element.

o  nowrap
add an 'noshade' attribute to the current element.

o  onLoad: action
add an 'onLoad=' attribute to the current element.

o  onSubmit: action
add an 'onSubmit=' attribute to the current element.

o  rel: relText
add a 'rel=' attribute to the current element.

o  rows: n
add a 'rows=' attribute to the current element.

o  rowspan: n
add a 'rowspan=' attribute to the current element.

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

o  script: aJavaScript
add a script to the current anchor element.

o  scrolling: aBooleanOrStringOrSymbol
add a 'scrolling=' attribute to the current element.

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

o  selected: aBoolean
add a 'selected=' attribute to the current element.

o  size: sz
add a 'size=' attribute to the current element.

o  src: source
add a 'src=' attribute to the current element.

o  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

o  tabindex: anInteger
add a 'tabindex=' attribute to the current element.

o  target: targetText
add a 'target=' attribute to the current element.

o  title: titleText
add a 'title=' attribute to the current element.

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

o  type: typeString
add a 'type=' attribute to the current element.

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

o  value: valueString
add a 'value=' attribute to the current element.

o  vspace: verticalSpace
add a 'vspace=' attribute to the current element.

o  width: aNumberOrPercentString
add a 'with=' attribute to the current element.

building
o  a
start an anchor <a> element

o  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

o  a: textOrBlock href: href
add an anchor with text and hyper link

o  aEnd
finish the current anchor element

o  blockQuote
start a blockquote element

o  blockQuote: textOrBlock

o  blockQuoteEnd
finish a blockquote

o  body
start a body element

o  body: aBlock
add a body element

o  bodyEnd
finish the body

o  br
add a <br>

o  center

o  center: textOrBlock

o  centerEnd

o  comment: aComment

o  commentAttribute: aComment

o  div
self assert:currentElement isTable not.

o  div: textOrBlock

o  divEnd

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

o  embed

o  embed: objectSourceURL

o  h1

o  h1: textOrBlock

o  h1End

o  h2

o  h2: textOrBlock

o  h2End

o  hr

o  html

o  html: aBlock

o  htmlEnd

o  iframe

o  iframeEnd

o  img: imageSourceURL

o  noBr

o  noBr: textOrBlock

o  noBrEnd

o  nobr

o  nobrEnd

o  noscript

o  noscriptEnd

o  p

o  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 ]
     ]    

o  pEnd

o  pre

o  pre: someTextOrBlock

o  preEnd

o  script

o  scriptEnd

o  span

o  span: textOrBlock

o  spanEnd

building-forms
o  button

o  buttonEnd

o  form
cannot be nested

usage example(s):

convert values of this form to url encoded values if they include unicode.  
     used to support unicode characters like '%u884C'.
     because the browser (ff, ie, chrome) converts this unicode char into '行' before sending  
     and the server (we) can not figure out if the user did enter '行' or the real unicode character.
     -> see HTTPRequest #decodeFields

o  formEnd

o  input

o  label

o  labelEnd

o  option

o  optionEnd

o  select

o  selectEnd

o  textArea

o  textAreaEnd

o  textarea

o  textareaEnd

building-head
o  base
add a base element to the current element.

o  head

o  headEnd

o  link
add a link element

o  meta
add a meta element

building-lists
o  dl
start a dl-list

o  dlEnd
finish a dl-list

o  ol
start an ol-list

o  olEnd
finish an ol-list

o  ul
start a ul-list

o  ulEnd
finish a ul-list

building-tables
o  caption

o  captionEnd

o  col

o  colgroup

o  colgroupEnd

o  li

o  liEnd

o  table

o  tableEnd

o  tbody

o  tbodyEnd

o  td

o  tdEnd

o  tfoot

o  tfootEnd

o  th

o  thEnd

o  thead

o  theadEnd

o  tr

o  trEnd

building-text attributes
o  bold
start a bold element

o  bold: textOrBlock

o  boldEnd
finish a bold element

o  code

o  code: textOrBlock

o  codeEnd

o  strong

o  strong: textOrBlock

o  strongEnd

instance release
o  release

obsolete
o  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) **

o  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
o  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
o  beginDocument
start building with an initial document-element as root element


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.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 19 Mar 2024 11:23:29 GMT