Using Subforms

Anne Rosebery
Form Developers

Subforms are forms that are included within another form. These forms can be submitted (such as work information on a task) or sections of the form that are shared across many forms so that the section can be managed in one place (such as a requested for section).

Loading a subform

Subforms are loaded with the K.load function. Below is an example of this function.

K.load({
  path: pathURL,
  container: '#subform-div',
  loaded: function(form) { ... },
  created: function(data) { ... },
  updated: function(data) { ... },
  completed: function(data, action) { ... }
});

Options/Callbacks

  • path path to the form (including space, kapp, and form slugs) that will be loaded
  • container CSS selector that specifies where the loaded form should be placed
  • loaded called after the form is loaded and appended to the page, it is passed the following parameters

    • form the Form object representing the loaded form, see Using Kinetic Objects for details
  • created called after the page save/submission results in the successful creation of a new submission, it is passed the following parameters

    • data contains the following properties
    • submission the submission API result, see the REST API documentation for details
    • action contains the following action functions
    • default loads the next displayable page for the embedded submission, note that this is done automatically unless the stop action (below) is called
    • close removes the embedded form from the page
    • stop prevents the default action from being done
  • updated called after each save/submit following creation, it is passed the following parameters

    • data contains the following properties
    • submission the submission API result, see the REST API documentation for details
    • action contains the following action functions
    • default loads the next displayable page for the embedded submission, note that this is done automatically unless the stop action (below) is called
    • close removes the embedded form from the page
    • stop prevents the default action from being done
  • completed called after page submit results in completion of the submission, it is passed the following parameters

    • data contains the following properties
    • submission the submission API result, see the REST API documentation for details
    • action contains the following action functions
    • default loads the confirmation page for the embedded submission, note that this is done automatically unless the stop action (below) is called
    • close removes the embedded form from the page
    • stop prevents the default action from being done
  • unauthorized called when the http request to load the form returns a status code of 401 (indicating the user making the request is not authenticated and the form requires authentication). This callback is not passed any parameters.
  • forbidden called when the http request to load the form returns a status code of 403 (indicating the authenticated user does not have access to submit the form). This callback is not passed any parameters.
  • notFound called when the http request to load the form returns a status code of 404 (indicating that the kapp slug and form slug provided do not match a form). This callback is not passed any parameters.
  • error called when the http request to load the form returns any status code that indicates an error. Note that if one of the status codes mentioned above is returned, this callback will be called in addition to the more specific callback. This callback is not passed any parameters.

Note: Forms used as subform cannot use K functions in custom head content, nor in HTML element scripts. Only use them in events.

Example Paths

When using the default bundle, which defines a function called spaceLocation, this is how you would call a each type of form:

Datastore form path: bundle.spaceLocation() + '/app/datastore/forms/<form-slug>'

Regular form path: bundle.spaceLocation() + '/<kapp-slug>/<form-slug>',

Passing Values

Populating Parameters on Subform

There are two options for setting a parameter on a subform. You can use the loaded function, which will populate the values after the form is loaded, or you can use url paramters, which will populate the values during page rendering (so they will be there during page load.

In the loaded function

Use form.select(...) to populate values upon load (happens AFTER the embedded form actually loads and the onLoad events of the embedded form occur):

Example:

form.select('field[subform field]').value(K('field[parent form field]').value());

As URL Parameters

This is useful when you want to pre-fill values server side (during page rendering). This works for drop down / cascading menus as well! If you want something to prefill, pass it inline this:

K.load({
  path: path + '?values[Field%20Name]=Value%20Here&values[Field%20Name2]=Value%20Here2',
  container: '#subform-div',

Using Parameter through a variable can help you loop through a series of parameters, such as fields on the parent form.

  // Turn paramsInput into formatted/encoded params array as that's what's required by the
  // Kinetic App when passing in values
  var paramsInput = {
      "Task Id": taskId
  };

  var params=[];
  $.each( paramsInput, function( key, value ){
    params.push( "values[" + encodeURIComponent( key ) + "]=" + encodeURIComponent( value ) );
  })

  //Remove null values from params list
  params = params.filter( function(val) { return val.split("=")[1]!=="null" } );

  K.load({
    path: bundle.spaceLocation() + '/services/change-scheduling-utility' + '?' + params.join("&"),

Populating Parameters from the Subform to the Form

This can be done using a watch in the Loaded method. This will keep the value on the main form matching what is set on the subform.

Example:

loaded: function(form) {
    var subform = K.as(form);

    subform('form').$watch('Login Id', function(newVal, oldVal){
      K('field[Requested For ID]').value(newVal)
    })

    subform('form').$watch('Full Name', function(newVal, oldVal){
      K('field[Requested For Name]').value(newVal)
    })
  }

This is setting the fields Requested For ID and Requested for Name on the main form to fields Login Id and Full Name on the subform, respectively.

Code on Subforms

It is important to note that Forms used as subform cannot use K functions in custom head content, nor in HTML element scripts.