TECHNICAL ARCHITECTURE FORM FACTORY V2

Transcription

1 TECHNICAL ARCHITECTURE 1

2 SUMMARY OVERVIEW FROM FF1 TO FF SERVER SIDE ARCHITECTURE Structure Rest API OSGI/Extendability CLIENT SIDE ARCHITECTURE LIBRARY Creation Management Use as template Duplicate Import/Export BUILDER Inputs ActionS Steps Validations Logics Layout Jahia Solutions Group SA Page 2 / 72

3 5.7 Metadata Themes Progress Bar Captcha Tracking PREVIEW/LIVE Rendering Inputs Validations Logics Submission Actions Callbacks Per form callback Form Factory API JS callback RESULTS Actions/Results Bound APIBackendType Interface ResultsProviderService Interface Implementations Fetching Views API Mapping JSP file Results API Views Jahia Solutions Group SA Page 3 / 72

4 7.3.2 Metadata view Datatable view Dashboard view PROJECT STRUCTURE GruntJS tasks APPENDIXES WZD files definitions Inputs Actions Validations Logics Renderers Progress Bars Roles/Permissions Roles Permissions JavaScript Frameworks Jahia Solutions Group SA Page 4 / 72

5 Overview In this document we will introduce to the architecture and design of Form Factory 2.0, we will highlight all the changes from version1. First we will describe what has changed and what is new in the structure of the application itself. Form Factory is an application dedicated to ease the creation of all your forms on your platform. To achieve this, FF provide a set of functionalities that can be group in 4 big sections: Building custom form Manage your forms Render/Submit forms Analyze results Jahia Solutions Group SA Page 5 / 72

6 1 FROM FF1 TO FF2 In FF2 we have switch from using Spring Webflow on the server side and BackboneJS on the client side to using a RESTful API and AngularJS for the client. On the DX side we did not touch the node types so that it is easier to move from FF1 to FF2. Your forms and results from version 1 are not lost and will appear right away in version 2. The UI has switch from Bootstrap 2 to Bootstrap 3. The captcha is not using Jahia DX captcha but it is using recaptcha from Google. Changes has been made on how you declare new input/action/validation/logic/callback/renderers/progress bar. From now on once you have defined the node type in the definition file of your module, all the files needed are views of this node type. No more modification of the repository.xml file. From the previous list of extension points you figured that there is quite a lot of new things in this version. FF 2 will allow to have logics on your field to toggle their visibility. This will allow to define forms where fields appear only if the user match certain conditions, you are able to provide your own rules as for validations. Validations validate one field upon static criteria mostly whereas logics allows to show/hide a field based on value of fields on the same step or on previous steps. It is also possible to change the layout of your form, so once you have assembled all the fields you are going to need on each steps of your form you can now dispatch those inputs on a grid and not just under one another as previously. You can now define a progress bar along your form to show to the user where they stand in the form completion. It is possible to associate a form to a callback to react after submission to the result of the actions. The only unchanged part is the results; those have just been upgraded to Bootstrap 3. FF 2 retain the concept of building language, meaning that a form structure (inputs/steps/actions) can only be altered in its building language, in other languages you can only translate some properties Jahia Solutions Group SA Page 6 / 72

7 2 SERVER SIDE ARCHITECTURE The JCR structure of the form has not changed; the new functionalities are working the same way as previous ones. Meaning that logics for example are stored and define like validations. 2.1 STRUCTURE The JSON serialization of a FF2 form is quite similar to the FF 1 serialization. Here an example of FF2 serialization: { "jcrid": "0b7f45fb-081a-4be5-b72f-7bb9d6165d46", "formname": "architecture", "buildinglang": "en", "cssclassname": null, "formdescription": null, "aftersubmissiontext": null, "modified": " T14:02: :00", "steps": [ { "jcrid": "72898fce-effb-4dcf-b6d bd48b9", "label": "Step 1", "inputs": [ { "name": " -input_0_1", "label": " input", "tab": "input", "template": "<ff- ></ff- >", "wizard": "<ff- view-type ='designview'></ff- >", "nodetype": "fcnt: definition", "jcrid": "7714bafe bcd-ba a5eb7e3e", "choicefield": null, "value": null, "layoutuuid": "510917c2-0ea0-47c6-a717-2aa1d545c303", "inputsize": "input-md", "helptext": "Please enter a valid here", "placeholder": "aaa@aaa.com", "definitionoptions": [ "inputsize" ], "definitionoptionstranslatable": [ "helptext", "placeholder" ], "validations": { "required": { "nodetype": "fcnt :requiredvalidation", Jahia Solutions Group SA Page 7 / 72

8 "jcrid": "ef343f97-a59b adf9a06118ab", "message": "This field is required", "definitionoptions": [ ], "definitionoptionstranslatable": [ "message" ], " ": { "nodetype": "fcnt: validation", "jcrid": "7c9f48b7-8ffb-4b96-a46c-6935cbc21997", "message": "Please enter a valid address", "definitionoptions": [ ], "definitionoptionstranslatable": [ "message" ], { "name": "checkboxes-matrix_0_2", "label": "Checkboxes Matrix", "tab": "checkbox", "template": "<ff-checkboxes-matrix></ff-checkboxes-matrix>", "wizard": "<ff-checkboxes-matrix view-type='designview'></ff-checkboxesmatrix>", "nodetype": "fcnt:matrixcheckboxesdefinition", "jcrid": "0ef30bc8-ba51-460e ee7f3c72ca0", "choicefield": "rows,columns", "value": null, "layoutuuid": "d2a15b d-a9f2-8869d0bcc32d", "helptext": "Help", "rows": [ { "key": "q1", "value": "Question One", { "key": "q2", "value": "Question Two", { "key": "q3", "value": "Question Three" ], "columns": [ { "key": "a1", "value": "Answer One", { "key": "a2", "value": "Answer Two", { Jahia Solutions Group SA Page 8 / 72

9 "key": "a3", "value": "Answer Three" ], "definitionoptions": [ ], "definitionoptionstranslatable": [ "helptext", "rows", "columns" ], "validations": { "matrix-required": { "nodetype": "fcnt:matrixrequiredvalidation", "jcrid": "3f38c426-add4-438c-8b21-78cf2ab9f8f3", "message": "Enter your error message here", "definitionoptions": [ ], "definitionoptionstranslatable": [ "message" ], "logics": [ { "name": "if-field-is-valid_0", "nodetype": "fcnt:iffieldisvalidlogic", "jcrid": "16b30c64-9e00-45ec-ac b3ed4", "fieldname": " -input_0_1", "noview": "true", "definitionoptions": [ "fieldname", "noview" ], "definitionoptionstranslatable": [ ] ] ] ], "actions": [ { "jcrid": "1b8226f ae61-b61fcab6960b", "nodetype": "fcnt:savetojcraction", "actionname": "savetojcr", "apientrypoint": "/modules/formfactory/results", "definitionoptions": [ "actionname", "apientrypoint" ], "definitionoptionstranslatable": [ ] Jahia Solutions Group SA Page 9 / 72

10 ], "missinglanguages": null, "existinglanguages": { "en": "English", "progressbar": null, "callbacks": null, "displayablename": "architecture", "layoutjson": "{\"active\":false,\"layoutempty \":true,\"steps\":[{\"rows\":[],\"inputpositionmanagement\":{\"colindex\":null,\" rowindex\":null,\"activeinputfieldname \":null,\"activeinputexists\":false,\"inputmovementhistory\":[]]", "token": null, "trackuser": true, "callbackname": null, "displaycaptcha": true, "theme": null The structure is the same as in V1 a form with its metadata and an array of steps and another array of actions. Each steps contains an array of inputs with their validations and logics. 2.2 REST API The API is defined with JAX-RS, each entry point is managing certain parts of the application. The 4 main entry points are /formfactory/builder: all the sub resources for form creation/management /formfactory/settings: all the sub resources for form factory settings /formfactory/live: all the sub resources for form rendering/submission /formfactory/results: all the sub resources to load/analyze the submissions 2.3 OSGI/EXTENDABILITY Once Form Factory is deployed on your platform it will react upon every module deployment and scan their definition file, looking for node types specific to Form Factory. With V2 there no need anymore to create complex structure in the repository.xml file of your module. To declare a new input, you just declare the type in the definition file, then you create a WZD view (it s a file following a specific DSL in groovy to ease the creation of extensions for Form Factory). Example of a WZD file, from Input Text definition: Jahia Solutions Group SA Page 10 / 72

11 input { label "Text input" template "<ff-input-text></ff-input-text>" wizard "<ff-input-text view-type='designview'></ff-input-text>" supportedvalidationtypes "required", "equal", "length", "number", "regex" supportedlogictypes "valid", "input" properties { inputsize "input-md" propertiesi18n { helptext "Help" placeholder "Text input" An input like this one, will need a few other files to be working with Form Factory Jahia Solutions Group SA Page 11 / 72

12 3 CLIENT SIDE ARCHITECTURE With the switch to AngularJS, we have decided that each element of Form Factory 2 will be an AngularJS directive. This means that for each input/action/validation/logic/etc. you might have to code a JS file and if needed some JSP s. Form Factory 2 will aggregate all those JS files inside only one JS file so that all the application can be loaded with as less requests as possible. All the resource bundle from your module are going to be aggregated together and merge in a dictionary available in the builder so that you can use them in JS without worrying about how to load them across modules. This structure has allowed us to have custom templates for each input either for rendering or for editing. The panels are no more auto-generated but now you design them the way you want. The build system of Form Factory is doing the same, upon building we aggregate all the JS libraries we are using into one file (_ff2.js)., we do the same for our AngularJS application, we aggregate each components in there own JS file (ff-core.js, ff-builder.js, ff-rendering.js, ffsettings.js). We are using NPM, Bower and Grunt in conjunction with maven. Here is what a typical input structure will look like: As you can see we need 4 files to define a new input. Actions and validations will need even less files (it is possible to declare a new action with just a wzd file) Jahia Solutions Group SA Page 12 / 72

13 The wzd file is the properties of your input (label, properties, i18n properties, validations, logics, etc.) The directive view is the AngularJS directive defining how and which template to load and if needed some specific behavior. Then the default view is used to render the input in the builder/preview/live mode, this is the view your visitor will see when they fill the form. And last view is the designview which will be visible by your form designer when they create/modify a form and update an input. The builder is build as a Single Application Page (SAP) every redirection is done internally using AngularJS UI-Router. The main routes are the library, the builder, and the translation mode. angular.module('formfactory').config(function(contextualdata, $stateprovider, $urlrouterprovider) { $stateprovider.state('library', { url: '/library', templateurl: ).state('builder', { url: '/builder', template: '<ff-controller>', params: { ).state('translator', { url: '/translator', template: '<ff-form-translator>', params: { );, ['contextualdata', '$stateprovider', '$urlrouterprovider']); On the preview/live side each form is bootstrapped individually so that they do not collide on the same page. There is no routing on the preview/live side, we load the whole form at once from the REST API and then navigate between all the steps, until submission. The module in preview/live is much lighter and with less dependencies than in the builder side. Live module declaration: Jahia Solutions Group SA Page 13 / 72

14 ff.app = angular.module('formfactory', ['i18n', 'formfactory.validation', 'formfactory.logic', 'ngfileupload', 'checklist-model', 'formfactory.commonusefactory', 'formfactory.templateresolver', 'ui.bootstrap', 'formfactory.datafactory', 'vcrecaptcha']); Builder module declaration: angular.module('formfactory', ['ui.router', 'formfactory.datafactory', 'datatables', 'datatables.bootstrap', 'i18n', 'ui.bootstrap', 'ui.bootstrap.tooltip', 'formfactory.commonusefactory', 'ngresource', 'formfactory.downloadzipfactory', 'formfactory.updaterfactory', 'checklist-model', 'uiswitch', 'formfactory.templateresolver', 'toaster', 'nganimate'], function ($uibtooltipprovider) { $uibtooltipprovider.options({ placement: 'bottom', popupdelay: 200, popupclosedelay: 0, appendtobody: true ); ); Jahia Solutions Group SA Page 14 / 72

15 4 LIBRARY The library is the main entry point to your form creation and lifecycle management. Users need to be part of the role Form Factory Manager, Form Factory Editor or Form Factory Reviewer to access the library. 4.1 CREATION When you want to create a new form we validate that there is no form existing with the same name already. The UI is calling the entry point: /formfactory/builder/checkformnameavailability/{language If name is available and valid then upon click we route you to the builder with a predefined form composed of one input text and one action ( Save To JCR ). 4.2 MANAGEMENT Once you have created a form and saved it in the builder, when you are coming back to the library you will see it in the lift of forms you can manage Jahia Solutions Group SA Page 15 / 72

16 You can easily modify the form, or by expanding the menu you have access to some other actions like publishing the form, deleting it. There is a shortcut to go directly to the metadata edition, this will route you the builder and open up the metadata side panel automatically Use as template This function will create a virtual copy of the form with its new name and then you can edit/save it. If you are working with multiple languages it will copy only the current language Duplicate On the other side duplicate is here to help you create an exact copy of an existing form, by duplicating it on the server side, meaning that as soon as you duplicate the form this one is saved on the server. The interesting behavior of duplicate is that it allows you to duplicate a form that has been created in English for say into French and then start modifying it in French. The duplicate process will switch the building language of your form to your current one. This way you can duplicate a form and modify its structure in another language. 4.3 IMPORT/EXPORT FF 2 allows you to export one or multiple form(s) at the same time. If you export multiple forms, we are aggregating all the zip in a parent zip file. You can then import this/those form(s) inside another platform. The import/export is otherwise using the usual archive format of DXM import/export services Jahia Solutions Group SA Page 16 / 72

17 5 BUILDER The form building is with the submission analysis the main components of Form Factory. The building process can be tear down to multiple phases/functionalities. We are going to go through them one by one. 5.1 INPUTS Inputs are the heart of your forms, the builder allows you to select which inputs to add to your form. An input is comprised of multiple sub elements: Node type definition WZD file to declare the properties of this input AngularJS directive to define the behavior of this input and how to load the different template A default template for rendering in preview/live of this input A designview to edit the defined properties in the builder Definition example from country selection: [fcnt:countrylistdefinition] > jnt:content, fcmix:definition, mix:title, jmix:droppablecontent, jmix:hiddentype - country (string, choicelist[country, sort]) Jahia Solutions Group SA Page 17 / 72

18 //Here we are declaring a fake country property at the cnd level so that we can use DXM choicelist //initializer capabilities WZD file allows to define all the properties of your input, from the same country selection example: select { label "Select Country" template "<ff-select-country></ff-select-country>" wizard "<ff-select-country view-type='designview'></ff-select-country>" supportedvalidationtypes "required" supportedlogictypes "valid", "country" properties { inputsize "input-md" topselections { values "US", "FR" propertiesi18n { helptext "Help" placeholder "Select country" In this file you are defining the template you want to use for the default view and for the wizard. See the appendix for a more detailed description of this WZD format. Then you list the validation and logic rules that this input support. After that you need to list all your properties, there is non I18N properties and I18N properties. The I18N properties are the only one that can be edited in translation mode. Form Factory is using the label property of you WZD file to create the node, the node name is the label in lowercase and with the whitespaces hyphenated. So that Select Country become select-country. See how the node name is referenced in the next file (the directive to resolve the different views from DXM). The AngularJS directive is the one defining the behavior of your input when the user interacts with it: <jcr:propertyinitializers var="countries" nodetype="fcnt:countrylistdefinition" name="country"/> angular.module('formfactory').directive('ffselectcountry', ['$log', 'fftemplateresolver', function ($log, fftemplateresolver) { var directive = { Jahia Solutions Group SA Page 18 / 72

19 restrict: 'E', require: ['^ffcontroller'], templateurl: function(el, attrs) { return fftemplateresolver.resolvetemplatepath('${formfactory:addformfactorymodulepath('/ form-factory-definitions/select-country', rendercontext)', attrs.viewtype);, link: linkfunc ; return directive; function linkfunc(scope, el, attr, ctrl) { var countrylist = [ <c:foreach items="${countries" var="country" varstatus="s"> { country: { key: '${country.value.string', name: '${functions:escapejavascript(country.displayname)', renderername: 'country' <c:if test="${not s.last">, </c:if> </c:foreach> ]; ]); In this directive we are initializing the list of country from DXM country initializer, this way we do not need to get the country list from another service than DXM, but it will be possible to do some asynchronous request to an external service to get the list of countries. We then build a JavaScript structure to use as a source for our AngularJS dropdown list. The directive template is calculated upon runtime depending on your context fftemplateresolver.resolvetemplatepath, but the view itself is rendered once and only, for the builder and for the live mode, per site and per language the results are stored in a JS file in digital-factory-data/generated-resources, if you are in development mode then this file is generated every time: Jahia Solutions Group SA Page 19 / 72

20 This means that calling the initializer is done only once for everybody, whereas if we were using an external services it will called for every user, so depending on the type of data each solution as its benefits. Now the UI part, the default view, this is the one your users will see when they submit the form, or when they build it: Here is the code for this input: <div class="form-group" ng-class="{'has-error': form[input.name].$invalid&&form.$dirty" ng-show="resolvelogic()"> <label class="col-sm-2 control-label"> {{input.label </label> <div class="col-sm-10"> <select name="{{input.name" class="form-control" ng-model="input.value" ng-required="isrequired()" ng-options="country as country.country.name for country in countries" ng-disabled="readonly" ff-validations ff-logic> <option value="">{{input.placeholder</option> </select> <span class="help-block" ng-show="input.helptext!= undefined"> {{input.helptext </span> <span class="help-block" ng-repeat="(validationname, validation) in input.validations" ng-show="form[input.name].$error[(validationname normalize)]&&form.$dirty"> {{validation.message Jahia Solutions Group SA Page 20 / 72

21 </span> </div> </div> When AngularJS is compiling this template, you will have access to the form controller form and to the current input itself input. The ng-show="resolvelogic()" instruction mean that we want to display this div only if the logic rules are true (works only in live/preview mode, will do nothing in builder mode). The ng-class="{'has-error': form[input.name].$invalid&&form.$dirty" will apply Bootstrap 3 error classes on this div if the field is invalid and if the form has been started by the user. On your input itself you need to map the model to input.value, and add the directives ff-validations and ff-logic if you want to have access and apply all the logic/validations rules defined on your input by the form designer. The wizard view: Jahia Solutions Group SA Page 21 / 72

22 is defined by a JSP view like this one: <div class="row"> <div class="col-md-12"> <div class="row" ng-if="!intranslatemode"> <div class="col-md-12"> <label> <span message-key="ff.label.changeinputfieldname"></span> </label> <input class="form-control" ng-model="input.name"/> </div> </div> <br/> <label> <span message-key="ff.label.changelabel"></span> </label> <input class="form-control" ng-model="input.label"/> <br/> <label> <span message-key="ff.label.changeplaceholder"></span> </label> <input type="text" class="form-control" ng-model="input.placeholder"/> <br/> <label> <span message-key="ff.label.changehelptext"></span> </label> Jahia Solutions Group SA Page 22 / 72

23 <input type="text" class="form-control" ng-model="input.helptext"/> <br/> <ff-country-top-selection countries="countries" top-selections="input.topselections" ng-if="!intranslatemode"> </ff-country-top-selection> </div> </div> Here again we inject some object in the scope of your directive, so you have access to your current input object input, there is also a flag that is very useful: intranslatemode will be true during translation, should be used on every non I18N property to avoid changing it. In the wizard it is possible to use other directives to have complex input and very helpful wizard. In this example we are using a dedicated directive to allow to select a list of countries that will appear on top of the list of countries instead of having them all sorted alphabetically. <ff-country-top-selection countries="countries" top-selections="input.topselections" ng-if="!intranslatemode"> </ff-country-top-selection> 5.2 ACTIONS Actions are a much simpler element for Form Factory. The actions are standard DXM actions, to use a DXM action in Form Factory you need to declare a specific node type, a WZD file and an AngularJS directive. You can also but it is not mandatory have a wizard view for your action (if you need to setup some properties for the action). List of files for declaring a working action: Node type definition WZD file to declare the properties of this input AngularJS directive to define the behavior of this action and how to load the different template An optional wizard view to edit the defined properties in the builder Jahia Solutions Group SA Page 23 / 72

24 And of course a Java class (the action is found by its action name, so it is possible to map easily any available action to be used inside Form Factory) Here is the example from the core action Redirect To URL, first the definition: [fcnt:redirecttourlaction] > jnt:content, fcmix:action, mix:title, jmix:droppablecontent, jmix:hiddentype now the WZD file: action { label "Redirect To Url" wizard "<ff-redirect-to-url view-type='designview'></ff-redirect-to-url>" properties { actionname "redirecttourl" propertiesi18n { redirectto "" then the directive: (function () { 'use strict'; var redirecttourl = function($log, $compile, contextualdata, ffdatafactory, fftemplateresolver) { var directive = { restrict: 'E', templateurl: function(el, attrs) { return fftemplateresolver.resolvetemplatepath('${formfactory:addformfactorymodulepath('/ form-factory-actions/redirect-to-url', rendercontext)', attrs.viewtype);, link: linkfunc ; return directive; Jahia Solutions Group SA Page 24 / 72

25 ; function linkfunc(scope, el, attr) { angular.module('formfactory').directive('ffredirecttourl', ['$log', '$compile', 'contextualdata', 'ffdatafactory', 'fftemplateresolver', redirecttourl]); )(); Jahia Solutions Group SA Page 25 / 72

26 And finally the wizard view: <div class="side-panel-body-content"> <label messagekey="fcnt_redirecttourlaction.designview.label.redirectto"></label> <input type="text" class="form-control" ng-model="action.redirectto"> </div> 5.3 STEPS Steps are really only managed by the designer of the form. There is no specific code associated to them. The live controller enforce that all steps are valid before allowing to go to the next one or to submit the form Jahia Solutions Group SA Page 26 / 72

27 5.4 VALIDATIONS Validations are simple JavaScript function receiving the new and the previous value of the field they are validating; each field can have multiple validation active at the same time. This means that contrary to inputs or actions, validations do not always need a specific directive, in fact if they need a directive it will be for their wizard view, to achieve more complex scenarios. So at minima a validation need: A node type in the CND file A WZD file to define its properties A JavaScript file for the rule itself (loaded only in live/preview mode) A view for the wizard (validation have no views in live/preview mode) use in the builder Optionally they can have an associated AngularJS directive to allow more complex input in the builder Example code from the validation rule, this rule ensure that the input text is matching a specified regex ff.validationrules. = function(rule, scope, el, attr, ctrls) { 'use strict'; var model = ctrls[1]; //Regexp taken from var regexp = /^[A-Z0-9._%+-]{1,64@(?:[A-Z0-9-]{1,63\.){1,125[A-Z]{2,63$/i; return function(modelvalue, viewvalue) { return model.$isempty(viewvalue) regexp.test(viewvalue); ; Jahia Solutions Group SA Page 27 / 72

28 ; When Form Factory render an input it is calling every validation defined on it and register the returned function in the ngmodel.$validators array of the AngularJS model, this will automatically ensure that the whole AngularJS form controller behave as expected from AngularJS point of view. Also this validation is a standard view of DXM it is easy to override it by redefining the exact same view in a module with a higher priority for rendering. This way you can easily override all your validation for a specific site by deploying another module. No need to tell your users to use the regex validation with a specific rule, just override the one. 5.5 LOGICS Logics rule are defined exactly the same way as validations, what changes is how they are called in the system. Every time an input value change, Form Factory check if this input is used as a source for logics rule on other inputs in the current active step (as it is the only step where values can change). If if it is then we call every logic rule on the found input, until a rule is failing. If all the rule pass the field is flagged as visible. To declare a logic this is all the files you will need: A node type in the CND file A WZD file to define its properties A JavaScript file for the rule itself (loaded only in live/preview mode) A view for the wizard (validation have no views in live/preview mode) use in the builder Optionally they can have an associated AngularJS directive to allow more complex input in the builder (after the beta) Jahia Solutions Group SA Page 28 / 72

29 Jahia Solutions Group SA Page 29 / 72

30 Example code of if field is valid logic : ff.logicrules.iffieldisvalid = function(rule, scope, el, attr, ctrls) { 'use strict'; var model = ctrls[1]; var ffformcontroller = ctrls[0]; // Try to find the input in a previous step if not found it must be in the current step var searchedinputvalue = ffformcontroller.getpreviousstepinputvalue(rule.fieldname); return function(scope,fieldvalue) { if (_.isundefined(searchedinputvalue) &&!_.isundefined(scope.form[rule.fieldname])) { return scope.form[rule.fieldname].$valid && scope.form[rule.fieldname].ffvisible && scope.form[rule.fieldname].$dirty; else if (!_.isundefined(searchedinputvalue)) { //we have a valid result from a previous step. return (searchedinputvalue!= null); ; Logic and Validation rules are not loaded by the builder. The only way to test those rules is to load the form in Preview or in Live Jahia Solutions Group SA Page 30 / 72

31 5.6 LAYOUT The layout of the form once activated is defined at the form level, and serialized as a JSON property: layoutjson: { "active": true, "layoutempty": true, "steps": [ { "rows": [ { "row": [ { "col": "col-sm-6", "layoutuuid": "510917c2-0ea0-47c6-a717-2aa1d545c303", "offset": "col-sm-offset-0", "moveactive": true, "activeclass": "activecolumn", { "col": "col-sm-6", "layoutuuid": "d2a15b d-a9f2-8869d0bcc32d", "offset": "col-sm-offset-0", "moveactive": false, "activeclass": "inactivecolumn" ] ], "inputpositionmanagement": { "colindex": 0, "rowindex": 0, "activeinputfieldname": "510917c2-0ea0-47c6-a717-2aa1d545c303", "activeinputexists": true, "inputmovementhistory": [ { "rowindex": 0, "colindex": 0, "createdcolumn": false ] ] The layout is a structure listing the rows per steps and for each rows the number of cells and if there is an input in the cell. Input that are not dispatched in a cell won t be visible by the user Jahia Solutions Group SA Page 31 / 72

32 Use preview mode to test your layout Jahia Solutions Group SA Page 32 / 72

33 5.7 METADATA As layout, metadata are stored at the form level they contain: the list of languages for this form its title its description CSS class submission message progress bar tracking captcha themes Themes Themes allows user to override the default views of Form Factory for every input, allowing user to switch from our default Bootstrap 3 theme to another one like Material CSS for example. This way you will be able to have forms matching your website theme/css engine. Those themes are just sets of views allowing a quick overhaul of Form Factory forms in your site, not in the builder and not how they behave. Themes are an integrated part of Form Factory so you can have multiple modules defining multiple themes. To declare a theme, you just need to declare a view of fcnt:form and use the same name for all the views you want to overhaul. Once the theme is selected it will be injected into the form as an attribute called view-type, this happening only in live/preview mode, excerpt from form.angular.jsp <div id="formfactory${identifier"> <ff-controller view-type="${currentnode.properties['theme'].string" id="'${identifier'" data-locale="'${currentnode.resolvesite.language'" datashow-form-title="${currentresource.moduleparams.showformtitle"></ff-controller> </div> Jahia Solutions Group SA Page 33 / 72

34 Then we are calling your main entry point form.theme-name.jsp <c:if test="${jcr:isnodetype(currentnode, 'fcmix:formtheme')"> <template:include view="${currentnode.properties['theme'].string" templatetype="html"/> </c:if> This way you can initialize any framework you are using if needed. The theme property is also used in the ffinputformdirective during form rendering. var formcontroller = ffcontrollerctrl[0]; scope.form = formcontroller.getformcontroller(); scope.readonly =!formcontroller.islivemode(); el.append($compile(angular.element(scope.input.template).attr('viewtype',!_.isundefined(formcontroller.currentform.theme) && formcontroller.currentform.theme!== null? formcontroller.currentform.theme : ''))(scope)); Progress Bar Progress Bar are showing information like steps name or percentage of completion along your form. They are composed of a definition, a WZD file, a directive and a template Definition // // Form Center Progress Bar Definition // [fcmix:hasprogressbar] mixin + progressbar (fcmix:progressbar) = fcmix:progressbar [fcmix:progressbar] mixin - template (string) mandatory - wizard (string) mandatory - position (string, choicelist) = "top" mandatory < "top", "bottom", "both" + * (fcnt:definitionoptions) = fcnt:definitionoptions [fcnt:percentprogressbar] > jnt:content, fcmix:progressbar, mix:title, jmix:droppablecontent, jmix:hiddentype The mixin fcmix:hasprogressbar will be applied on the form if there is a progress bar for this form Jahia Solutions Group SA Page 34 / 72

35 The mixin fcmix:progressbar is the mixin your progress bar definition should extend to be found by the system WZD progressbar { label "Percent Progress Bar" template "<ff-percent-progress-bar></ff-percent-progress-bar>" wizard "<ff-percent-progress-bar view-type='designview'></ff-percentprogress-bar>" position "top" Directive angular.module('formfactory').directive('ffpercentprogressbar', ['$log', 'fftemplateresolver', '$filter', function ($log, fftemplateresolver, $filter) { var directive = { restrict: 'E', templateurl: function (el, attrs) { return fftemplateresolver.resolvetemplatepath('${formfactory:addformfactorymodulepath('/ form-factory-progress-bars/percent-progress-bar', rendercontext)', attrs.viewtype);, ; link: linkfunc return directive; function linkfunc(scope, el, attr, ctrl) { scope.roundvalue = function(value) { return $filter('roundvalue')(value); ; ]); View/Template <div class="row"> <div class="col-md-12"> <div class="progress"> <div class="progress-bar progress-bar-success" role="progressbar" Jahia Solutions Group SA Page 35 / 72

36 aria-valuemin="0" aria-valuemax="100" ariavaluenow="{{roundvalue((currentstep+1)/form.steps.length*100)" style="min-width: 2em; width: {{roundvalue((currentstep+1)/form.steps.length*100)%;"> {{roundvalue((currentstep+1)/form.steps.length*100)% </div> </div> </div> </div> Jahia Solutions Group SA Page 36 / 72

37 5.7.3 Captcha Form Factory 2 is using recaptcha from Google instead of the DX captcha by default. This need to be configured by setting up your API key. The integration is done on the client side, there is no server call to google. This integration use Angular ReCaptcha to validate the form or not, as long as the captcha is not validated the submit buttons are not activated. The JS files are loaded if needed in form.angular.jsp and the captcha is displayed on the last step with this code from formdefinition.formview.jsp, here is the code. <div class="row" ng-if="vm.getcaptchakey()!== null && vm.currentform.steps.length-1 === vm.currentstep && vm.currentform.displaycaptcha"> <div class="col-sm-12 text-right"> <div vc-recaptcha theme="'light'" key="vm.getcaptchakey()" oncreate="vm.notifyofcaptchaload()"></div> </div> </div> Tracking The tracking option will save the user IP upon submission or not Jahia Solutions Group SA Page 37 / 72

38 6 PREVIEW/LIVE The preview/live mode allows you to test/submit your form. In preview you will able to validate your validations, logics and layout. Actions can be only tested in live mode. 6.1 RENDERING During the rendering first we bootstrap every form separately. This way you could have different forms on the same page. Once every app has been bootstrapped, we load the form data. We are using Jahia Assets management capabilities so that the JavaScript files are loaded only once, even the one aggregating every element at your disposal Inputs We render every inputs of the current step. For each type of input we request compile the template, by default it means rendering the default view of this input. The HTTP request for the view should happen only once per type as AngularJS should cache the result of the template locally. Then for each input AngularJS will apply the model of the input into its template Validations Validations are executed on every field upon every changes in the model of the current step. So every time the user enters a new data or select a new entry all the fields are validated. When moving between steps, we restore the status of every input/validation upon re-entering, this will flag the form as dirty and touched once again Jahia Solutions Group SA Page 38 / 72

39 6.1.3 Logics Every change in the values of the input will trigger an evaluation of the logic rules on the current step, to show or hide fields depending on the current state of the model. All invisible inputs are considered valid. A field can be required and invisible, as long as it is invisible it will not block the validation of the form, if it become visible then it will block the user to move forward until it fills this input Logic directive and Logic service The logic directive is in charge of listening to the changes of values on the current step and evaluate all the logic rules define on those fields. The directive is in charge of finding the fields values in the previous steps or in the current one, apply all the rules on a field. The Logic service is the repository of rules available, same as the Validation service. In preview/live we load only the rule for Validation and Logic, we do not load any template 6.2 SUBMISSION Reaching the last step, as long as the form is valid, it is possible to submit it. Upon submission the user will submit only the ids of the inputs along with there value, we do not submit the whole model to the server. 6.3 ACTIONS Those are regular DX Actions, by default FF provide 4 actions: Save to JCR: Will save the data submitted in the JCR backend Jahia Solutions Group SA Page 39 / 72

40 Send Will send an to the configured s address, the will contain the data submitted by the user Redirect to Page: Will redirect the user to a specific page after submission Redirect to URL: Will go to another website upon submission All actions are called in the backend whatever their result is. So you will always receive in the response a message from each action. 6.4 CALLBACKS Per form callback One of the new functionality of this version 2, it is now possible to define at the form level which callback function you want to apply once the actions have been called, this will allow to customize the way you handle errors, redirection etc. on a per form basis. Here is an example of a callback that will automatically redirect to the page selected in Redirect to a page action but also display a message to the user and let it choose between waiting or clicking, the callback also detects if there is a Redirect to URL and in that case offer a link to the URL instead of an automatic redirect. angular.module('formfactory').directive('callbacktwo', ['$log', 'fftemplateresolver', '$interval', function ($log, fftemplateresolver, $interval) { var directive = { restrict: 'E', require: ['^ffcontroller'], scope: { actiondata: '=', callback: '&', templateurl: function(el, attrs) { return fftemplateresolver.resolvetemplatepath('${formfactory:addformfactorymodulepath('/ form-factory-callbacks/callback-two', rendercontext)', attrs.viewtype);, link: linkfunction ; return directive; Jahia Solutions Group SA Page 40 / 72

41 function linkfunction(scope, el, attr, ctrl) { scope.url = '#'; scope.page = '#'; scope.secondstoredirect = 5; for (var i in scope.actiondata) { if ('actionname' in scope.actiondata[i] && scope.actiondata[i].actionname[0] === 'redirecttourl') { scope.url = scope.actiondata[i].redirecturl[0]; if ('actionname' in scope.actiondata[i] && scope.actiondata[i].actionname[0] === 'redirecttoapage') { scope.page = scope.actiondata[i].redirecturl[0]; scope.countdown = function() { if (scope.secondstoredirect === 0) { window.location.assign(scope.page); return; scope.secondstoredirect -= 1; ; ]); $interval(scope.countdown, 1000); Jahia Solutions Group SA Page 41 / 72

42 6.4.2 Form Factory API JS callback This type of callback is the one used to integrate Form Factory forms with other systems, they are used in our own products like Marketing Factory or Marketo module. Those integrations work in two steps, first those tools allow a tighter integration with Form Factory for their form mapping functionalities, allowing to map multiple steps form easily to their own sets of fields. Once the mappings are defined those products register themselves as callback for Form Factory, doing so they will receive all the data submitted. <script type="text/javascript"> document.addeventlistener("ffformready", function(e) { var forminfo = e.forminfo; window.ffcallbacks.registercallback(forminfo, testobject.testfunction, testobject); ); var testobject = { testfunction : function(data, forminfo) { var self = this; settimeout(function() { forminfo.notifyformfactoryofcompletion("testfunction");, 3000); </script> Jahia Solutions Group SA Page 42 / 72

43 7 RESULTS The overall architecture of the results analysis as not changed from V1 to V2, this is still the same code, the views have been switched to Bootstrap 3 and all the JavaScript framework have been updated. The form submits are saved in the live Workspace, under the folder named formfactory/results. In all the cases, whatever the destination of the form submitted data, the form metadata are saved in this folder. The actual data are saved in JCR only when the form contain the action Save to JCR. We can see that the Results are fetched from JCR directly by the API which return JSON objects to pages. The structure of the returned JSON Object is : { "status" : <"success" "error">, "code" : <HTML CODE>, "message" : <String Message>, "data" : <Data Object> The results are wrapped in an object under the data key. 7.1 ACTIONS/RESULTS BOUND In the Form Center, the actions have to be mapped to the results display methods to be able to fetch view data from the good source (JCR, Database...). Form center actions bounding is based on three entities: Backend type: A constant to define where the results are saved. API: An API name (this represent how results can be fetched) Mapping view: A file defined for each API/Backend couple that returns the API entry points for each request of the view Jahia Solutions Group SA Page 43 / 72

44 Views: View to display results fetched from a given API to the user. To know which API to map on each action, the form center watch for the ResultsProviderService implementations which map a list of API on a backend type. As each actions declare a Backend type implementing the APIBackendType interface, the org.jahia.modules.formfactory.api.subresources.formresults get the backend type for each action and watch for ResultsProviderService implementation with this backend type, then it gets the corresponding list of API and from there can access all the views of the APIs APIBackendType Interface The interface org.jahia.modules.formfactory.api.apibackendtype is implemented by the action class to declare the Action Backend type. This action Backend type is a String constant that has to be reused in the class that will implement org.jahia.modules.formfactory.api.resultsproviderservice to map the backend to the right API ResultsProviderService Interface The Interface org.jahia.modules.formfactory.api.resultsproviderservice is implemented for each couple Action / API to map an API to a given Backend type. For the action SaveToJCRAction, the class org.jahia.modules.formfactory.impl.savetojcrrawresultsimpl is doing this mapping : public class SaveToJcrRawResultsImpl implements ResultsProviderService public String getapinames() { List<String> APINames = new ArrayList<String>(); APINames.add("rawResults") return public String getbackendtype() { Jahia Solutions Group SA Page 44 / 72

45 return "JCR"; We can see here that the Backend type is the same than the one declared in the SaveToJCRAction class. 7.2 IMPLEMENTATIONS FETCHING The function getviewsbyaction of SaveToJCRResultAPI.java return all the view and the APIs by action. To do so, it gets the list of actions in the formed saved in JCR and from this list it gets all the API by action: //Putting in the map all the views for each [backend,api] couple for (ResultsProviderService providerservice : resultsproviderservices) { String providerbackendtype = providerservice.getbackendtype(); if (providerbackendtype.equals(((apibackendtype) action).getbackendtype())) { List<Map<String, String>> prefixedviews = new ArrayList<Map<String, String>>(); for(string APIName : providerservice.getapinames()){ prefixedviews.addall(prefixviews(providerbackendtype, viewmap.get(apiname))); actionviewmap.put("views", prefixedviews); Then it gets the list of views for each API. Finally, it returns the list of views for each action Views A view is linked to an API because it has to submit to the format of the results returned. To declare this bound, each view name has to contain the API name. A results view is a view of the node submissions (of type fcnt:submissions) and its name has to respect a rule: submissions.<apiname>.<viewname> Jahia Solutions Group SA Page 45 / 72

46 A resource bundle property is used to properly display this view name to a user, this property key has to be defined precisely: fcnt_submissions.viewname.<apiname>.<viewname> for example the the view datatable of the rawresults API will be named: submissions.rawresults.datatable and its property key will be: fcnt_submissions.viewname.rawresults.dashboard API Mapping JSP file The last link between the actions and the API is the JSP file that map the view fetch keys to the API entry points. The different views that displays results call getfetchurl function : //Generate an URL from parameters function getfetchurl(urlparameters) { return APIMethods[urlParameters.APIMethodName](urlParameters); This function takes the following object as parameter: { formid:this.model.formid, APIMethodName:"results_submissiontime", fromdate: this.model.fromdate, todate: this.model.todate The parameter APIMethodName is a constant used to map API entry points thanks to the object APIMethods : { "results":function(parameters){ if(parameters.fromdate!=null && parameters.todate!=null){ return APIURLBase + parameters.formid + "/from/" + parameters.fromdate + "/to/" + parameters.todate + "/results"; else{ Jahia Solutions Group SA Page 46 / 72

47 return APIURLBase + parameters.formid + "/results";, "results_submissiontime":function(parameters){ return APIURLBase + parameters.formid + "/results/submissiontime";, "results_submissionpage":function(parameters){ return APIURLBase + parameters.formid + "/results/submissionpage";, "results_submissionempty":function(parameters){ return APIURLBase + parameters.formid + "/results/submissionempty";, "results_choicelabel":function(parameters){ return APIURLBase + parameters.formid + "/results/choicelabel";, "results_label":function(parameters){ return APIURLBase + parameters.formid+"/results/labels";, "results_choice":function(parameters){ return APIURLBase + parameters.formid+"/results/choice/"+parameters.choiceid;, "total":function(parameters){ return "${url.context/modules/formcenter/results/total/"+parameters.formid;, "lastdays":function(parameters){ return "${url.context/modules/formcenter/results/${rendercontext.uilocale.language/tot allastdays/"+parameters.formid;, "grouptotal":function(parameters){ return "${url.context/modules/formcenter/results/${rendercontext.uilocale.language/gro uptotal/"+parameters.formid; This object map the different String keys to API get URLs. This system make possible: The creation of new view for each API in separated module (by naming the views the right way). The mapping of a Backend type to new API in any separated module (implementing org.jahia.modules.formfactory.resultsproviderservice). The creation of new APIs for a given backend type in any separated module (Implementing the API and org.jahia.modules.formfactory.resultsproviderservice) Jahia Solutions Group SA Page 47 / 72

48 7.3 RESULTS API The results API is developed using JAX-RS, the source of API different function (All HTTP GET methods ) is localized in the org.jahia.modules.formfactory.api.subresources.formresults class. This class uses different Spring injected variables: renderservice: Jahia RenderService used to get views of node submissions repository: jcrsessionfactory used to get current session resultsproviderservices: List of implementations of the interface ResultsProviderService. templatemanagerservice: Jahia TemplateManagerService used to get the actions available on the server. The API class contains a certain number of methods (all HTTP Get) that return JSON object. Some of these methods will always be used even if the form results are not saved in JCR : getviewsbyactions : Returns an object containing the views for each action basing on the existing Form center actions. Example: {<actionname>:{<view1name>:<view1label>, <view2name>:<view2label> [{"views":[{"viewname":<viewname>,"viewlabel":<viewlabel>],"actionname":<actionname >] The view name is composed the following way: <APIName>.<viewName>, so the name of dashboard view of rawresults API will be rawresults.dashboard. The view Label is a resource bundle with a key composed the following way : fcnt_submissions.viewname.<apiname>.<viewname>, so the resource bundle key for the dashboard view of the RawResult API is : fcnt_submissions.viewname.rawresults.dashboard getactionsproviders: Returns the list of actions id in an array Jahia Solutions Group SA Page 48 / 72

49 getformsdetails: Returns in an object the details (metadata) from a given form Views The results section contains multiple pages. The first pages (That we can call results home page) displays the list of forms that have at least one result already saved : The JCR Results API (org.jahia.modules.formfactory.api.subresources.formresults) is called to fill this table. The function getviewsbyactions is called with the API entry point /views to fill the view selection of the Form Display column. The columns Name and Date are filled with the getformsdetails function. This table is displayed using a Backbone view (FormsResultsView) based on a collection (FormsCollection). All the Backbone Views definitions are localized in the main-results.js file. Each table line contains a form that is submitted to the same page. On the page load, if a form and a view have been submitted the form results are displayed in the selected view. The form center comes with the RawResult API and its JCR implementation. The rawresult API contains 3 views : Metadata view The metadata view is made to display only metadata of the submitted results (Source, user and date) and its code is in the submissions.rawresults.metadata.jsp file Jahia Solutions Group SA Page 49 / 72

50 It uses the Backbone view MetadataResultsView which initializes a Datatable fetching backbone model. In each line the submission date value is clickable and display the submitted result in a popover which is defined by the function displaydata of the JSP file Jahia Solutions Group SA Page 50 / 72

51 7.3.3 Datatable view The Datatable view render results in a table managed by Datatables. The Backbone model used is a pageable collection called PageableResults from the framework Backbone.Paginator defined in the results.js file under the collections folder. The view implemented to display this collection is PageableResultsView (from main-results.js). The size of the page is 500 results per page. The view defines a Datatable with unlimited scroll using Scroller datatable extension Jahia Solutions Group SA Page 51 / 72