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.