Aikau Mini Examples - Simple Form

[ddraper]

Introduction

This is one post in a series of short examples of things that can be done using the Aikau framework. The series is not intended to provide complete documentation but simply to show how to solve frequently encountered problems, implement repeating UI patterns, show case how to use existing widgets or how to create new ones.

Real World Use Case

Ultimately most web applications boil down to just being lists and forms (given the REST based nature of HTTP) so it stands to reason that at some point you’re going to need to define a form. It’s quite likely that you want to build in some dynamic behaviour into your forms from simply not allow the user to POST invalid data to changing the state form fields as data is changed.

As well as providing many different form controls (and the means to easily implement complimentary additional controls) Aikau allows you to define complex form behaviour in a declarative way. This example will show a couple of form controls and a fraction of the capabilities to highlight the benefits of the publication/subscription model that Aikau utilises.

Example

In this example we’re going to defined a relatively simple form containing a text box for capturing an e-mail address and a checkbox that controls whether or not that text box is visible.

Define a form

Let’s start by defining the form widget:

var form = {
  name: 'alfresco/forms/Form',
  config: {
    showOkButton: true,
    okButtonLabel: 'Save',
    showCancelButton: false,
    cancelButtonLabel: 'Doesn't Matter',
    okButtonPublishTopic: 'PUBLISH_TOPIC',
    okButtonPublishGlobal: true,
    widgets: []
  }
};
‍‍‍‍‍‍‍‍‍‍‍‍

In actual fact you could omit all of these attributes and Aikau would provide you with some sensible defaults, but for educational purposes I’ve included (almost) all the attributes available.

Define a text box

Now let’s add a basic text box and add it into the form:

var textBox = {
  name: 'alfresco/forms/controls/TextBox',
  config: {
    fieldId: 'EMAIL',
    name: 'email',
    label: 'Contact',
    description: 'Your e-mail address',
    placeHolder: 'e-mail',
    validationConfig: [
      {
        validation: 'regex',
        regex: '^([0-9a-zA-Z]([-.w]*[0-9a-zA-Z])*@([0-9a-zA-Z][-w]*[0-9a-zA-Z].)+[a-zA-Z]{2,9})$',
        errorMessage: 'Valid E-mail Address Required'
      }
    ]
  }
};

form.config.widgets.push(textBox);‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

With the single exception of the “placeHolder” attribute all of the attributes are applicable to any Aikau form control. All form controls inherit from the “alfresco/forms/controls/BaseFormControl” module which defines the structure of form controls (e.g. labels, options, validation, behaviour, etc) it means that form widgets can be easily swapped without needing to re-write the configuration.

It should be relatively obvious what each attribute is doing. There is a short-hand version of defining validation configuration, but this style allows us to define multiple validators (although we’re only using the “regex” validator to check that the data maps to a valid e-mail address pattern).

Define a check box

Now define a checkbox that will control the visibility of the text box:

var checkbox = {
  name: 'alfresco/forms/controls/CheckBox',
  config: {
    fieldId: 'SHOW',
    name: 'showEmail',
    label: 'Show E-mail',
    description: 'Uncheck to hide the e-mail field',
    value: true
  }
};

form.config.widgets.push(checkbox);
‍‍‍‍‍‍‍‍‍‍‍‍

Note that the attributes are the same as before but assigned different values. This time we’re also providing an initial value of true to ensure that the checkbox is initially in the checked state.

Define a visibility rule

Whenever a form control changes value it will publish the change within the scope of the form and other widgets can define rules that trigger updates based on those changes. Let’s update the text box with a rule that controls it’s visibility:

textBox.config.visibilityConfig = {
  initialValue: true,
  rules: [
    {
      targetId: 'SHOW',
      is: [true]
    }
  ]
};

‍‍‍‍‍‍‍‍‍‍

It’s possible to set multiple rules, multiple “is” values (and indeed “isNot” values) to compare against. It is also possible to use the same rule structure for “requirementConfig” (whether or not the field is required) and “disablementConfig” whether or not the field is disabled.

Here we are simple defining a rule that says if the form control with the “fieldId” of “SHOW” is set with the value “true” then this form control should become visible (and should be hidden if it is set to any other value).

Create the page

Finally we need to add our widget definitions into the main page model:

model.jsonModel = {
  widgets: [
    form
  ]
};
‍‍‍‍‍

Example In Action

This is defined in a JavaScript controller for a WebScript mapped to the /formExample URL. When deployed to a Share (or any Surf based Aikau application) this can be accessed by the URL: http://localhost:8081/share/page/dp/ws/formExample

Here are some screenshots of the page. Note how when the e-mail address in invalid the 'Save' button is automatically disabled. When the checkbox is not checked the e-mail address field is hidden.

Download the entire example here.

Download a PDF version of this post here.

[blog_commenter]

[…] i’ve already covered the basics of defining forms I’ll focus on just the last control which is the […]

[blog_commenter]

Hello Dave, bear with me for asking this, but since the 'DojoSelect' misunderstanding (remember? It's me, again! Thanks once again by the way), I thought it might better to ask:

I am trying to use a Form in my project, but I cannot seem to be able to POST: simply put, when I hit the OK button, nothing happens.

I took a look at the Form.js code in Alfresco 4.2.3.3e, and it seems that the '_onOK' function is not getting called, or, to look it the other way around, the OK button created in 'createButtons' doesn't have an 'onClick' property set to call '_onOK'. Am I missing something?



TL;DR: Are Aikau Forms ready to be used in 4.2.3.3e ? If so, how will I be able to make it POST stuff?



thank you again

[ddraper]

@Massimo - to be honest, I can't remember what state the forms code was in when 4.2 was released (because it wasn't used for any features) but it has come along way since then for 5.0.



One of the key things about Aikau though is that all widget communication is de-coupled. When you click the 'OK' button on a form it will publish a payload that contains the form values - there needs to be a widget or service on the page that subscribes to the topic that the form publishes on.



This approach allows us to use the forms code in multiple scenarios because it is not tied to any specific data processing (i.e it doesn't just make an XHR request). The typical pattern would be that a service is on the page that subscribes to the published topic and then makes an XHR request to POST the form value.



The other advantage of this approach is that it allows the service to 'normalise' the data so that it can be used against different REST services. As well as allowing other widgets to 'piggy-back' on the published topic (e.g. for logging or notification, etc).



I hope that all makes sense!

[blog_commenter]

What  'flavor'  are the alfresco regular expressions for validation?

[ddraper]

@stuartonmaui - They run on the browser and are intended to be processed by JavaScript