Overview

PMDynaform is the component responsible for rendering Dynaforms in ProcessMaker. It is the component in charge of creating controls, building the responsive layout and connecting services to gather and handle form data.

Architectural Design

The PMDynaform component is built over the following libraries:

Four main libraries:

JQuery, used mainly to consume services and for DOM manipulation. It is a requirement for Bootstrap, JavaScript and plugins, and it is also used in Backbone views for DOM manipulation.

Underscore.js, used to manage HTML templates, also used in Backbone views to render form controls.

Common Mistakes

The following list details common problems that architects may encounter using JavaScript in Dynaforms:

Set Field Value Using JQuery .val() or Native JavaScript

As mentioned above, a control view must send changes to its model when the user types something or make use of helpers to set values. This cannot be guaranteed when the data view is modified in other ways like: document.getElementByID("form[field]").value or $("form\\[field\\]").val().

AJAX Requests to Files in the Server

Architects often need to make AJAX requests to obtain additional information from servers while the user is filling out a form. In ProcessMaker 2.x, architects used to code their backend inside plugins and point at the file URL to make AJAX requests. This practice works perfectly fine in a web browser but does NOT work on ProcessMaker Mobile because the form is running on a mobile device, and having a relative URL will cause the AJAX request to try to find the file in the device's local folders.

Going Through the DOM to Reach an Element

Architects cannot rely on the idea that the generated HTML is always going to be the same. ProcessMaker HTML code might change to save issues or add features; therefore it is not recommended to reach elements by referencing the child, parent or sibling nodes.

Dependent Fields Overuse

By using dependent fields, users can populate text fields with the first value returned by a query. This practice is very useful when completing form information. For example, a disabled text field is populated depending on the user email selected from a dropdown. In the same design, the architect can add more fields to be populated in this way, like telephone, username, address, country, ZIP code, position, etc.

The problem with this practice is that each dependent field request is processed individually, even though all the information is read from the same row in a table. In other words, each dependent field will trigger an AJAX request, making the form slower. In this case, it is recommended to create a custom endpoint inside a plugin that will return all the information in JSON format and use JavaScript to populate the fields.

Using CSS Properties that Break Bootstrap (Width Property)

The Bootstrap layout is defined in the HTML class attribute of a container, and divides the container width into 12 columns. If the width container is modified, the responsive behaviour that Bootstrap grants will be compromised.

If for any reason a container width needs to be modified, it is recommended to modify the class attribute of the container following Bootstrap rules.

URL Redirectioning

ProcessMaker Mobile does NOT support URL Redirectioning because the Dynaform runs inside a webkit hosted in the application. Therefore, relative paths will fail and absolute paths to ProcessMaker will generate unexpected behaviours.

Commonly, architects redirect users to the ProcessMaker inbox. The alternative to this practice in ProcessMaker Mobile is to close the Web View with the following helper: form.closeForm()