Clearing Aikau Form Fields

[ddraper]

Introduction

This blog post is part of my commitment to work through interesting Aikau development and customization use cases. In this post I'm going to be addressing this question that was raised in relation to clearing form fields. One of the reasons why this question interested me was that it gives me the opportunity to point out a recently added (albeit minor) capability that was added on request from the Community.  An issue was raised on the Aikau GitHub repository pointing out that it was not possible to add additional buttons to a Form that don't include the form value in the published payload when clicked (see the "widgetsAdditionalButtons" configuration attribute).  

In one project I was recently working on we included a "reset" type button into an alfresco/forms/Form instance that contained a pre-defined set of values for each form field and published to the "setValueTopic" of the form. Unfortunately the form module always overrides the configured payload of any button in the "widgetsAdditionalButtons" property without providing any option to disable the override in general / per-button. Such an option is necessary.

Interestingly the request wasn't to just provide a "reset" option (which would have been a perfectly valid request to make) but simply to provide a way in which form buttons could be configured to not include the form value payload. So a JIRA issue was raised, included in a sprint and the solution was delivered as part of release 1.0.81.

It's important to understand that we want to support your use cases and are committed to delivering solutions for them - the main thing is for you to let us know what they are!

Some Forms Background

The forms solution provided by Aikau is one of its key strengths. As well as providing a wide variety of of form controls out of the box it also provides some very powerful capabilities that can be leveraged through a simple declarative model - this Sandbox page will take you through a handful of those capabilities and the Aikau tutorial also provides some excellent examples.

It is possible to set the values of form controls either individually on each control:

{
  name: "alfresco/forms/controls/TextBox", 
  config: {
    fieldId: "FIELD1",
    label: "A TextBox",
    name: "text",
    value: "Some Value"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

...or on the form itself:

{
  name: "alfresco/forms/Form",
  config: {
    okButtonPublishTopic: "MY_TOPIC",
    widgets: [
      {
        name: "alfresco/forms/controls/TextBox", 
        config: {
          fieldId: "FIELD1",
          label: "A TextBox",
          name: "text"
      }
    ],
    value: {
      text: "Some value"
    }
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The value configured for the Form will always override the value configured for the form control.

Additional Buttons

You can configure whether or not you want the "OK" and "Cancel" buttons to be displayed via the "showOkButton" and "showCancelButton" configuration attributes respectively. But if you want to provide additional buttons then you will need to provide them via  "widgetsAdditionalButtons".

{
  name: "alfresco/forms/Form",
  config: {
    okButtonPublishTopic: "MY_TOPIC",
    widgets: [
      {
        name: "alfresco/forms/controls/TextBox", 
        config: {
          fieldId: "FIELD1",
          label: "A TextBox",
          name: "text"
      }
    ],
    widgetsAdditionalButtons: [
      {
        name: "alfresco/buttons/AlfButton",
        config: {
          label: "Extra Button",
          publishTopic: "MY_OTHER_BUTTON"
        }
      }
    ],
    value: {
      text: "Some value"
    }
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

By default this new button will publish the form value as its payload, but if you add the "updatePayload" attribute and configure it to be false then it will just publish whatever payload it is configured with, 

...
widgetsAdditionalButtons: [
  {
    name: "alfresco/buttons/AlfButton",
    config: {
      updatePayload: false,
      label: "Extra Button",
      publishTopic: "MY_OTHER_BUTTON"
      publishPayload: {
        something: "else"
      }
    }
  }
],
...‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Providing a Reset Button

In most cases you're likely to know the value that you want to assign your form... the most likely scenario that I can imagine is that you are retrieving the value from calling a REST API on the Alfresco Repository. If you have this value then you can set it as both the value of the form and the publishPayload of your reset button.

In order for the form to take notice of our reset button we need to ensure that it is configured with a "setValueTopic" attribute that matches the "publishTopic" of the reset button.

var formValue = {
  text: "Some value"
};

var myForm = {
  name: "alfresco/forms/Form",
  config: {
    setValueTopic: "RESET",
    setValueTopicGlobalScope: true,
    okButtonPublishTopic: "MY_TOPIC",
    widgets: [
      {
        name: "alfresco/forms/controls/TextBox", 
        config: {
          fieldId: "FIELD1",
          label: "A TextBox",
          name: "text"
        }
      }
    ],
    widgetsAdditionalButtons: [
      {
        name: "alfresco/buttons/AlfButton",
        config: {
          updatePayload: false,
          label: "Reset",
          publishTopic: "RESET",
          publishGlobal: true,
          publishPayload: formValue
        }
      }
    ],
    value: formValue
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍;‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Bugs, bugs, bugs...

The great thing about doing an exercise like this is that it can help to flush out bugs. Those that are more familiar with Aikau may have noticed that the form is subscribing to the "RESET" topic globally (configured via the "setValueTopicGlobalScope" attribute) and that the button is publishing the value globally (configured via the "publishGlobal" attribute).

This is because in the course of working through this use case I discovered that the "setValueTopic" is subscribed to before the pubSubScope is generated meaning that it will always be subscribed to globally. So I raised a bug report and will fix the problem in the current sprint and the fix will be available from the 1.0.87 release.

Finally...

Having an easy config option for a form to render a reset button is still a perfectly valid request... someone just needs to ask for it !

If you've found this post useful or interesting then it would be great if you could like or share it from the top of the page!