Entando plugin: Web Dynamic Forms
Installation and configuration of the plugin jpwebdynamicform
The purpose of this guide is to provide a complete description of the Entando Web Dynamic Forms plugin whose code is jpwebdynamicform for the Entando platform.
This guide is intended for both administrators and developers who wish to explore the capabilities of the Entando Plugin Web Dynamic Forms and are considering a possible integration into a running production environment or in a Development Environment.
In order to take maximum advantage from the present guide, it is necessary to have basic knowledge of the Java platform, the servlet engine Apache Tomcat, PostgreSQL (or MySQL) DBMS and the Entando platform.
Moreover, it's necessary to have read the Plugin Pattern for the installation procedure basics and the explanation of the standard directory layout.
The jpwebdynamicform plugin enables the visitors of the portal to initiate a two-ways communication with the managers of the portal via notifications sent by email: in this respect we can consider the Dynamic Form (better, the correspondent entity type) in term of a message sent from the visitor to the administrator. By visitors, or guests, we intend unregistered portal users.
Please be aware that this plugin wasn't conceived as a message exchange tool: the administrator won't see any response from the visitor anywhere in the backend; the communication is intended to continue via email.
The administrator might choose to write back to the user by email or to use the backend interface provided: in this case all the responses toward the visitor will be recorded (and optionally are made available for use by other plugins).
The plugin provides a interface in the portal through which the visitors submit a form to the administrator: this interface is capable of delivering dynamic forms, customizable at will thanks to the Entando entity engine.
Administrators have a number of configuration decisions to take through the management interface in the backend:
-
create the proper entity types for the forms
-
decide how the message will be handled by the system that is, whether it will be stored in the database or notify a new message to a list of specific users
-
configure the page(s) where the form(s) will be published
Due to its nature, jpwebdynamicform requires as a prerequisite the Email Sender. This information is relevant only for the installations in production environments: the administrator is required to manually provide the prerequisites. For further details on those plugins consult the respective manuals.
For installations in a development environment there are no problems because Maven takes care of the prerequisites automatically; though the plugin installation is not difficult at all, we are going to modify the system tables, so a backup of your database is highly recommended. Furthermore, you may be required to customize the scripts to your needs before installation.
For the purpose of the current guide, a few Maven and Ant commands are shown: your IDE has probably the ability to execute those commands for you in background.
jpwebdynamicform is a pure plugin, thus it neither affects the core of the system nor the existing functionality.
jpwebdynamicform directories are organized following the Maven Standard Directory Layout as shown in the Developers guide – Plugin guide.
It is worth of note that the plugin installation is greatly changed from the previous releases (thank you, Maven!).
As always when it comes down to install new things, stop your servlet container before moving on.
Open the pom.xml of your project: locate the <dependencies> tag toward the end of the file, after the <build> tag; if the tag dependencies doesn't exist just create a new one just after the closure of the build tag.
Add the following snippet inside the dependencies:
<dependency>
<groupId>org.entando.entando.plugins</groupId>
<artifactId>entando-plugin-jpwebdynamicform</artifactId>
<version>${entando.version}</version><!-- version. Don't remove this comment. -->
<type>war</type>
</dependency>You are done! You can verify the correct installation of the plugin going to the administration area and checking for the new item in the Plugins menu.
From now we will use the name myportal when referring to your deployed Entando application or, in other words, to the artifact ID of the deployed portal.
All Entando plugins can be downloaded from the Maven Central repository, just filter by code and by version.
To install jpwebdynamicform in a production environment the file jpwebdynamicform-3.2.0.war is needed; we will refer to this file as WAR package.
The WAR package might contain the dependencies of other plugins; when performing copy operations you may accidentally overwrite your previous customizations of the JSP files, so you are warmly recommended to create a backup of your installation.
The integration activity must be performed after the servlet container has been stopped.
-
Install the Email Sender plugin in the production environment (consult the relative documentation for the correct procedure to follow), if it is not already present
-
copy the content of
WEB-INF/libdirectory of the WAR package, tomyportal/WEB-INF/lib/directory -
create the directory
myportal/WEB-INF/plugins/if it does not exist. Copy the content ofWEB-INF/plugins/directory of the WAR package, tomyportal/WEB-INF/plugins/ -
copy the content of
resources/pluginsdirectory of the WAR package, tomyportal/resources/plugins/directory
Now the servlet container can be restarted.
The jpdynamicwebform management interfaces are grouped under the Plugin → Web Dynamic Form. From this moment on, the terms Dynamic Form, (form) entity and (form) message refer to the same entity that is displayed as a (dynamic) form of the portal that later becomes an email message to the administrator when the visitor (or guest) submits the data.
This first thing to do in order to configure the plugin is to create at least one entity for the form. This is done accessing the Message Types item in the menu of the plugin.
Consistently with the Entando entity management interface you go through the configuration simply clicking on the description of the relative list entry. You may optionally delete an existing entity simply clicking on the removal icon.
Please note that you are not allowed to delete an entity type of a Dynamic Form unless you delete all the message history in advance.
The administrator can edit the entity type of the form simply clicking in the description; the icon in the column labeled R shows whether the references must be reloaded (a sun icon appears) or not (a moon icon is displayed), as depicted in the image below:
To force a reload of the references you may click the moon icon itself or to the link within the list named Reload References for these Entity Types provided in the bottom of the page.
A new form is created clicking the New Entity Type link, as shown below
The Key is a three letters name which identifies uniquely the entity while Description is a human readable string.
The administrator builds the entity adding the attributes desired using the Add button and then completing the configuration relative to that attribute; the Save button saves the entity and returns to the entity list.
Consistently with the others entity engines of the system, the administrator can arrange the items in the list by clicking the arrows or to delete them using the removal button.
The column labeled with an asterisk shows whether the attribute is mandatory; the next column, labeled F indicates if the corresponding attribute can be used as filter in list. The sun and the moon icon shows whether the option is enabled or not, respectively.
Accessed through the Configuration menu, this management page enables the administrator to configure the different Dynamic Forms; entering the configuration page you are first asked to select the entity to be modified
Once you have chosen the desired Message Type click the Continue button to proceed with the configuration.
Once that the configuration is over, the administrator will return to this page.
The WebDynamicForm section provides a brief explanation of the main settings
The Local Message Storage checkbox makes the messages list available to third part software for import.
The Sender represents the email used by the system for communication.
The Email Attribute from Message is used to select the attribute of the entity (Dynamic Form) which holds the email address of the user.
Object and Template Body are used to define the email template. Is it important to notice that the body of the email is a Velocity template; you have two tokens, $i18n and $message that will be respectively expanded with the appropriate label and with the various fields of the message.
For example, a given a Dynamic Form named Company form, composed with the following MonoText attributes:
- Company
- Address
- Note
might have a corresponding Velocity template similar to the following:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="it">
<head><style type="text/css">.body {padding: 1em;} body {background-color: #fff;color:#333333;font-family:Verdana,Arial,sans-serif;font-size:100.01%;margin: 0 auto;max-width: 1200px;} .header {padding: 1em; background-color: #E5ECFA;color: #0F4780; border-top: 0; border-bottom:2px solid #0F4780; } .footer {background-color:#E5ECFA;border-bottom:2px solid #0F4780;border-top:2px solid #0F4780;padding:0.1em 0.5em; }</style> </head>
<body>
<div class="header"><h1>Municipality of Villamarina</h1><h2>Feedback Service</h2>
<div class="body">
<p>$i18n.getLabel("jpwebdynamicform_TITLE_PER") arrived:</p>
<hr />
<dl>
<dt>$i18n.getLabel("jpwebdynamicform_COM_Company")</dt>
<dd>$message.Company.text</dd>
<dt>$i18n.getLabel("jpwebdynamicform_COM_Address")</dt>
<dd>$message.Address.text</dd>
<dt>$i18n.getLabel("jpwebdynamicform_COM_email")</dt>
<dd><a href="mailto:$message.email.text">$message.email.text</a></dd>
<dt>$i18n.getLabel("jpwebdynamicform_COM_Note")</dt>
<dd>$message.Note.text</dd>
</dl>
<hr />
</div>
</body>
</html>Here the tokens replacement behaves like expected, providing the data submitted in the form (please note that you have to provide the i18n labels into the language manager of Entando from the left menu → Languages → Labels)
In the Automatic Notification the administrator inserts the email addresses of the people which are going to be notified whenever a new form is submitted:
The Active checkbox toggles the notification service: every time a visitor submits a form the people in the list of the recipients will receive a notification.
As you can see from the image above you may define three kind of recipient: only the Primary Addresses and the Bcc were defined.
In this management interface we have the list of the forms/messages submitted by the visitors of the portal; you may Search by Type and, in the Base Search section, a submission period ( From, To) and the Status ( Answered / Not Answered or both) can be imposed as well.
The basic search is launched by clicking in the Search button; if a particular form type was chosen the Search By Type select, the Advanced Search section becomes active providing new search criteria, depending on how the attribute of the form were configured.
As a side note, all the parameters of the Basic Search section are retained when the advanced search is enabled: they can be changed anytime.
The button Change, which pops up as soon as the Advanced Search becomes available, enables the administrator to change again the type of the Dynamic Form (or, in other words, the corresponding entity) to search for; as soon as the Change button is clicked the Advanced Search is deactivated.
The advance Search section will show only those attributes suitable to be used as filters in list; the “Company form”, used as reference in the previous chapter, has the only attribute “Company” declared available to be used as a filter for lists.
The image above shows the situation aforementioned.
In whatever way the search is done a list of results similar to the following is produced
The Status column shows whether the message has been responded or not: the moon icon means that this form hasn't been replied yet, otherwise a sun is used.
The removal icon is used to delete the entry while a click on the envelope icon lets the administrator to answer to the visitor.
The administrator can visualize a summary of the submitted data just clicking on the item in the Request column:
From this page you can also see all the given answers -newest first- but not the replies coming from the site visitors because that would be beyond the scope of the plugin.
As stated earlier the page that enabled the administrator to write back to the visitor is accessed through the mail envelop icon:
As a side note, an attachment can be included in the reply message.
The response is sent immediately clicking the Send button.
This plugin adds two Widgets (from the left menu → Widgets)
The Dynamic Web Forms – Choice a type of a type Message Widget is used when multiple forms have been defined and we want to give the visitor the possibility to choose the form to apply for.
The Dynamic Web Forms – Publish the form for a message type is used to provide a fixed form in the frontend. When this Widget is assigned to a frame the administrator is prompted for the Message Type (or the Dynamic Form) to display as shown below
Here are some screenshots of showlets in action. Please remember that all showlets provided do not have any graphical decoration, so the actual images may differ.
The following picture shows the Dynamic Web Forms – Choice a type of a type Message Widget.
The user makes his choice and then the desired form is displayed
The Dynamic Web Forms – Choice a type of a type Message Widget would have automatically displayed this form, if configured to
After the form is submitted it is possible to start the submission of a new form.
