Building HTML Pages

Rumba provides two objects for building web pages: HTMLDocument and HTMLElement. In addition there are various functions and methods for manipulating HTML documents and for adding common widgets (like an input and label combination) to a page. These widgets are simply functions that call HTMLElement, set various attributes, in order to build up commonly occurring patterns in web page design. All HTML related functions are in the Rumba.HTML namespace.

To create a document, use the NewHTMLDocument function:

      d←NewHTMLDocument ''

The Add method adds an element to the document, and returns the new element as its result:

      p1←d Add 'p'

An optional additional argument, containing plain text, or content, may be provided to Add:

      p2←d Add 'p' 'This is some content.'

The Add function can add content to an existing element:

      _←p2 Add ''  ' This is more content.

And it can Add a new element to an existing element:

      s1←p2 Add 'span'

The NewHTMLElement method may be used to create a new element without adding it to a document:

      p3←NewHTMLElement 'p'

A stand-alone element may be added to the document or other element using the Add function:

      _←d Add p3

The NewHTMLElement function can create a new element and add it to an existing element or document by providing a left argument:

      p4←d NewHTMLElement 'p' 'This is a paragraph.'

Attributes are added by simple assignment into an element:

      p4.class←'normal'

These three functions NewHTMLDocument, NewHTMLElement, and Add, provide the basic building blocks of a web page. In fact, as NewHTMLDocument is easily constructed from Add, only NewHTMLElement and Add are strictly necessary. However, certain patterns will occur frequently, and the good programmer will extract these patterns as functions. Rumba provides a set of widgets built up using Add and NewHTMLElement that are used for the Rumba Admin site. These can be used as a starting point for your own web site, and provide a design guideline as well.

These widgets functions all start with "New", and take an optional left argument as a parent for the new widget. The right argument to a widget function will vary depending on the widget. For example the NewLink function takes a URL and a description for a right argument:

       l←NewLink '/My/Path' 'Click me'

The result a widget function is the widget's top-level element. For example, the NewTextField function returns a div that encapsulates an input and a label. Widgets will often set pointers to elements of interest, insulating the programmer from changes. The result of NewTextField has an Input property which points to the input element of the widget.