DynaForms

DynaForms, or "Dynamic Forms", are the custom forms which can be designed in ProcessMaker to interface with the user while running a case. DynaForms allow users to view and enter data into cases in a graphical interface which should be intuitive for even non-technical users.

The DynaForm Editor is designed to be user-friendly for process designers who don't have any programming experience, yet also provide the full XML code and the HTML code for process designers who want to customize their forms to their hearts content. DynaForms allow process designers to use SQL queries to pull data from external databases or the ProcessMaker databases. With case variables, data can also be pulled from ProcessMaker triggers and used in the fields in DynaForms. Finally, audacious process designers can add their own custom JavaScript code to dynamically control their DynaForms, error check the data and provide feedback to the user.

Creating DynaForms

To create a new DynaForm, first open the process where the DynaForm will be used. (Go to the PROCESSES menu, find a process in the list and click it's Edit link.) Then select the DYNAFORMS tab to display the list of existing DynaForms. Click the New link at the top left of the list.

Enter a Title for the DynaForm. Production users who run cases can see the DynaForm title when they go to the INFORMATION tab and click the DynaForms button, so create a title which will make sense to users running cases.

Select the Type of DynaForm. Normal or master forms are designed to display only a single record and their fields are laid out vertically by default. They are stand-alone forms and can not be embedded into other forms.

In contrast, grid forms are designed to contain multiple records. Their fields are laid out horizontally in a single row, so they can be repeated to form a table consisting of columns and rows. Grid forms are also capable of using special aggregate functions, such as sum, to perform operations on all the fields in a column. Grid forms can only contain fields which are types of textboxes and dropdown boxes, because they occupy little space and are easily displayed in the format of rows. From version 1.2-2740 on, grids can also contain textareas and hidden fields.

Grid forms are created separately from master forms, but they can not be used alone and must be embedded in a master form when used in a process. Embedding the grid form in a master form provides it with additional controls to add and delete records.

Enter a Description for the DynaForm. The description will not be seen by ordinary production users who run cases, so geer the description for process designers who may need to edit the DynaForm later. Since the description doesn't automatically line wrap, use hard returns.

Click Save to create the new DynaForms and return to the list of available DynaForms for the process. Click Save and Edit to create the new DynaForm and immediate begin editing it in the DynaForm Editor.

Managing DynaForms

All the DynaForms available for the current process can be found by selecting the DYNAFORMS tab (under the PROCESSES menu).

• UID: The unique identification, which is a string of 32 hexidecimal characters used to identify DynaForms.
• Title: The title of DynaForms.
• Type: The type of DynaForm, which can be either "Normal" or "Grid".
• Edit link: Click to edit the DynaForm.
• Delete link: Click to delete the DynaForm.

To hide a column in the DynaForm list, right click on the column headers and unselect the checkbox next to the column to hide it.

The DynaForm Editor

The DynaForm Editor provides a graphical designer for DynaForms, with a toolbar to add new elements to DynaForms and tabs to switch easily between the graphical preview of the form, the code, and the definition of the fields in the form.

Unlike the drag-and-drop interface of the Process Map, the DynaForm Editor is a click-and-define interface. Click on the toolbar to add a new object to the DynaForm, then define the chacteristics of that object. The DynaForm Editor allows for the properties of objects to be specified to a great degree, and access to the XML code allows for a great deal of flexibility in object definition. The Preview tab allows process designers to check how fields in the form will appear and be populated with values before running a case.

Objects are added to DynaForms in a specific order to DynaForms and can not be moved around freely with the mouse. Instead, objects can only be moved around by changing their order inside the Field List tab or by modifying the HTML code for the form. The WYSIWYG HTML editor allows designers to customize the appearance of DynaForms. For process designers who want maximum control over their forms, full access to the HTML code is provided.

The DynaForm Editor Toolbar

The DynaForm Editor provides a toolbar to easily add fields and other objects to the DynaForm. The toolbar buttons function while in all the DynaForm Editor tabs, so objects can be added to DynaForms at any time, whether using the Preview mode, editing code, viewing the field list, or setting the form properties. Unlike the Process Map toolbar which uses drag-and-drop icons, the icons in the DynaForm Editor toolbar are activated by a single mouse click over the icons.

• save
  Click to save the DynaForm. Before version 1.2-2895, ProcessMaker did not allow for different versions of a DynaForm to be saved. If making experimental changes to a DynaForm which you might want to later undo when using an older version of ProcessMaker, it is recommended to first export your process, so you can later import the old process definition if you decide to not keep your changes.
• save as
  Click to save a copy of the DynaForm. A new feature in version 1.2-2895 and later which allows the content of the present DynaForm to be saved under a different DynaForm name. "Save As" is useful when making another copy of a DynaForm to make experimental changes or when creating multiple copies of the same DynaForm with slight changes to the fields.
• text
  Add a textbox to the DynaForm, which is designed to input one line of text.
• currency
  Add a currency textbox to the DynaForm, which restricts the input to numbers.
• percentage
  Add a percentage textbox to the DynaForm, which restricts the input to numbers to form percentages.
• password
  Add a password textbox to the DynaForm. This textbox displays the input as ******, so observers can't easily glimpse passwords.
• Suggest
  Add a suggest box to the Dynaform. A new feature in version RC2_1.2-3306 and later which shows the users a list of suggestion as he types in the box, and it allows one value to be selected.
• textarea
  Add a textarea to the DynaForm, which is designed to input more than one line of text into a form. The number of lines and width of the textarea can be specified, and scrollbars will automatically appear to allow for greater space if more text is entered.
• title
  Add a title to the DynaForm, which are designed to label the major sections of the form.
• subtitle
  Add a subtitle to the DynaForm, which are designed to label the minor sections of the form and appear with a smaller font and more indentation than a title.
• button
  Add a button to the DynaForm. The functionality of a button has to be added with custom JavaScript code.
• submit
  Add a submit button to the DynaForm. Submit buttons save the data entered into a Dynaform to the database and to case variables, so the data can be accessed later in the case.
• reset
  Add a reset button, which clears the entered data and resets the DynaForm to its original state.
• dropdown
  Add a dropdown box to the DynaForm. Dropdown boxes allow the user to select from a list of predetermined options which drop down. They occupy less space than a listbox, but only allow a single value to be selected.
• yesno
  Add a Yes/No dropdown box, which is designed to present a binary "Yes"/"No" option to the user. Unlike checkboxes, Yes/No dropdowns can be used in grids.
• listbox
  Add a listbox to the DynaForm. Listboxes allow the user to select one or more predetermined options. They are more convenient to use than a dropdown box, since they do not require clicking to see the available options and they allow more than one option to be selected, but they occupy more space.
• checkbox
  Add a checkbox to the DynaForm. Checkboxes offer a binary on/off choice and are square in appearance with a check mark when activated (on). Checkboxes are convenient for allowing a user to activate an option with a single click of the mouse and are recommended over Yes/No dropdown boxes in most cases.
• checkgroup
  Add a checkgroup, which is a group of checkboxes where the user can activate all, some or none of the checkboxes. The checkbox group has a title (label) and all the checkboxes in the group should be related in some way to that title.
• radiogroup
  Add a radiogroup to the DynaForm. Like checkboxes, radio buttons offer only a binary on/off option, but they are round and a black dot appears in the middle when activated (on). Unlike checkgroups, radiogroups only allow the user to select one option, and will deselect all other options. Like listboxes, radio groups occupy more space but are more convenient for the user since selection only requires a single click.
• date
  Add a date selector to the DynaForm, which does not allow the user to directly enter the date like a normal textbox. Instead clicking on the box opens a calendar where the user can select the date. This helps standardize date formats and eliminates many careless errors. Date selectors also offer another button to clear the date.
• hidden
  Add a hidden field to the DynaForm. Hidden fields allow for unseen variables to be added to the DynaForm. They are often used when needed to pass extra data to JavaScripts or when needing a space to store data which shouldn't be seen by the user.
• link
  Add a link to the DynaForm. Links can either be hyperlinks to external web pages, or an internal link to another DynaForm.
• file
  Add a file to the DynaForm, which provides a dialog box to upload a file. The files can either be an Input Document (since version 1.2-2467) or an undetermined file.
• javascript
  Add JavaScript code to the DynaForm, which allows the process designer to customize the behavior of the form, add data checking and perform custom calculations.
• grid
  Embed a grid form inside the master DynaForm. Grid forms are special forms which present data in a table format consisting of columns and rows. They offer controls to add and delete rows and aggregate functions such as summing a column.

The DynaForm Editor Tabs

The DynaForm Editor offers a tab bar which allows the process designer to switch rapidly between field definitions and code editing to a graphical preview mode to check how the DynaForms will appear to the user.

Preview tab

Displays a graphical preview of the DynaForm. Here the process designer can try out the form to see how the objects in form will appear and how they will be filled with values. Preview mode may have slight differences from when it is run in a case, especially if it uses fields which depend upon values entered in previous DynaForms or case variables defined in previous triggers.

Nonetheless, the preview mode should allow process designer to check layout and design of the DynaForm, verify the default values and the options in listboxes, dropdown boxes, checkbox groups, etc, and verify the SQL statements used to populate fields (as long as the requisite tables already exist). Moreover, Preview mode will run JavaScripts, so it should be possible to debug code which doesn't depend upon case data. Running test cases to polish and debug DynaForms can be a laborious process, so process designers should make use of the Preview mode as much as possible to shorten development time.

XML tab

ProcessMaker uses XML (Extensible Markup Language) to define the fields and other objects used in DynaForms. The flexibility of XML and its ability to add custom options to the language makes it a good match for ProcessMaker.

Process designers who want complete control over the definition of objects in their DynaForms can switch to the XML tab and directly access the code. Moreover, there is some functionality, such as the use of aggregate grid functions and the use of PM tables and custom arrays to populate lists which is only possible by editing the XML code. New functions in ProcessMaker are generally added first to the XML code before they are added to the graphical field designer in the Fields List tab. See DynaForm Fields for more information about how each field is defined in the XML.

After modifying the XML code, the Preview mode and Fields List will automatically update according to the changes in the XML. If altering the definition of objects in XML, it is a good idea to switch to the Preview mode or the Fields List to check the validity of your changes. Mistakes in the XML can usually be caught by checking how ProcessMaker displays the altered DynaForm in Preview mode.

It is very easy to make a mistake when editing XML and the DynaForm Editor does not offer an undo option. Therefore, it is a good idea to make a backup copy of your original XML code before beginning to edit it. Press CTRL + A to select all, CTRL + C to copy, and then paste the original code into a plain text editor such as Notepad++ in Windows or gedit or vim in Linux/UNIX to store it. If you make a mistake at any later point, you can always return to the original XML by pasting it back into the DynaForm Editor.

XML form storage

The XML code for DynaForms is stored in the file location:

<INSTALL-DIRECTORY>/shared/sites/<WORKSPACE>/xmlForms/<PROCESS-UID>/<DYNAFORM-UID>.xml

For example:

Linux/UNIX:

/opt/processmaker/shared/sites/workflow/xmlForms/728cae447fbdF7be6aeb1276dce1f/41162480747fa4824e244a076980812.xml

Windows after version 1.6-4260 or manual install:

C:\Program Files\ProcessMaker\processmaker\shared\sites\workflow\xmlForms\728cae447fbdF7be6aeb1276dce1f\41162480747fa4824e244a076980812.xml

Windows before version 1.6-4260:

C:\Program Files\ProcessMaker\apps\processmaker\shared\workflow_data\sites\workflow\xmlForms\728cae447fbdF7be6aeb1276dce1f\41162480747fa4824e244a076980812.xml

If an XML form gets corrupted and can not be edited inside ProcessMaker, it is possible to directly edit the form with a plain text editor. While a DynaForm is being edited, it is saved as a temporary file named:

<INSTALL-DIRECTORY>/shared/sites/<WORKSPACE>/xmlForms/<PROCESS-UID>/<DYNAFORM-UID>_tmpN.xml

Where N is a number, starting from 0.

For example:

/opt/processmaker/shared/sites/workflow/xmlForms/728cae447fbdF7be6aeb1276dce1f/41162480747fa4824e244a076980812_tmp0.xml

If the system crashes while editing a DynaForm, it is possible to recover it by copying the XML code out of the temporary file.

HTML tab

Although ProcessMaker uses XML to define the objects in DynaForms, the layout and appearance of those objects is controlled by HTML (HyperText Markup Language). Editing the HTML provides a finer degree of control over the formatting of the DynaForm than using the graphical interface provided in Preview mode and the Fields Handler (formerly named Fields List). Note that only the HTML for master forms can be edited--it will not work for grid forms.

The HTML code should only be edited after defining all the fields and setting the order of the fields in the DynaForm. After changing the HTML code, ProcessMaker may not be able to add, delete, or move fields correctly, since the HTML structure of the form has changed. If unexpected problems arise after editing a form's HTML code, revert the DynaForm's HTML by clicking the button Restore Original HTML.

The WYSWYG HTML Editor

For people who want to alter the appearance of their DynaForms, but don't want the hassle of delving into the HTML code, the DynaForm Editor provides an HTML View area. A WYSIWYG (What You See Is What You Get) HTML editor allows process designers to alter the formatting of DynaForms in a graphical design environment and add some of the more common HTML elements such as hyperlinks, images and horizontal rules. A user-friendly toolbar is provided to automatically insert HTML code into the DynaForm. In addition, users can click anywhere in the HTML View area to manually add text to their forms.

Fields, field labels and other objects defined in the XML are inserted directly into the HTML with PHP variables, which are enclosed in curly braces {}.

{$form.field_name}         A DynaForm field defined as a member of $form, which is the DynaForm object.
{$field_name}              The label for a DynaForm field.
{$form.__DYNAFORM_OPTIONS} The DynaForm properties and general settings.

It is very important that no text or HTML tags be inserted inside the curly brackets or the DynaForm objects won't be inserted into the HTML correctly. When applying formatting to a PHP variable, make sure that the formatting encompasses the entire variable name, including its curly braces. Do NOT apply formatting like this:

The HTML tags <big> and <span> are inserted into the middle of the name of the PHP variable {$Employee_Name}:

{$Emplo<big><span style="font-weight: bold;">yee_Na</span></big>me}

When switching to Preview mode, the following error will arise:

Instead, HTML formatting should be applied to the entire variable name including its curly braces like this:

Here the HTML tags aren't inserted into the PHP variable name:

<big><span style="font-weight: bold;">{$Employee_Name}</span></big>

This will yield the following formatting in the DynaForm:

If you accidentally insert HTML tags or text into a PHP variable name and can't figure out how to undo the problem, click on the Restore Original HTML button, which will loose any changes made to the HTML and return it to its original state.

The HTML Toolbar

Click on icons in the HTML toolbar to insert new HTML elements such as hyperlinks, email links, images and horizontal rules. To alter the formatting of an HTML element, first select the element in the HTML View area and then click on the appropriate icon in the toolbar. It helps to know a bit of HTML when using the toolbar, since some of the icons force the user to manually enter bits of code, as in the case of the Email link, or the RGB (Red, Green, Blue) numbers when selecting colors.

• Bold: To convert text to boldface, select the desired text, then click this icon.
• Italics: To convert text to italics, select the desired text, then click this icon.
• Underline: To underline text, select the desired text, then click this icon.
• Left Align: To left align a paragraph or any other HTML element, click to set the cursor inside the element in the HTML View area, then click this icon. Multiple HTML elements can be left aligned at once by selecting them and then clicking this icon. By default most fields in DynaForms are left aligned.
• Center Align: To center a paragraph or other HTML elements, click to set the cursor inside the element in the HTML View area, then click this icon. Multiple HTML elements can be centered at once by selecting them and then clicking this icon.
• Right Align: To right align a paragraph or other HTML elements, click to set the cursor inside the element in the HTML View area, then click this icon. Multiple HTML elements can be right aligned at once by selecting them and then clicking this icon. By default most fields labels in DynaForms are right aligned.
• Justify: To justify a paragraph or another HTML element, so it fully extends between the right and left margins, click to set the cursor inside the element in the HTML View area, then click this icon. Multiple HTML elements can be justified at once by selecting them and then clicking this icon.
• Cut: Note: This icon does not currently work. Use CTRL + X to cut elements in the HTML View area.
• Copy: Note: This icon does not currently work. Use CTRL + C to copy elements in the HTML View area.
• Paste: Note: This icon does not currently work. Use CTRL + V to paste elements in the HTML View area.
• HyperLink: Note: This icon does not currently work. Edit the HTML code to add hyperlinks.
• Undo: Click to undo the last change to the HTML. Multiple undo actions are permitted. Note that switching out of the HTML tab will clear the undo stack, so don't switch to Preview mode and then try to undo HTML changes afterwards.
• Redo: Click to redo the last change to the HTML. Multiple redo actions are permitted.
• Font: To change the type of font, select text and then click this icon to open a dialog box. Enter the name of the font. It is recommended to not use specific fonts, since not all computers will have them. Instead, enter generic font names, such as "serif" in place of Times New Roman, "sans serif" in place of Arial and "monospace" in place of Courier.
• Larger Font: To raise the font size one notch on HTML's 7 font size scale, select text and then click this icon to insert <big> tags around the text.
• Font Color: To change the font color, select text and click this icon. Enter a color code and click OK.
• Highlight Color: To change the highlight color, select text and click this icon. Enter a color code and click OK.

• Superscript: To convert text to superscript, select the text and click this icon.
• Subscript: To convert text to subscript, select the text and click this icon.
• Strikethrough: To strikethrough text (put a line through the middle), select the text and click this icon.
• Increase Indent: Click this icon to increase the indent of the current paragraph. Select multiple paragraphs to indent all at the same time.
• Decrease Indent: Click this icon to decrease the indent of the current paragraph. Select multiple paragraphs to decrease the indent of all at the same time.
• Numbered List: Click this icon to add a numbered list to the current paragraph. Select multiple paragraphs to convert them into a numbered list.
• Bullet List: Click this icon to add a bullet point to the current paragraph. Select multiple paragraphs to convert them into a bullet list.
• Erase: To erase, select parts of the form to erase and click this icon.
• New Paragraph: This icon does not currently work. To add a new paragraph, insert the tag <p> in the HTML code.
• Horizontal Rule: Click to add a horizontal rule (line) to the form.
• Erase HyperLink: To remove a hyperlink, select a hyperlink and click this icon
• Email: To add an email link, click this icon and enter the HTML code for an email link such as:
  <a href="mailto:albert@colosa.com">Email Albert</a>
• Image: To insert an image, click this tab and enter the URI (web address) of an image.
• Font Size: To set the font size on a scale from 1 to 7, select text and click this icon. Enter the font size number and click OK.
• Smaller Font: To lower the font size one notch on HTML's 7 font size scale, select text and then click this icon to insert <small> tags around the text.
• Background Color: To change the background color of the entire form or the current cell if inside a table, click this link. Enter a color code and click OK.
• Block: This icon does not currently work.

Note: Colors in HTML can be specified with 6 hexadecimal digits preceded by a hash sign (#), which represent each of the RGB (Red, Green Blue) colors on a scale of 0 to 255. Alternatively, use one of 150 standard color names which are understood by all web browsers. So, red can be specified as either "Red" or "#FF0000".

Altering the HTML Table Structure

DynaForm forms are constructed with HTML tables, so each field is contained in a table row and the label and field are separated into table cells. The WYSIWYG HTML Editor provides a user-friendly tool to alter this basic table structure.

Resizing the form
The form in the WYSIWYG HTML Editor will initially appear with the table resizer controls on each side and in each corner. To redimension the form, drag and drop the resizer controls. An arrow will appear in the control, indicating in which direction the table is being resized.

Adding Rows
To add a new row to the form, select an existing cell, so the row control appears on the left-hand side of the cell. To select the cell, rather than text inside the cell, press the ALT key and click in the cell. To add a row above the existing row, click on the red up arrow in the row control. To add a row below the existing row, click on the red down arrow .

Deleting Rows
To delete a row in the form, select an existing cell, so the row control appears on the left-hand side of the cell. Then click on the red center circle in the control.

Adding Columns
To add a new column to the form, select an existing cell, so the column control appears above the cell. To select the cell, rather than text inside the cell, press the ALT key and click in the cell. To add a column to the left of the cell, click on the red left arrow in the control. To add a column to the right of the cell, click on the red right arrow in the control.

Deleting Cells
To delete an existing column, select an existing cell, then row in the form, select an existing cell, so the row control appears on the left-hand side of the cell. Then click on the red center circle in the control.

Editing the HTML Code

The HTML View area is easy enough to use, that most people can avoid having to edit the HTML code in their DynaForms. Nonetheless, the WYSIWYG HTML editor has a number of limitations. The DynaForm Editor is designed to insert fields vertically in the DynaForm and the WYSIWYG HTML editor can only make basic alterations to the form structure. For example, the HTML code must be directly edited in order to position fields in horizontal rows.

To begin editing the HTML code, click on the Enable HTML Editing checkbox to activate it. Then edit the HTML code. To check how the changes to the HTML will effect the DynaForm, click the Refresh View button, which will update the HTML View area and the Preview mode for the DynaForm. Note that these changes will not be permanently saved until the Save icon in clicked in the main DynaForm Editor toolbar.

Unlike when editing XML, ProcessMaker provides the option to undo the changes to the HTML. To revert the HTML to its original state, click on the Restore Original HTML button. Note that this button will NOT revert the HTML back to the last time it was saved. Instead, the HTML will be reverted back to the state defined by the field list and the default ProcessMaker layout for DynaForms. So all your customizations to the code will be lost. If you might want to revert the code back to a previous version which includes your modifications, it is recommended to make copies of the code and save them in an external plain text editor.

HTML form storage

If HTML editing is enabled for a DynaForm, its HTML code is stored in the file location:

<INSTALL-DIRECTORY>/shared/sites/<WORKSPACE>/xmlForms/<PROCESS-UID>/<DYNAFORM-UID>.html

For example:

Linux/UNIX:

/opt/processmaker/shared/sites/workflow/xmlForms/728cae447fbdF7be6aeb1276dce1f/41162480747fa4824e244a076980812.html

Windows after version 1.6-4260 or manual install:

C:\Program Files\ProcessMaker\processmaker\shared\sites\workflow\xmlForms\728cae447fbdF7be6aeb1276dce1f\41162480747fa4824e244a076980812.html

Windows before version 1.6-4260:

C:\Program Files\ProcessMaker\apps\processmaker\shared\workflow_data\sites\workflow\xmlForms\728cae447fbdF7be6aeb1276dce1f\41162480747fa4824e244a076980812.html

If the HTML code gets corrupted and can not be edited inside ProcessMaker, it is possible to directly edit the code with a plain text editor. While a DynaForm is being edited, it is saved as a temporary file named:

<INSTALL-DIRECTORY>/shared/sites/<WORKSPACE>/xmlForms/<PROCESS-UID>/<DYNAFORM-UID>_tmpN.html

Where N is a number, starting from 0.

For example:

/opt/processmaker/shared/sites/workflow/xmlForms/728cae447fbdF7be6aeb1276dce1f/41162480747fa4824e244a076980812_tmp0.html

If the system crashes while editing a DynaForm, it is possible to recover it by copying the HTML code out of the temporary file.

Fields Handler tab

The Fields Handler tab allows all the fields in a DynaForm to be easily viewed at a glance and their definitions to be edited or deleted. Moreover, the Fields Handler provides the ability to easily reorder fields in DynaForms by dragging and dropping the fields in new locations with the mouse. After changes are made to the definition of fields in the Fields Handler, the DynaForm will automatically be updated in the XML and Preview tabs.

• Field Name: Displays the field names, which is how fields are identified in their XML definition and how they are saved as case variables.
• Field Label:
• Type: This column displays the type of field, such as "Title", "Text", "Dropdown" or "Grid".
• Edit: Click this link to open a dialog box to edit the definition of the field.
• Delete: Click this link to delete the field from the DynaForm.

Old Fields List

If using version 1.2-2552 or earlier, the Fields Handler had a different interface and was named the Fields List. The principal difference is that the old Fields List did not display field labels and did not allow field order to be changed by dragging and dropping fields with a mouse.

• Field Name: This column displays the field names (which is different from their labels which appear on the DynaForm).
• Type: This column displays the type of field, such as "Title", "Text", "Dropdown" or "Grid".
• Edit: Click this link to open a dialog box to edit the definition of the field.
• Delete: Click this link to delete the field from the DynaForm.
• Up: Click this link to raise the field higher in the field order. Note that this link may not have any effect in the appearance of the DynaForm if the HTML code has been altered.
• Down: Click this link to lower the field in the DynaForm. Note that this link may not have any effect in the appearance of the DynaForm if the HTML code has been altered.

JavaScripts tab

ProcessMaker allows process designers to insert JavaScript into their DynaForms. As a browser-side scripting language, JavaScript is limited to accessing only the objects within the DynaForm, so it can not access case and system variables, use ProcessMaker web services or consult databases like ProcessMaker triggers. Nonetheless, within the sandboxed environment of a web browser, JavaScript can add error checking, dynamic controls and dialogs to forms which will greatly enhance the flexibility and functionality of a process.

JavaScript can not be added to a DynaForm unless it is part of a JavaScript object in the DynaForm. All code entered into the JavaScript editor will be lost unless it is first associated with a JavaScript object. Click on the icon in the toolbar to add a JavaScript object and then define its name and add code.

A DynaForm can have multiple JavaScript objects. To edit the code in one of the JavaScript objects, go to the JavaScript tab and select it from the dropdown box in the uppper left-hand corner. After editing the code, it can be checked by simply switching to the Preview tab. The new JavaScript code will immediately execute upon displaying the form in Preview mode (even if the DynaForm has not yet been saved).

To make a button execute JavaScript code, enter the name of the JavaScript object which contains the code for the button.

The code will not execute unless it is associated with one of the button's events such as onclick, ondblclick, onfocus, or onkeypress. The way to do this is create a function with the code to execute and then assign that function to the button's event. For instance, in this example the function checkInput() will execute when the verify button is clicked:

 function checkInput()
 {
    var maxVal = 100;
    if (getField("price").value > maxVal)
    {
       G.alert("Reducing price to $100", "Value out of bounds");
       getField("price").value = 100;
    }     
 }
 
 getField("verify").onclick = checkInput;

To get started programming in JavaScript, see ProcessMaker's JavaScript manual and download the "JavaScript Tutorial" process from the library.

Properties tab

The Properties tab is where the general characteristics of the DynaForm are set.

• DynaForm: The title of the DynaForm.

• Type: The type of DynaForm, which can be "Master" (normal) or "Grid" forms.

Be careful when switching the type of form from a master form to a grid. Grids can can only contain fields which are links, textboxes (including currency, percentage and date boxes) and dropdown boxes (including yes/no boxes). If any other type of field is included such as a title field or checkbox, errors will generated by switching the form type. Delete all the fields which aren't allowed in grids, before converting from a master form to a grid form.

• Description: A description of the DynaForm, which is mainly used by the process designer, since the normal production user will not see the description.

• Width: The width of the DynaForm in pixels.

It is generally recommended that DynaForms not be wider than 700 pixels, so that they can be displayed on older monitors with 800x600 resolution with room for a sidebar and scrollbars. Narrower DynaForms also allow for easier cutting and pasting of information between windows, which is important for processes which involve a great deal of data entry.

• Mode: This option allows the entire form to either be set to "Edit" or "View" mode.

If set to "View", a user running a case will not be able to alter any of the data in the DynaForm. In Edit mode, the user will be able to edit data in the form, except for fields which have the "Read-Only" option activated or have mode="view" in their XML definition.

• Show print dynaform button: Enabling this options shows a print button in the dynaform, allowing the user to print the dynaform.

• Next Step Link: This option specifies how the data entered into a DynaForm will be handled when moving to the next step in the task.

With the default option "No Save and Continue", any data entered into the DynaForm will be discarded if the user clicks on the "Next Step" link without clicking a Submit button on the form to save the data. With the "Prompt" option, the user will be asked whether the data should be saved or not after clicking the "Next Step" link in the form. The "Save and Continue" option will automatically save any data entered into the form when the "Next Step" link is clicked.

If using the "No Save and Continue" or "Prompt" options for a DynaForm, it is possible that the user will choose to not save the data. If the data isn't saved, no case variables will be created for the fields in the DynaForm. An error can be caused in the process if a subsequent condition or trigger tries to reference a case variable which should have been created when a DynaForm's field was saved.

If users are given the option to not save their data in a DynaForm, but case variables are needed from the DynaForm fields in subsequent steps or conditions, it is a good idea to create a trigger which fires after the DynaForm to create those case variables. For instance, if your case has a checkbox named "Finished_Assignment" and a subsequent evaluation routing rule has the condition @@Finished_Assignment=="On", then you will need to manually create the @@Finished_Assignment case variable if the DynaForm wasn't saved. Add the following code to a trigger which fires after the DynaForm:

 if (!isset(@@Finished_Assignment))
    @@Finished_Assignment = "";

The variable @@Finished_Assignment will be created with an empty string to avoid errors, but it won't equal either "On" or "Off" in case one of the subsequent conditions tests for one of those values.

Click on the Apply button to immediately apply the changes entered into the Properties tab and update the definition of the DynaForm, so the changes can be seen in the other DynaForm Editor tabs.

To undo the changes entered into the Properties tab to the DynaForm definition, click the Revert button.

Conditions Editor tab

The Conditions Editor is a user-friendly way to show or hide different elements of the DynaForm as the user interacts with the form and changes values in the fields. The Condition Editor allows for forms to be created with dynamic content without having to resort to JavaScript code. Conditions are evaluated whenever specified field(s) are either loaded and/or changed. If the condition evaluates to true, then fields will be shown or hidden depending on which function is selected.

Defining a Condition

In the DynaForm Editor, go to the Condition Editor tab, to see the list of conditions. To create a new condition, click on the New link at the top. The Conditional Show/Hide Editor dialog box will appear where the condition can be defined:

First select one of the functions to either show or hide fields.

Function	Description
Show	Shows the selected fields, but does not affect any other fields.
Show Only	Shows only the selected fields, and hides all other fields in form.
Show All	Shows all fields in the DynaForm. (It is not necessary to select any fields.)
Hide	Hides the selected fields, but does not affect any other fields.
Hide Only	Hides only the selected fields, and shows all other fields in the form.
Hide All	Hides all the fields in the DynaForm. (It is not necessary to select any fields.)

The Show and Hide functions will operate on only the selected fields, but will not affect the visibility of any other fields.

Next, select which field(s) the function will be applied to. In other words, which fields will be shown or hidden. Highlight one or more fields in the Applying the function fields listbox, then click on the button to add those fields to the Selected Fields listbox. To remove a field from the list of Selected Fields, highlight the field and then click on the button.

Note: It is not possible to select reference the fields inside grids, checkgroups or radiogroups in conditions, although it is possible to hide/show checkgroups, radiogroups and grids. If needing conditions which reference the values in grid, checkgroups or radiogroups, then use JavaScript. Before version 1.6-4184, a bug prevented radiogroups and checkgroups from being hidden, so use JavaScript to hide these fields in older versions of ProcessMaker.

Next define the condition, which is a Boolean expression which can evaluate to true or false in JavaScript. If the condition is true, then the function will be executed and show or hide the selected fields. If false, then the function will not be executed, and the appearance of the DynaForm will not change.

In Javascript, any string which isn't empty or any non-zero number is considered true.
Therefore, the following values evaluate to true: 24, 3.14, -42, "HeLlO", "@#$%$%", true
In contrast, the following values all evaluate to false: 0, null, "" (an empty string), false, NaN (Not a Number)

Conditions can either be directly entered into the Condition editing box or the condition can be constructed using the button pad on the right hand side.

Fields from the DynaForm can be referenced by prepending '@#' to the field name. For example, a field named 'ClientAddress', could be referenced as '@#ClientAddress'. Remember that field names are case sensitive. Rather than writing out the field names, it is easier to use the [@#] button to insert the variable names.

Buttons to construct conditions

Button	Description	Example conditions
==	Equals	@#CurrencyType == "dollars" @#Total == 100 @#MyCheckbox == false
!=	Not equals	@#CurrencyType != "euros" @#Total != 0
<	Less than	@#Total < 1000 @#LastName < "M"
<=	Less than or equal to	@#SubTotal <= @#Total
>	Greater than	@#Balance > 0
>=	Greater than or equal to	Math.sqrt(@#Total) >= 5
+	Addition	@#Subtotal + @#Taxes > @#AccountLimit @#FirstName + @#LastName != ""
–	Subtraction	@#Price - @#Discount > 300
*	Multiplication	@#BasePrice + @#BasePrice * @#TaxRate != @#FinalPrice @#Diameter * Math.PI < 25
/	Division	@#Total / @#Quantity < 10
(	Begin grouping	(@#Price - @#Discount) * @#Quantity < @#MinimimOrder
)	End grouping	(100 + @#Percent) / 100 * @#Price < 900
AND	Both expressions must be true to evaluate to true	@#Total > 40 && @#Total < 400 @#Total > 0 && @#PaymentMethod != "credit card"
OR	Only one of the expressions need to be true to evaluate to true	@#Total < 200 || @#PaymentMethod == "cash"
NOT	Reverse the valence, so true becomes false and false becomes true	!(@#Address == "")
@#	Insert field
	Enter test values in field(s)

String values should be enclosed inside double or single quotation marks. Dropdown boxes and listboxes, store the value of the selected option, not the label of the selected option. Checkboxes can either have a value of true or false. For example:

@#MyCheckbox == true

or:

@#MyCheckbox == false

If advanced mathematical operations are needed, use the constants and methods of JavaScript's Math object, such as Math.E, Math.PI, Math.sqrt(), Math.round(), and Math.max().

Note that field references will always return the value property of the field, except for checkboxes, which return the checked property. It is not possible to access any other property of the fields, such as @#MyField.disabled; nor is it possible to call any string methods on the fields, such as @#MyField.toUpperCase() or @#MyField.search(). Since checkgroups and radiogroups, do not have a value property, it is not possible to use them inside a condition. It is also not recommended creating a condition which looks for a particular selected value in a listbox, since multiple options can be selected. If using checkgroups, radiogroups or listboxes, it is recommended to use JavaScript to hide and show fields.

After creating a condition, click on Test Condition to check whether it is a valid condition. If there is an error in the condition, a message will be displayed in red at the bottom of the condition editing box, indicating what is the problem:

If the condition is valid, a message in green will be indicating whether the condition evaluates to true:

or evaluates to false:

Testing the condition at this point will be of little help, since the user hasn't entered any data yet. To test the condition with some data, click on the button and enter some values into the fields used in the condition. Click on Save Data to close the dialog box, then click on Test Condition again to reevaluate the condition with the saved data.

After creating a condition, specify when the condition will be evaluated. If the condition should be evaluated when the selected field(s) are first loaded, i.e., when DynaForm is first displayed, then check the option On load event. If the condition should be evaluated when the user changes the value of the selected field(s), then check the option On change event.

Then select which fields whose onload and/or onchange events will cause the condition to be evaluated. One or more fields need to be selected.

To enable the condition, so it will be evaluated, check the option Enabled.

Managing Conditions

After a condition is created, it is added to the list of available conditions.

To alter a function, click on its Edit link. To remove it, click on its Delete link.

The conditions will be evaluated according to their number in the list, with the #1 condition executing first. This makes it possible to use multiple combinations of conditions. For example, one condition could use the Show All function to show all the fields, then a condition lower in the list could use the Hide function to hide a particular field out of all those which were shown.

Example

A dynaform is used to get information about users' educational history.

If users select "Some grade school", it doesn't make sense to ask for the names of the high school or the universities they attended. Conditions can be used to only show the fields for the level of university attained. See the conditions which were defined in the list above.

When the users select "Bachelors", they are only asked to enter the name of their grade school, high school and the university which granted the bachelors degree.

Printing Dynaforms

From version 1.2-3862Beta and later, a option is available to print Dynaforms. To enable printing, open the form in the DynaForm Editor and to go the Properties tab. Check the option Show print dynaform button. Then, a icon to print the DynaForm will appear in the upper left corner of the Dynaform.

Clicking on the icon will open the DynaForm in a separate window to be printed. If running a case, information will be listed at the top of the DynaForm about the case number, case title, the process name, the current username, and workspace name. If in preview mode inside the DynaForm Editor, only the process name will be listed. In order to print the DynaForm, the machine running the web browser has to be configured to print.

Note: Only data which is currently saved to the database will be printed. To print the form with its current data, add a custom button to the DynaForm and use JavaScript to print the form as it currently appears:

getField("myPrintButton").onclick = function() { window.print(); };

To print the DynaForm with the data which will be saved to the database, use this JavaScript code:

printForm = false;
getField("myPrintButton").onclick = function() { printForm = true; }
getField("myPrintButton").form.onsubmit = function() {
   if (printForm) 
      window.print();
   return true;
}

Configure the browser to print

Mozilla Firefox:
Go to the menu File -> Page Setup and change the Format & Options and the Margins Header & Footer.

Enabling background.

Disable printing headers and footers.

Internet Explorer:
Go to the menu File -> Page Setup and change the Format & Options and the Margins Header & Footer.