Contents:

• Attributes common to all object classes

• Object classes compatible with ASCII DLG
  • Dialog
  • GroupBox
  • StaticText
  • PushButton
  • CheckBox
  • RadioButton
  • EditText
  • ListBox
  • HelpText
  • POPUP BOX

• New object classes
  • System
  • Application
  • Image

• Using HTML in StaticText and Button objects

Attributes common to all object classes

Dialog

Name	Type	Default	GET	SET	Description
x	INT	0	X	X	Ignored but implemented for compatibility reasons (please refer to the document How compatible is Eloquence WEBDLG? for details)
y	INT	0	X	X	Ignored but implemented for compatibility reasons (please refer to the document How compatible is Eloquence WEBDLG? for details)
title	STRING	empty	X	X	Dialog title (a special token is provided to embed the title into customized page header and/or page trailer template files)
border	INT	3	X	X	If nonzero: border width in pixels (has no effect with Netscape 4.x browsers).
bgimage	STRING	empty	X	X	Location of a background image file, typically on a web server. If a relative URL is given the .baseurl attribute of the application object is prepended. Please note that with Netscape this disables any background colors (even with Netscape 6.2).
cr	INT	0	X	X	Ignored but implemented for compatibility reasons
f1...f10	INT	0	X	X	Ignored but implemented for compatibility reasons
alt	INT	0	X	X	Ignored but implemented for compatibility reasons

Groupbox

Name	Type	Default	GET	SET	Description
title	STRING	empty	X	X	Currently ignored but implemented
border	INT	1	X	X	If nonzero: border width in pixels (has no effect with Netscape 4.x browsers).

StaticText

Name	Type	Default	GET	SET	Description
w	INT	*	X	X	Object width (default value depends on text length)
h	INT	1	X	X	Object height
text	STRING	empty	X	X	The text to be displayed (HTML is supported)

PushButton

Name	Type	Default	GET	SET	Description
w	INT	*	X	X	Object width (default value depends on length of button's text)
h	INT	1	X	X	Object height
rule	INT	0	X	X	If nonzero: rule value to be triggered when the button is clicked.
text	STRING	empty	X	X	The button's text (HTML is supported)
border	INT	1	X	X	Currently ignored but implemented (a pushbutton always has a border)
adjust	INT	0	X	X	Ignored but implemented for compatibility reasons
ruleoverride	INT	1	X	X	Whether the rule of an edittext which currently has the focus will be overridden.

CheckBox

Name	Type	Default	GET	SET	Description
w	INT	*	X	X	Object width (default value depends on length of label text)
h	INT	1	X	X	Object height
rule	INT	0	X	X	If nonzero: rule value to be triggered when the state of the checkbox is changed.
text	STRING	empty	X	X	The label text of the checkbox (HTML is supported)
active	INT	0	X	X	Whether the checkbox is active or to be activated
ruleoverride	INT	1	X	X	Whether the rule of an edittext which currently has the focus will be overridden.

RadioButton

Name	Type	Default	GET	SET	Description
w	INT	*	X	X	Object width (default value depends on length of label text)
h	INT	1	X	X	Object height
rule	INT	0	X	X	If nonzero: rule value to be triggered when the state of the radiobutton is changed.
text	STRING	empty	X	X	The label text of the radiobutton (HTML is supported)
activebtn	STRING	empty	X	-	Path of active radiobutton in this group
active	INT	0	X	X	Whether the radiobutton is active or to be activated
ruleoverride	INT	1	X	X	Whether the rule of an edittext which currently has the focus will be overridden.

EditText

Please note that although a cursor position is maintained, this is only used internally (eg. to specify the position where new contents are to be inserted). The browser however does not mention this cursor position at all.

Name	Type	Default	GET	SET	Description
rule	INT	0	X	X	If nonzero: rule value to be triggered when the contents have changed and the focus moves out of the edittext.
length	INT		X	-	Current length of content
content	STRING	empty	X	X	Current content
editable	INT	1	X	X	Whether edittext is editable or read-only
multiline	INT	0	X	X	Whether edittext is single- or multi-line
border	INT	1	X	X	Currently ignored but implemented (an edittext always has a border)
title	STRING	empty	X	X	Ignored but implemented for compatibility reasons
hsb	INT	1	X	X	Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
vsb	INT	1	X	X	Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
maxchars	INT	0	X	X	Maximum characters accepted for input (0=unlimited)
maxlines	INT	0	X	X	Ignored but implemented for compatibility reasons
ispassword	INT	0	X	X	Whether contents are visible or displayed as '*' asterisk characters
vheight	INT		X	-	Current number of lines
vwidth	INT		X	-	Current number of columns
cx	INT	0	X	X	Cursor column (starting with 0)
cy	INT	0	X	X	Cursor line (starting with 0)
topitem	INT	0	X	X	Topmost line (starting with 0)
clear			-	X	Clears the entire edittext
add	STRING		-	X	Adds new contents to the end
line	STRING		X	X	A specific line's contents
home			-	X	Moves the internal position to the beginning
end			-	X	Moves the internal position to the end
bol			-	X	Moves the internal position to the beginning of the current line
eol			-	X	Moves the internal position to the end of the current line
up	INT		-	X	Moves the internal position up for the specified number of lines
down	INT		-	X	Moves the internal position down for the specified number of lines
left	INT		-	X	Moves the internal position left for the specified number of columns
right	INT		-	X	Moves the internal position right for the specified number of columns
npage	INT		-	X	Moves the internal position down for the specified number of pages
ppage	INT		-	X	Moves the internal position up for the specified number of pages
ins	STRING		-	X	Inserts new contents at the current position
delch	INT		-	X	Deletes the specified number of characters from the current position
delln	INT		-	X	Deletes the specified number of lines from the current position
deleol			-	X	Deletes from the current position up to the end of the current line
deleot			-	X	Deletes from the current position up to the end
file	STRING		-	X	Name of a file from which the contents shall be read (the encoding of external files can be configured with the ExtCharset directive)
insertfile	STRING		-	X	Name of a file from which the contents shall be inserted at the current position
writefile	STRING		-	X	Name of a file to which the contents shall be written

ListBox

Please note that although a cursor position is maintained, this is only used internally (eg. to specify the position where new contents are to be inserted). The browser however does not mention this cursor position at all.

Name	Type	Default	GET	SET	Description
rule	INT	0	X	X	If nonzero: rule value to be triggered when the selected line changes.
length	INT		X	-	Current length of content
content	STRING	empty	X	X	Current content
multiline	INT	0	X	X	Whether edittext is single- or multi-line
border	INT	1	X	X	Currently ignored but implemented (a listbox always has a border)
title	STRING	empty	X	X	Ignored but implemented for compatibility reasons
hsb	INT	1	X	X	Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
vsb	INT	1	X	X	Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
vheight	INT		X	-	Current number of lines
vwidth	INT		X	-	Current number of columns
cx	INT	0	X	X	Cursor column (starting with 0)
cy	INT	0	X	X	Cursor line (starting with 0)
topitem	INT	0	X	X	Topmost line (starting with 0)
activeline	INT	0	X	X	Current active line (starting with 1, 0 = no active line)
clear			-	X	Clears the entire edittext
add	STRING		-	X	Adds new contents to the end
line	STRING		X	X	A specific line's contents
home			-	X	Moves the internal position to the beginning
end			-	X	Moves the internal position to the end
bol			-	X	Moves the internal position to the beginning of the current line
eol			-	X	Moves the internal position to the end of the current line
up	INT		-	X	Moves the internal position up for the specified number of lines
down	INT		-	X	Moves the internal position down for the specified number of lines
left	INT		-	X	Moves the internal position left for the specified number of columns
right	INT		-	X	Moves the internal position right for the specified number of columns
npage	INT		-	X	Moves the internal position down for the specified number of pages
ppage	INT		-	X	Moves the internal position up for the specified number of pages
ins	STRING		-	X	Inserts new contents at the current position
delch	INT		-	X	Deletes the specified number of characters from the current position
delln	INT		-	X	Deletes the specified number of lines from the current position
deleol			-	X	Deletes from the current position up to the end of the current line
deleot			-	X	Deletes from the current position up to the end
file	STRING		-	X	Name of a file from which the contents shall be read (the encoding of external files can be configured with the ExtCharset directive)
writefile	STRING		-	X	Name of a file to which the contents shall be written

HelpText

POPUP BOX

Syntax:

    POPUP BOX X,Y,"[Title][Line 1|Line 2|Line 3][Button 1|Button 2]",Rc

Please note:

• With WEBDLG, the X/Y coordinates are ignored.

• On entry, WEBDLG ignores the value of Rc. With ASCII DLG, it would define the default button which can be submitted with the ENTER key, but with WEBDLG this is currently not implemented.

• On exit, the value of Rc reflects which button was submitted (starting with 1).

• CSS style sheets can be used to customize the appearance. Please refer to the document How compatible is Eloquence WEBDLG? for details.

• HTML can be used in text lines and buttons to further customize the POPUP BOX layout. Please note that in the title HTML is not supported.

System

Name	Type	Default	GET	SET	Description
driver	STRING	*	X	-	WEB for WEBDLG, JDLG for Java DLG (will be implemented for ASCII DLG as well)
version	STRING	*	X	-	The driver's version code
baseurl	STRING	empty	X	-	Any given relative URL (eg. referring to image files) is prepended with this value. An URL is considered relative if it does not start with http:// (globally-absolute) or / (server-absolute).
helpbaseurl	STRING	empty	X	-	Currently unused since the help system is not functional yet
remoteaddr	STRING	*	X	-	The IP address of the remote PC where the user's browser runs
remotename	STRING	*	X	-	The host name of the remote PC where the user's browser runs (equivalent to 'remoteaddr' if the host name is unkown, e.g. if the Apache web server is not configured to do DNS lookups)
remoteport	STRING	*	X	-	The port number the remote PC's browser uses for this request

Example:

  ! Query the System.driver
     DLG GET "System.driver",Driver$

Application

Name	Type	Default	GET	SET	Description
baseurl	STRING	empty	X	X	Any given relative URL (eg. referring to image files) is prepended with this value. An URL is considered relative if it does not start with http:// (globally-absolute) or / (server-absolute).
helpbaseurl	STRING	empty	X	X	Currently unused since the help system is not functional yet

Example:

  ! Set the Application.baseURL
     DLG SET "Application.baseURL","http://www.your-host.com/your-app/"

  ! Now load the first dialog
     DLG LOAD "dialog.dlg,YOURVOL"

Image

Name	Type	Default	GET	SET	Description
w	INT	0	X	X	Width in character cells of the rectangular area where the image is to be placed. If the image's width extends this width the area is enlarged accordingly by the browser.
h	INT	0	X	X	Height in character cells of the rectangular area where the image is to be placed. If the image's height extends this height the area is enlarged accordingly by the browser.
url	STRING	empty	X	X	Location of the image file, typically on a web server. If a relative URL is given the .baseurl attribute of the application object is prepended.
rule	INT	0	X	X	If nonzero: rule value to be triggered when the image is clicked.
ruleoverride	INT	1	X	X	Whether the rule of an edittext which currently has the focus will be overridden.
border	INT	0	X	X	If nonzero: border width in pixels (has no effect with Netscape 4.x browsers).
sw	INT	0	X	X	Horizontal alignment:  0: The image is horizontally centered  <0: The image is horizontally scaled to .w (in character cells)  >0: The image is horizontally scaled to .sw (in pixels)
sh	INT	0	X	X	Vertical alignment:  0: The image is vertically centered  <0: The image is vertically scaled to .h (in character cells)  >0: The image is vertically scaled to .sh (in pixels)
area	STRING	empty	X	X	Image area (see below).

Using image areas

An image area is defined with the following syntax:

  RULE:SHAPE:COORDINATES[:DESCRIPTION]

RULE

An integer value specifying the rule to be returned when the area is clicked

SHAPE

Defines the shape of the clickable area:

• RECT - a rectangular area
• CIRCLE - a circular area
• POLY - a polygonal area

COORDINATES

A comma-separated list of integer values defining the coordinates of the clickable area. All coordinates are in pixel units:

• For a RECT area, exactly 4 coordinates must be specified:
  • x coordinate of upper left corner
  • y coordinate of upper left corner
  • x coordinate of lower right corner
  • y coordinate of lower right corner
• For a CIRCLE area, exactly 3 coordinates must be specified:
  • x coordinate of center point
  • y coordinate of center point
  • radius
• For a POLY area, an even number of coordinates must be specified, defining the polygon points (x,y). The last polygon point is automatically connected to the first. At least 3 polygon points (6 coordinates) must be specified.

DESCRIPTION

An optional text which causes some browsers to display a tooltip when the mouse cursor touches the clickable area

The following example first clears any existing area and then defines a rectangle, a circle and a polygon:

  ! Clear any existing area
     DLG SET "My_Dialog.My_image.area",""
  ! Define a rectangular area with rule value 101
     DLG SET "My_Dialog.My_image.area[1]","101:rect:25,25,75,75:A Rectangle"
  ! Define a circular area with rule value 102
     DLG SET "My_Dialog.My_image.area[2]","102:circle:125,50,25:A Circle"
  ! Define a triangular area using a polygon with rule value 103
     DLG SET "My_Dialog.My_image.area[3]","103:poly:200,25,175,75,225,75:A Triangle"

Please note:

• To define an area, an index must be specified, starting with 1:
  "My_Dialog.My_image.area[1]"

  The index must be specified in increments of 1 (1, 2, 3, ...), otherwise a DLG error 660 will be returned.

  If the index is omitted, the next index (highest index plus 1) is used, for example:
  DLG SET "My_Dialog.My_image.area","101:rect:25,25,75,75:A Rectangle"
  DLG SET "My_Dialog.My_image.area","102:circle:125,50,25:A Circle"
  DLG SET "My_Dialog.My_image.area","103:poly:200,25,175,75,225,75:A Triangle"
  

• If the image itself has a rule, it is considered the "default rule" which is returned when you click the image but not into one of the areas.

• The descriptions ('A Rectangle', 'A Circle', 'A Triangle' in the example) are optional and can be omitted, such as:
  DLG SET "My_Dialog.My_image.area[1]","101:rect:25,25,75,75"

  Please note that not all browsers use them to display a tooltip so they may be nonfunctional with some browsers.

• To clear (undefine) an existing area, set it to an empty string, such as:
  DLG SET "My_Dialog.My_image.area[1]",""

• To clear (undefine) all existing areas, omit the index, such as:
  DLG SET "My_Dialog.My_image.area",""

Image areas can be defined in the DLG file as well. Of course, in this case it does not make sense to previously clear the existing areas. Example:

  Image img
  {
    # Default rule
    .rule = 100
    # rectangular area with rule value 101
    .area[1] = "101:rect:25,25,75,75:A Rectangle"
    # circular area with rule value 102
    .area[2] = "102:circle:125,50,25:A Circle"
    # triangular area using a polygon with rule value 103
    .area[3] = "103:poly:200,25,175,75,225,75:A Triangle"
  }

Furthermore, the image areas can be read from a file. Please note that the file must be accessible by WEBDLG (i.e., you cannot specify an URL of a remote file).

The file should contain the area definitions in the same format as described above. Example:

  # rectangular area with rule value 101
  101:rect:25,25,75,75:A Rectangle
  # circular area with rule value 102
  102:circle:125,50,25:A Circle
  # triangular area using a polygon with rule value 103
  103:poly:200,25,175,75,225,75:A Triangle

The file can then be referenced with the .area attribute as follows:

  Image img
  {
    # Default rule
    .rule = 100
    # read area definitions from external file
    .area = "file:/path/to/area.file"
  }

Please note: The file must be specified using the absolute path and must be prefixed with "file:".

Using HTML in StaticText and Button objects

Example:

  ! Highlight the current item in a statictext with red color
  !
     Text$="<html>The current item is: <font color='red'>"&Item$&"</font></html>"
     DLG SET "My_Dialog.My_statictext.text",Text$

Because a POPUP BOX internally uses StaticText and PushButton objects, HTML is especially useful to further customize a POPUP BOX layout:

  ! <em>...</em> is used to show text in italic (emphasized)
  ! YES button is green, NO button is red
  !
     Buf$="[Confirmation]"
     Buf$=Buf$&"[<html>Do you <em>really</em> want to quit?</html>"
     Buf$=Buf$&"|<html>Any <em>unsaved</em> changes will be lost!</html>]"
     Buf$=Buf$&"[<html><font color='green'>Yes</font></html>"
     Buf$=Buf$&"|<html><font color='red'>No</font></html>]"
     POPUP BOX Buf$,Rc

Please note:

• While using HTML offers a lot of flexibility, wrong HTML code can easily destroy a dialog's functionality.

• The following characters have a special meaning in HTML and must be replaced with their so called "character entity references":
  • & - replace with &
  • " - replace with "
  • < - replace with &lt;
  • > - replace with &gt;

• Take care of correctly balancing your HTML tags. For example, the following is correct HTML:
  <font color='green'><strong>some text</strong></font>
  Example of wrong HTML code (tags not correctly balanced):
  <font color='green'><strong>some text</font></strong>
  Another example of wrong HTML code (missing closing font tag):
  <font color='green'><strong>some text</strong>
  

• Take care of correctly quoting any tag attribute. If you forget a closing quote, the dialog will probably not function correctly on some browsers. In particular, the Internet Explorer seems to tolerate most quoting errors, so if you forget a closing quote and then test your dialogs with the Internet Explorer, they may seem to be correct but won't work in other browsers such as Mozilla Firefox.
  This is an example of wrong HTML quoting (missing closing quote):
  <font color='green>

• You can use single or double quotes. If you specify HTML text in a DLG file you must use single quotes because a double quote inside a string is not correctly recognized by the Eloquence DLG file parser (i.e., the string will be undesirably terminated).
  If you, however, specify HTML text with DLG SET you are free to use double quotes (CHR$(34)).

With HTML in a StaticText object, you can embed external hyperlinks into your dialogs. Example:

  ! Embed a hyperlink to our home page
  !
     Text$="<html><a href='http://www.our.homepage...' target='_blank'>Home</a></html>"
     DLG SET "My_Dialog.My_statictext.text",Text$

Please note the target='_blank' attribute which specifies that a new browser window should be opened to display the hyperlink target. This is important because if you don't specify to open a new browser window, the hyperlink target will be displayed in the current browser window where your WEBDLG program is running, kind of "interrupting" your program: There is no obvious way to return to your program so the less experienced user will probably end up with an idle WEBDLG session which will eventually expire silently.

A more sophisticated way to display external hyperlinks is to use JavaScript to open new browser windows with specific properties.

For example, put the following JavaScript code section into your page header:

  <script language="JavaScript">
  <!--
   function openWin(width, height, url)
   {
    window.open(url, 'win_' + width + '_' + height,
     'width=' + width + ',height=' + height
     + ',resizable=yes,scrollbars=yes');
   }
  //-->
  </script>

Having this function defined, you can conveniently display external links in new browser windows. The width and height parameters specify the size of the new window which will be resizable and show scrollbars when needed.

Example:

  ! Embed a hyperlink to our home page using javascript:openWin()
  ! <a href="javascript:openWin(500,350,'http://www.our.homepage...')">Home</a>
  !
     Text$="<html><a href="&CHR$(34)
     Text$=Text$&"javascript:openWin(500,350,'http://www.our.homepage...')"
     Text$=Text$&CHR$(34)&">Home</a></html>"
     DLG SET "My_Dialog.My_statictext.text",Text$

In the example above, the size of the window is 500x350 pixels. Note that our openWin() JavaScript function will compose the window's name from this size (2nd parameter of the window.open() function: 'win_' + width + '_' + height will result in "win_500_350") so that for each size there will be only one window present (i.e., windows of the same size will be reused).

Also note that when using JavaScript in hyperlinks, you have to use both double and single quotes, as shown in the example above. Therefore, you cannot define such hyperlinks in a DLG file: As explained above, double quotes inside a string do not work in DLG files.

To learn more about the JavaScript window.open() function please refer to the Mozilla Gecko DOM reference documentation. An informative introduction to hyperlinks can be found here.