Page tree
Skip to end of metadata
Go to start of metadata

Version

Linked form instances are available in AsdeqForms 6.2.1

Overview

An advanced use case for AsdeqForms is to be able to create new forms from within a form, and to be able to link these forms together, allowing users to open from one linked form to another.

This can be achieved in a flexible fashion with just a small amount of scripting. The form engine exposes three helpful functions for creating and opening linked forms:

FunctionUse
createLinkedForm( callback, clone )Creates a new form using the same definition, and returns a javascript Promise containing the UUID of the new form.
The callback function receives the model of the new form so that it can make changes or additions, then returns the modified model.
Passing a value of true for the clone parameter will cause the new form to inherit all values from the current one, allowing for a quick way to duplicate a form.
createLinkedFormInLibrary( formIdentifier, callback, clone )Creates a new form as per createLinkedForm(), but also accepts a form identifier allowing the new form to be based on a different form definition.
The form identifier can be the form library name or the UUID displayed in the advanced tab of the form configuration page.
Using the UUID is recommended for maximum reliability and portability.
openForm( formUuid )Saves and closes the current form, then opens a form identified by its metadata uuid.

Linked forms

Forms can retain a reference to another form by UUID, which allows a form to open another using form script, but they remain independent. Changes to one form will not change the contents of the other once it has been created, and each form has its own workflow and state.

Tutorial

In this tutorial, two form definitions will be created, called Parent and Child. A new parent form will have a button to create a Child form, when clicked, it will add a permanent link to the new Child, save the parent, then open the child form.

The child form will also have a permanent link to the parent (but a Child form can still be created independently, i.e. without a parent). The same technique can be used to create a Child form with the same form definition as its parent.

The tutorial will also show how to send data from the parent form into the child form, setting the title of the child form based on user entered data from the parent.

 

Form Definition Files

This example covers constructing two forms, Parent Form.afdz and Child Form.afdz. To try the prebuilt forms, download from the link and when creating new forms select "Import from a Form Definition File (.afdz)"


Creating the parent Form

  1. Log in to the Asdeq Server console. The account used to log in must have either the Administrator or Form Administrator role
  2. Click Forms in the navigation bar, then click the + button and create a new form using the default layout, name the form Parent Form
  3. Open the new form, and drag three new controls from the left hand palette: A text input, a button and a paragraph. The text input will be used to provide a title for the child form, the button will trigger creating a child, and the paragraph will display the child form's identifier once it is created
  4. Give each control an appropriate id and title, as well as text for the button. The text input must have the id formtitle

Parent form javascript

  1. Select the button control and expand the Events section at the bottom of the right hand properties menu, then click the Add... button next to onClick. This will create a javascript handler that activates when the button is clicked. Give it a name, for example 'createChildForm'.

     

  2. See below for the contents of the createChildForm() function, followed by a line by line explanation of the script.

 

function createChildForm(context)
{
let parentModel = context.formEngine.model
if (!parentModel.childUuid)
{
context.formEngine.createLinkedFormInLibrary("69f2fa34-226e-446e-907e-e9c08ab3a25b", (childModel) =>
{
// Set the child form title based on the text input value
childModel.setValue('formtitle', parentModel.formtitle)
// Place a reference to the parent in the child form so it can link back
childModel.metadata.parent = parentModel.metadata.uuid
return childModel
}, false).then( (response) =>
{
// Store the child UUID in the parent form. This allows the parent to reopen its child when clicking the button after a child has been created
parentModel.setValue('childUuid', response.uuid)
// Open the child form. This will close and save the parent form, then open the child.
context.formEngine.openForm(response.uuid)
})
}
else
{
context.formEngine.openForm(parentModel.childUuid)
}
}
let parentModel = context.formEngine.model

Here parentModel is the model of the current form, it contains the values of any controls in this form. In this case, the only value will be the formtitle entry from the text input.

 

if (!parentModel.childUuid)

This ensures that only one child form is created per parent. If there is already a child form, the existing child will be opened instead of creating a second one. It is possible to have multiple child forms using a masterdetail control, but for simplicity this example form stores just one child per parent.

 

context.formEngine.createLinkedFormInLibrary("69f2fa34-226e-446e-907e-e9c08ab3a25b", (childModel) => {...}, false)

The createLinkedFormInLibrary function actually does the work of creating the new child form. It has three parameters:

  1. The first parameter is an identifier for the form library. It can be the name of the form (e.g. "Child Form"), but for reliability it is recommended to use the UUID of the form. The form UUID is available in the Advanced tab of the form properties. If importing the form from the supplied .afdz file at the start of this tutorial, the quoted UUID here will be imported as well, otherwise, be sure to set this parameter to match the child form name or UUID.
  2. The second parameter must be a callback function that takes newly created child model, makes any modifications, and returns the model again. You can use this to save information from the parent form into the child.
  3. The last parameter determines whether the child model should clone the contents of the parent. If set to true, childModel will inherit all the control values from its parent form.

Creating a new form of the same type

To make a linked form of the same type as its parent, you can use formEngine.createLinkedForm(callback, clone). This function creates a linked form in the same form library as the parent, without needing the first identifier parameter.

// Set the child form title based on the text input value
childModel.setValue('formtitle', parentModel.formtitle)
// Place a reference to the parent in the child form so it can link back
childModel.metadata.parent = parentModel.metadata.uuid
return childModel

This callback function receives the new child form model, and makes two additions. It sets the child form title based on the text input value, and then stores a reference to the current parent form in the child model. This will allow the child form to link back to the parent.

 

.then( (response) =>
{
// Store the child UUID in the parent form. This allows the parent to reopen its child when clicking the button after a child has been created
parentModel.setValue('childUuid', response.uuid)
// Open the child form. This will close and save the parent form, then open the child.
context.formEngine.openForm(response.uuid)
})

The createLinkedFormInLibrary() function returns a javascript Promise (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises). This callback will run after the child form has been created and saved, it saves the link to the child form in the parent, and then opens the child form.

Parent Form Binding Expressions

At this point the Parent form is fully functional, but there are a couple of improvements that can be made using binding expressions.

  1. Return to the editor layout tab, and select the Child Form Title text input. In the right hand properties panel, click the ... button next to the Readonly property, and enter ${model.childUuid} in the Expression Code tab. This expression prevents changes to the text input once a child form has been created.
  2. Select the paragraph control and enter this expression code for the visible property: ${model.childUuid}. Then double click the paragraph control to open the text editor. Delete the default text and replace it with this binding expression: ${model.childUuid || "Child form identifier"}.
  3. Select the button control, and click the ... button next to the text property and enter this expression code: ${model.childUuid ? "Open child form" : "Create linked child" } which changes the button text when a child form exists.

Creating the child form

The child form is far more straightforward, having only two controls and a single line of javascript.

  1. Create a new form, and open it in the form editor.
  2. Add a button control
  3. Double click the existing title text, and replace it with this expression code: ${model.formtitle || "Child Form"}



  4. Click the form background to access the overall form configuration properties in the right hand panel. Next to the Title property, click the ... button and set the title value to ${model.formtitle}
  5. Select the button control, and expand the Events section at the bottom of the right hand panel. Click the Add... button onClick to add an onclick javascript handler below


Child Form Javascript

function openParentForm( event )
{
event.formEngine.openForm(event.formEngine.model.metadata.parent)   
}

This simple function opens the parent form using the UUID that was saved when the child form was created.

Testing the linked forms

Form editor preview

The form editor Run tab can be useful for testing the layout and behaviour of forms, but it is not able to simulate creating and opening linked forms. To test linked form behaviour, use a device or the AsdeqForms webapp.


To test the parent and child forms:

  1. Open the parent form on a device or in the webapp
  2. Enter some text into the text input and click the Create Child Form Button
  3. A new form will be created and immediately opened, with the title reflecting the text that was just entered. 
  4. Click the Open parent form button to go back to the original form
  5. The Parent form will have the text input in a readonly state, and will display the UUID of the child form in the paragraph control. Clicking the button will reopen the child form.

 


 

 

 

 

 

  • No labels