The Document is the central object in Jolene. It's the parent of most objects you will work with. The Jolene document object model (DOM) has some similarities to the JavaScript DOM but it's simpler because it does not contain layout elements like div, span and table. Instead it only contains data related elements that a web developer would be interested in like label, input and select. This provides a true separation of concerns between web designers and web developers.
The DOM is structured like this:
These document objects directly represent the components and elements of a HTML document. Body, headers, forms and form elements are HTMLElement objects and doctype and title are simple strings.
These elements all extend the HTMLElement object and share common properties and methods.
The Button represents a HTML button element. This is sometimes referred to as an advanced button as its content can contain other HTML text. Jolene sees this inner HTML text as plain text - in other words - there is no inner DOM for the content. A common element inside a button would an image. Note that a Button has both a content and a value.
Example:
In your document:
<button name="MyButton" value="test">test</button>
In your code:
Image img = new Image();
img.setAttribute("src", "/img/smile.png");
img.setAttribute("alt", "Smile");
img.setAfterText(" click me!");
button.setContent(img);
button.setValue("Click");
Which would output:
<button name="MyButton" value="Click"><img alt="Smile" src="/img/smile.png"> click me!</button>
The CheckBox represents a HTML checkbox element. It has a checked property to indicate if the checkbox is checked or not.
The Form is the container for other HTML elements. It's used as a parent in the DOM for the elements it contains. See The Form Object.
The grid represents a tabular set of data to display. Jolene creates Grid objects whenever it sees a TABLE tag in a form with an ID attribute which starts with "grid". See The Grid Object.
The Header object is an element in the HEAD section of the HTML file. Usually these are scripts, styles and meta tags. For in-line styles and scripts you can access their content from the content property.
The Image object represents an image in the document. Note that Jolene only recognizes images inside form tags.
The Input object represents an input element in the document. Note that for checkbox and radio Jolene create CheckBox and Radio objects instead of Input objects.
The Label object represents a label element in the document. Labels are usually used for simple text. If a label in your document contains HTML then Jolene will create a Text object instead which allows you to send back any arbitrary text.
The Radio represents a HTML radio button element. It has a checked property to indicate if the radio is check or not. Additionally the value and name attributes are used to group radio buttons together. See the forms getRadioGroup and populate methods for examples.
The Select object represents a HTML select or dropdown element. See The Select Object.
The Text object represents arbitrary text that you would want to render in a document. Text objects are created wherever you have a label tag in your document which contains HTML. The Text object does not render any tags or other html attributes. It renders explicitly whatever you set the value property to be. Let's say for example that you want to insert some text containing some specific formatting - like an error message string.
In your document you could have:
<label id="errorText" style="display:none"><b>Error goes here!</b></label>
Because of the HTML tags inside the label when Jolene reads this document it will create a Text object called errorText. So now in code you could do this:
if (error) {
document.forms(0).elements("errorText").setValue("<b>An error has occurred</b>");
}
Which render this instead of the label tag:
<b>An error has occurred</b>
This technique could be used to send back custom scripts, object tags, images or other specialized data back to the user.
The TextArea represents a HTML textarea element. A textarea is basically a multi-line editor.
The body, form, header elements and form elements inherit from this class and have some common properties and methods.
The afterText property is used to set any any arbitrary text which will appear immediately after the element.
document.elements("MyButton").setAfterText("Whatever you do - don't click this!");
Which would output:
<button name="MyButton">Whatever you do - don't click this!
The beforeText property is used to set any any arbitrary text which will appear immediately before this element.
document.elements("MyInput").setBeforeText("Enter something here:");
Which would output:
Enter something here:<input name="MyInput" type="text">
The checked property sets or gets if an element is checked or not. Used for Radios and Checkboxes.
The content property sets or gets the content part of an element. The content is the portion of the element after the end of the start tag to the start of the end tag. Example:
<button name="MyButton">This is the content</button> <label id="MyLabel">Label content</label>
Note that not all elements have a content - Input, Select, Image, etc. For these elements content property is not rendered even if it was set. For other elements like Label and TextArea - the content and the value are the same thing - in these cases the 2 properties are interchangeable. The Button is a special case since it has both a value and a content. Example:
<button name="MyButton" value="this is the value">This is the content</button>
The disabled property sets or gets if an element is disabled or not.
This property gets or sets the name of the element. Note that this name is also set as an attribute for submitable form controls. For Image, Text and Label this has no effect on the rendering of the element.
The readonly property sets or gets if an element is readonly or not.
This property sets or gets whether or not this element will be rendered in in the document. By default it's true. If it's false then the element will be rendered as an empty string. This is used to hide elements in the document. -- NEEDS WORK.
This property gets the tag for this element. Supported tags are: input, button, form, table, img, label, select, textarea, tr, td, th, option, meta, script, link and style.
Sets or gets the value of the element. This is usually the value the element submits. In the case of a Label is it's text content.
Retrieves the specified attribute from the element. Attributes are the name/value pairs found inside the tags of an element. The method is case insensitive and can return null if the attribute is not found see hasAttribute. For example:
In your document:
<input type="text" name="hello">
In your code:
document.elements("hello").getAttribute("TYPE"); // returns 'text'
Retrieves a style value from the style attribute of the element. The method is case insensitive and can return null if the style is not found. See hasStyle. Example:
In your document:
<input type="text" name="hello" style="background:aliceblue;background-color:aquamarine;border-top-width:medium;font:xx-small;">
In your code:
document.elements("hello").getStyle("background-color"); // returns 'aquamarine'
Returns true if the specified attribute exists on the element. The method is case insensitive.
In your document:
<input type="text" name="hello" style="background:aliceblue;background-color:aquamarine;border-top-width:medium;font:xx-small;">
In your code:
document.elements("hello").hasAttribute("style"); // returns true
Returns true if the specified style exists on the element. The method is case insensitive.
In your document:
<input type="text" name="hello" style="background:aliceblue;background-color:aquamarine;border-top-width:medium;font:xx-small;">
In your code:
document.elements("hello").hasStyle("background"); // returns true
Returns the Set of attributes names on the element. Used if you want to iterate over the attributes.
Removes the specified attribute from the element. The method is case insensitive.
Removes the specified style in the elements style attribute. The method is case insensitive.
Sets the style on the element clearing the existing style. The style should look like a standard style string. Example:
In your document:
<input type="text" name="hello" style="background:aliceblue;">
In your code:
document.elements("hello").resetStyle("background:red;");
Which would output:
<input type="text" name="hello" style="background:red;">
Sets the style on the element clearing the existing style. This version takes a Style object as a parameter. Example:
In your document:
<input type="text" name="hello" style="background:aliceblue;">
In your code:
Style style = new Style();
styles.setStyle("background", "blue");
styles.setStyle("foreground", "red");
document.elements("hello").resetStyle(style);
Which would output:
<input type="text" name="hello" style="background:blue;foreground:red;">
Sets a style on the element preserving any existing styles. The method will only add or replace existing style attributes.
In your document:
<input type="text" name="hello" style="background:blue;foreground:red;">
In your code:
document.elements("hello").setStyle("foreground:pink;");
Which would output:
<input type="text" name="hello" style="background:blue;foreground:pink;">
Sets the style on the element based on a formatted style string preserving any existing styles. Example:
In your document:
<input type="text" name="hello" style="background:blue;foreground:red;">
In your code:
document.elements("hello").setStyles(forground:pink;");
Which would output:
<input type="text" name="hello" style="background:blue;foreground:pink;">
Sets the style on the element from a Style Object preserving any existing styles. Example:
In your document:
<input type="text" name="hello" style="background:blue;foreground:red;">
In your code:
Style style = new Style();
style.setStyle("forground","pink");
document.elements("hello").setStyles(style);
Which would output:
<input type="text" name="hello" style="background:blue;foreground:pink;">
Use this method to replace the element with any arbitrary String. Since any Jolene HTML object can be used outside the DOM, a common usage is to replace a element from the HTML file with another HTML element. Example:
In your document:
<input type="text" name="hello">
In your code:
Button button = new Button("hello");
button.setContent("hello world!");
document.elements("hello").swapWith(button);
Which would output:
<button name="hello">hello world!<button>
The body property allows you to modify the attributes of the body tag.
document.getBody().setAttribute("topmargin","2");
Which would output:
<body topmargin="2">
This property gets or sets the type of document. This is the string which would appear before the start of the html tag.
Example:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
String doctype = document.getDoctype();
This property gets the number of forms in the document. This can be used to iterate over all forms.
for (int j=0;j<document.getFormCount(); j++) {
document.forms(j).setAttribute("action","hello.do");
}
This property gets the the number of header elements in the document. This can be used to iterate over all headers.
for (int j=0;j<document.getHeaderCount(); j++) {
document.headers(j).setAttribute("description","hello");
}
The title property gets or sets the title of the document.
document.setTitle("My Title");
The uri property gets the document Uniform Resource Identifier (URI) of the document. In a web context the URI is the web version of the document file name. Jolene associates this URI to the filename to find and read the document. Example:
C:\apache-tomcat-5.5.12\webapps\kbsample\domlet\article.html
Your webapp is kbsample and your documents are stored under a domlet folder so the uri would be:
/domlet/article.html
Adds a Header object to the list of headers in the document.
Header header = new Header(Tags.meta);
header.setAttribute("name","author");
header.setAttribute("content","Dan Howard");
document.addHeader(header);
Which would output:
<meta name="author" content="Dan Howard"/>
Returns an element in the document by searching by case insensitive name through each form. It will return null if no element is found with that name. Note that for Jolene an element NAME and ID are interchangeable. When Jolene reads the document some elements may not have a name attribute and instead have an id attribute. For the Jolene DOM these are the same and are recognized as a name property.
Returns the Form object indexed by document order starting with zero.
document.forms(0).setAttribute("action","/hello.do");
Returns the Form object specified by name. For the form to be found it will require a 'name' attribute in the document.
document.forms("MyForm").setAttribute("action","/hello.do");
The headers method gets the Header object index by document order. The Header object is an element in the HEAD section of the HTML file. Usually these are scripts, styles and meta tags. Each of these elements can be
Removes the specified Header from the document using the numeric index to the header. The index is zero based by document order.
Writes the document to the specified file name.
document.forms("MyForm").setAttribute("action","/hello.do");
document.stream("c:/mydocs/myhtml.html");
Writes the document using the specified writer.
document.forms("MyForm").setAttribute("action","/hello.do");
StringWriter sw = new StringWriter();
document.stream(sw);
The Form object is an element object but it's also the parent for other HTML elements. Unlike basic elements the Form has additional functionality.
This property returns the number of elements contained in the form.
Returns an element based on the location in the document by read order starting at zero. Usually this method would be used when iterating over all form elements. Otherwise you should use the method which gets the element by name.
Returns an element by name. Note that this is the Jolene name and not necessarily the name attribute of a HTML element. Some elements do not use a name attribute (like labels) so in those cases the name of the object is read from the ID attribute.
This method returns the specified HTML element casted as a Grid object.
Returns the radio group specified by name. Radio buttons are a little special because you can have multiple radio buttons in form with the same name and each would have a different value. So if you simply used the elements method it would always return the first radio only. This method method will return a map of string values of the radio buttons keyed to the specific radio button element.
For example lets say you had the following in your HTML file:
<input name="security" type="radio" value="Public"> <input name="security" type="radio" value="Private" checked="checked"> <input name="security" type="radio" value="Specify">
Then in code you could do this:
Map<String, HTMLElement> radios = document.forms(0).getRadioGroup("security");
if (radios.get("Private").isChecked()) {
radios.get("Private").setChecked(false);
radios.get("Public").setChecked(true);
}
Which would output:
<input name="security" type="radio" value="Public" checked="checked"> <input name="security" type="radio" value="Private"> <input name="security" type="radio" value="Specify">
Note that in this context the keys are case sensitive.
This method returns the specified HTML element casted as a Select object.
Returns true if the specified element is found in this form. The search is case insensitive.
This method populates the form elements based on the specified Java bean. Any object which conforms the Java bean specification can be used. The method is intelligent and can populate any of the normal HTML elements - like radios, checkboxes, inputs, selects, etc. A common use-case is that you get an object from your database and you want to display this object as an editable Form to the user. The method matches the bean properties to the form element names.
The grid represents a tabular set of data to display. Jolene creates Grid objects whenever it sees a TABLE tag in a form with an ID attribute which starts with "grid". So for example a web designer could denote a data grid like this:
<table id="grid1"> <tr> <td>Data goes here.</td> </tr> </table>
And then in code you can bind this grid to a data object using GridColumn objects.
List data = getDataObjectsToDisplay();
GridColumn col;
List<GridColumn> header;
List<String> fields;
// We'll have 3 columns
header = new ArrayList<GridColumn>(3);
// Define each column in the grid
// The GridColumn header can takes a text to display and a default width.
col = new GridColumn("Customer", "40%");
// Add the column to the header
header.add(col);
col = new GridColumn("Address", "40%");
header.add(col);
col = new GridColumn("Account balance", "20%");
header.add(col);
// Field (property) names to use from the data list
// These match up to the data objects getters.
fields = new ArrayList<String>(3);
fields.add("customer"); // getCustomer from data object
fields.add("address"); // getAddress from data object
fields.add("balance"); // getBalance from data object
// Get the grid from the document.
Grid grid = document.forms(0).getGrid("grid1");
// Bind the grid to this data - passing in the header columns, the fields to display and the data itself.
grid.bind(header, fields, data);
TODO!!!!
This property indicates if the Select is a multi-select or not. A multi-select allows the user to ctrl-click on options and select multiple ones.
This method adds a new option to the available options for the select object and returns the new size of the Options list. Example:
In your document:
<select name="MySelect"> </select>
In your code:
Select select = document.forms(0).getSelect("MySelect");
select.addOption(new Option("1", "Mr"));
select.addOption(new Option("2", "Mrs"));
Which would output:
<select name="MySelect"> <option value="1">Mr</option> <option value="2">Mrs</option> </select>
This method clears the list of options on the select.
Returns the specified option object by the numeric index. Example:
In your document:
<select name="MySelect"> <option value="1">Mr</option> <option value="2">Mrs</option> </select>
In your code:
Select select = document.forms(0).getSelect("MySelect");
Option o = select.options(1); // returns Option object for "Mrs"
This method sorts the options. Example:
In your document:
<select name="MySelect"> <option value="1">ZZZ</option> <option value="2">JJJ</option> <option value="3">AAA</option> </select>
In your code:
document.forms(0).getSelect("MySelect").sortOptions();
Which would output:
<select name="MySelect"> <option value="3">AAA</option> <option value="2">JJJ</option> <option value="1">ZZZ</option> </select>