AppFormXml

From UGP-Wiki

Documentation on appForm file: app_form.xml

[edit] Purpose of app_form.xml

• app_form.xml is one the three required files for any appForm application
• app_form.xml defines the form elements that appear in the Input Generator tab. More specifically, the form elements that define the parameters to be included in the program input file.

• NOTE: Replace app in the file name with the name of the application as it appears in the UGP Application table.

[edit] Overall Syntax

The app_form.xml file should look like this:

  <?xml version="1.0" ?>
  <app name="application">
     xml element
     xml element
     xml element
     ...
  </app>

• The form is created using two kinds of elements: Widgets and Compound elements.
• Each Widget is used to solicit user input for a single item that is to appear in the application input file.
• Compound elements organize the widgets into groups and allow the Grid Admin to create a cleaner and more complex page to display to the user.
• All xml elements (widgets and compound) must appear inside of the <app> </app> tags. Do not replace <app> with the name of the application but code <app> exactly as it appears here.

[edit] <about>

Each element (group, repeatgroup, string, textarea, number, pulldownmenu, image, checkbox) can have an optional <about> section which can have the following tags inside of it. All of the tags inside <about> are optional. If there are none, <about> should be omitted.

  <about>
     <label>Label</label>
     <description>description</description>
     <image [url="url"]>image</image>
     <url>url</url>
     <enable element="element" value="value" test="test"/>
     ...
     additional options
  <about>

<label>

Is the label for that particular element.

<description>

Is a long description that can be shown to the user.

<image>

Is like an href for the image to be shown in conjunction with this element.

<url>

Is a url that can appear next to this widget to give the user documentation about to how to fill it in or what the choices mean.

<enable>

Controls the display of the element. The element will only be displayed when the condition is true. This is dynamic (i.e. when an element is changed, it automatically updates all elements enabled by it)

additional options

Some elements have unique options in their <about> sections, these are listed in each element's respective section below.

[edit] <enable> conditions

If the tool to test is a boolean, the condition takes the form:

<enable element="element" value="value" test="test" />

Where:

element

Is the name of a widget, whose value on which the appearance of this widget depends

value

Is the value to match.

• If test is ==, value can be of the form: value1|value2|...|valuen. The test will be satisfied if any of the values specied match.

• When testing against a <pulldownmenu>:

  <value>WHATEVER</value>

  use WHATEVER in the <enable>.

  <value code="5">WHATEVER</value>

  use 5 in the <enable>.

• When testing against a <checkbox>:

  A checked checkbox has the value "true"

  An unchecked checkbox has the value "false"

test

Defaults to == and can optionally be <=, <, >=, or > if value is numeric.

[edit] Compound Elements

There are 3 compound elements:

• page
• group
• repeatgroup

Pages and groups are used to visually differentiate similar elements. Groups combine elements into a separate HTML "box" within a page, whereas a page displays its elements in a separate tab.

Pages are useful for:

• Defining separate categories of input widgets and placing them together on a separate tab. This allows the user to easily navigate through a large amount of options

Groups are useful for:

• Combining similar widgets into a labeled group within a page. This makes the page easier to navigate and use.
• Defining how widgets are displayed in relation to each other by using the "horizontal" and "vertical" attributes
• Using the <enable> for a group to easily control the display of a group of widgets based on the value of another element.

NOTE: Pages and Groups are completely optional. If they are not used, a single page is created that contains a list of whatever widgets you define.

[edit] <page>

appForm automatically defines the first page ("Main Page"). Any elements not within a <page></page> element will be displayed in the "Main Page" tab.

Additional pages are displayed as tabs next to "Main Page". To create additional pages, code a <page></page> element:

  <page id="page_id">
       <about>
         <label_format>1|2</label_format>
       </about>
         xml element (widget or compound)
         xml element (widget or compound)
         ...
  </page>

page_id

the text that will be displayed in the YUI tab as the title of the page

<label_format>

used to control formatting of widget labels on this page using an integer in this element. The currently implemented integers are:

• 1: ([id])[label] Widget's id is displayed in parentheses before label
• 2: [id] Only the widget's id is displayed as the label. Widget must still have label tag (an empty label tag, any contents inside this tag will be ignored) to cause this label type to be displayed.

<label_format> tags can also be used in group <about>'s, these will override <label_format> tags in page elements. This is useful for defining local formatting in a group while not affecting the global formatting in a page. For example, adding an empty <label_format/> tag to a group will override a page <label_format> and make the formatting in that group the default.

[edit] <group>

Groups are used to group and format elements within a page. Groups can contain both widgets and other groups, but NOT pages.

The format for a group element is:

  <group id="group_id" [layout="horizontal|vertical"]>
      <about>
       standard <about> options
       ...
       <label_format>[integer]</label_format>
      </about>
      xml element 1(widget or group/repeat group)
      xml element 2(widget or group/repeat group)
      ...
      xml element n(widget or group/repeat group)
  </group>

     <group id="group_id" [layout="horizontal|vertical"]>
         <group id="group_id" [layout="horizontal|vertical"]>
             widget
             ...
         </group>
         ...
     </group>

but currently the nesting of groups more than two levels deep is NOT supported.

Error with Horizontal Groups and <enable>

Additionally, for elements that:

• are inside a horizontal group
• use an <enable>

you must NOT use labels or descriptions. If you do, the alignment of the group will not display properly

[edit] <repeatgroup>

A Group of elemtents that can be "repeated". A button is included in a repeatgroup that allows the user to create an exact copy of the content inside <repeat></repeat>. The new, "repeated" content is displayed directly below the original content. The content inside <repeat></repeat> can only include widgets.

The format for a <repeatgroup> is:

  <repeatgroup id="group_id">
      <about>
         ...
      </about>
      outerwidget 1
      outerwidget 2
      ...
      outerwidget n
      <repeat id="repeat_id" [layout="horizontal|vertical"]>
         <about>
           ...
         </about>
         innerwidget 1
         innerwidget 2
         ...
         innerwidget n
      </repeat>
  </repeatgroup>

<about>

both the <repeatgroup> and <repeat> <about> can use standard group <about> options

outerwidget

a widget in the repeatgroup that will NOT be repeated

innerwidget

a widget in the repeatgroup that WILL be repeated

<enable>s in <about>s inside of a <repeatgroup> have to be treated specially:

• The <enable> in the <about> belonging to the <repeatgroup> can refer to an element outside the repeat group. i.e., the entire repeat group can be shown or hidden depending on the value of something outside.

• <enable>s belonging to outerwidgets can refer only to other outerwidgets.

• <enable>s belonging to the innerwidgets inside of <repeat> can only refer to other widgets inside the <repeat>.

[edit] Widget Elements

There are 6 widget elements:

• string
• textarea
• number
• pulldownmenu
• image
• checkbox

Widgets are the form elements that are used for the user-input that will be converted to program input file options. Each widget element has its own benefits/drawbacks and together provide a diverse way to facilitate user-input.

[edit] Syntax of Widgets

The format of widget tags is:

     <widget_type id="id">
        <about>
           ...
        </about>
        <other_tags_this_widget>
     </widget_type>

Where:

<widget_type>

Is the type of widget selected from the widgets documented here.

id="id"

Each widget in an xml file MUST have a unique id. This id should be carefully chosen as it is used as the element name when processing in app_form_input.xsl. Normally, a widget's id should be the EXACT name of the corresponding option in the program input file. This will allow app_form_input.xsl to simply write the widget's id and value to the program input file without any additional formatting.

<about>

Is the optional <about> section. See <about> section above for documentation.

other tags

Other addtional tags are defined for specific widgets.

[edit] Widgets

[edit] <pulldownmenu>

Drop down menu with multiple choices.

    <pulldownmenu id="tool_id" [display="value"]>
      <about>
        ...
      </about>
      <title>title1</title>
      <title>title2</title>
      ...
      <value [display="value"] [code="code"] [title=”title1”]>value1</value>
      <value [code="code"] [title="title2"]>value2</value>
      ...
    </pulldownmenu>

• The user will see a pulldown menu with the following entries: value1, value2, ...
  • Code the code= attribute if the program needs to be passed a value that is different from the string that the user is to see for this menu item.
  • Code code="default" for a default value. This will cause this value to be selected in the pulldownmenu, regardless of the order of the values. Using a default code also allows easy filtering of default values in form_input.xsl.
  • The value options will appear in the pulldown menu in the same order they are coded. The first option will be selected, unless a [code="default"] is used for a value
• The menu items in the pulldown menu can be grouped under headings using the <title> option. This is useful if there is a long list of menu items or if the menu items logically fall under different categories. The <title> elements specify what category headings can appear in the pulldown menu. In order for a menu item in the pull down menu to appear under a category heading, code the title= attribute and specify the appropritate title from one of the <title> elements.
• Display Formatting Options
  • By default, each value will be displayed as: (code)value1
  • If there is no @code, then only the value will be displayed
  • This was done to show the user both the actual value (@code: for more advanced users) and a simpler value (value1, value2, etc: for novice users)
  • To display only the value, even if @code is provided, use @display="value"
  • Using @display in <pulldownmenu> will cause all values for this pulldownmenu to be displayed without @code
  • Using @display in a single <value> will cause only that value to be displayed without @code
  • NOTE: when using @display="value", value is not a variable. You should actually hardcode "display="value""

[edit] <image>

An image:

  <image>
     <about>
        ...
     </about>
     <fn>filename for the image</fn>
  </image>

[edit] <number>

A number

  <number id="tool_id" [required="true"|requiredIfVisible="enabledId"]>
     <about>
       ...
     </about>
     <min>min_value</min>
     <max>max_value</max>
     <not>illegal_value</not>
     <default>default_value</default>
     <cols>n</cols>
     <preset value="value">label for this preset</preset>
     ...
  </number>

• <min>, <max>, <not>, <default>, and <presets> are optional.
• <cols> defines the size of the input field
• <preset>s represent values for known quantities. Presets appear in a dropdown menu next to the type in box for the value. The user can either select a preset or type in any integer value in the number field. If a preset is chosen, the number field is automatically updated to reflect the choice. The value attribute must be included in the preset element for linking to work correctly.

• Code required="true" if the user MUST fill this in.

• Code requiredIfVisible is the user MUST fill this in only if the enabled group or widget whose Id is enabledId is visible.

[edit] <string>

A single line text input box.

  <string id="tool_id" [required="true"|requiredIfVisible="enabledId"]>
     <about>
     ..
     </about>
     <cols>n</cols>
     <default>default value</default>
       <preset value="value">label for this preset</preset>
     ...
  </string>

• <cols> defines the size of the input field
• Code required="true" if the user MUST fill this in.
• Code requiredIfVisible is the user MUST fill this in only if the enabled group or widget whose Id is enabledId is visible.

• <preset>s represent values for known quantities. Presets appear in a dropdown menu next to the type in box for the string. The user can either select a preset or type in any value in the string field. If a preset is chosen, the string field is automatically updated with the preset's "value" to reflect the choice. The value attribute must be included in the preset element for linking to work correctly.

[edit] <textarea>

A multi-line text input box.

  <textarea id="tool_id" [required="true"|requiredIfVisible="enabledId"]>
     <about>
     ..
     </about>
     <cols>n</cols>
     <rows>n</rows>
     <default>default</default>
  </textarea>

• <cols> and <rows> define the size of the input field
• Code required="true" if the user MUST fill this in.
• Code requiredIfVisible is the user MUST fill this in only if the enabled group or widget whose Id is enabledId is visible.

[edit] <checkbox>

A checkbox than can be used both for user-input and enabling large groups of options (i.e. "Display the following options?" next to a checkbox)

  <checkbox id="tool_id">
     <about>
     ..
     </about>
     [<value>value</value>]
     [<checked/>]
  </checkbox>

Checkboxes are useful for formatting a <page>. You can group large numbers of widgets togther and hide or show them depending on whether or not a checkbox is checked.

• Note that the required= and requiredIfVisible= options CANNOT be specified for a <checkbox>.

• Code <checked/> if you want the checkbox to initally be checked, otherwise omit.

• Code the <value> element to specify the value to be sent to the form when the checkbox is checked. When the values/selections that a user enters into the form are saved to a file, the checkbox value is saved only if it is checked. If value is not specified when the checkbox is checked, “on” will be saved as its value.

[edit] <fileselector>

A file selector dialog box. Useful for defining filenames for program input.

  <fileselector id="tool_id" [required="true"|requiredIfVisible="enabledId"]>
     <about>
     ..
     </about>
  </fileselector>

• Code required="true" if the user MUST fill this in.
• Code requiredIfVisible is the user MUST fill this in only if the enabled group or widget whose Id is enabledId is visible.

[edit] <plot>

  <plot id="tool_id" type="fcn">
     <about>
        ...
     </about>
     <fcn>y_as_a_function_of_x</fcn>
     <min>mininum_x</min>
     <max>maximum_x</max>
     <constant id="const1"/>
     <constant id="const2"/>
  </plot>

For Example:

  <plot id="tool_id" type="fcn">
     <about>
        ...
     </about>
     <fcn>Math.exp((x-vx0)**2/(2*vtx**2))</fcn>
     <min>4*vtx</min>
     <max>vx0+(4*vtx)</max>
     <constant id="vtx"/>
     <constant id="vx0"/>
  </plot>

Only type=fcn plots are currently supported. These are 2D X/Y plots.

• Specify y as a function of x. x must appear in the functions specification. The function specification must be good JavaScript code and use Math.sqrt( ), Math.exp( ), etc. when a mathematical function is required.

• Numbers that the user supplies by filling in or selection from widgets in the form, may be used as constants in the function. In this example, "vx0" and "vtx" are constants in the function and refer to the ids of other widgets within the form. They must be defined with a <constant> tag. The ids are case-sensitive. appForm obtains the values of each constant automatically. The values used in plot are dynamic (i.e. when the values of vx0 or vtx are changed by the user, the plot will be automatically updated to reflect the change).

• Currently, plots only graph 10 points. Functions such as sine or exp may appear incorrectly, however it is only due to appForm

[edit] <howtorun>

Place a <howtorun> tag somewhere in the document. At the end before </app> is a fine place to have it.

When the user clicks on the Save button, appForm updates the Job Parameters tab to specify the name of the application input file. <howtorun> specifies how appForm is to add information to the Job Parameters tab.

Additionally, howtorun also includes the necessary file extension for your application (e.g. GAMESS requires an input file with a .inp extension). Appform will read the <extension> value and use it accordingly. If the <extension> element is not included in <howtorun>, then appForm will use the default extension of .txt

   <howtorun>
      <arguments placement=["front"|"back"]>
         <filename tag="" placement="2"/>
         <directory tag="" placement="1"/>
      </arguments>
      
      [<extension value=".extension"/>]  (e.g. <extension value=".inp"/>)
   </howtorun>

   - If the input filename is to be passed to the application as stdin, for example:

        application < input_filename

     code <howtorun> as follows:

       <howtorun>
          <arguments placement=["front"|"back"]>
          </arguments>
       </howtorun>

       - Code placement="front" if the input filename must appear in front of any other file 
         names that the user has coded for stdin on the Job Parameters tag. 
       - Code placement="back" if the input filename is to appear last.

   - If the input file is to appear on the argument list for the program, with or without 
     a proceeding flag, for example:
 
        application input_filename

     or

        application -in input_filename

     add the filename element.  Specify tag=, if there is a flag.  For example, for the example 
     just above you would code:
  
        <filename tag="-in" placement="1">

     Some programs require that the directory path be specified separately from the filename.  
     In that case, also code the <directory> element.  The placement attribute determines the order. 
     The placement="1" argument will appear before the placement="2" argument in the argument list.

[edit] Additional Options

[edit] xml Elements for Formatting the Page Headers and Footers

In addition to the widget elements the following optional elements are for the formatting the top and bottom of the pages. All of the tags inside of these optional sections are optional.

  <heading>
     <title [url="url"]>Centered title of the page</title>
     <text>Lengthy text description to appear under the title</text>
     <image [url="url"]>image</image>
     <prompt [url="url"]>Such as: Fill in Form Below</prompt>
  </heading>

  <footer>
     <text [url="url"]>footer text</text>
     <image [url="url"]>image</image>
  </footer>

• These should appear first in the file after the <app> tag.
• For more on <image> see image in the section that describes the widgets.

[edit] Title String Widget: Automatic Updating of Save Filename

Many applications require a title option, which is included in the input file. If you include a string widget with id="title" (as shown below), in addition to being able to use this option in your xsl file, it will become the default filename when saving in appForm.

<string id="title">
     <about>
     ..
     </about>
     <cols>n</cols>
     <default>default value</default>
       <preset value="value">label for this preset</preset>
     ...
</string>

• In the above example, whatever value the user types in the "title" input field will become the default filename to save
• Note: Using this option will only provide a default value when saving, it is still user-changeable
• It is suggested that this be the first widget to be coded in the xml file (after the heading section)

[edit] xml Element for Applications which "batch" "Jobs"

THIS OPTION IS NOT YET FULLY IMPLEMENTED

  <batchJob/>

• The tag should be specified directly after the <app> element
• The <batchJob/> tag allows for multiple "jobs" to be included in one input file. This is useful in programs such as Q-Chem, NWChem, etc. This tag implements the formatting of the appForm to accomodate this, including the addition of buttons to control the addition and removal of jobs.
• This option is transparent, if the tag is not included, the application will behave normally.

[edit] Useful Links

• appForm Main Page

• AppForm FAQ

• Sample app_form.xml file

• Documentation on app_job.xml (Job Parameters Tab)

• Documentation on app_form_input.xsl (Translator which creates input file)