Participating in the Form Lifecycle

It is possible to participate in the lifecycle of the form. See Form Lifecycle and Events for more details.

Fetching Additional Variables

When loading the form, the values of all variables used in the form are fetched from the backend. This means that the form SDK only fetches those variables which are actually used in the form. The most convenient way to use a variable is the cam-variable-name directive. However, there are some situations where directive-based usage is inconvenient. In such situations it is useful to declare additional variables programmatically:

<form role="form">

  <div id="my-container"></div>

  <script cam-script type="text/form-script">
    var variableManager = camForm.variableManager;

    camForm.on('form-loaded', function() {
      // this callback is executed *before* the variables are loaded from the server.
      // if we declare a variable here, its value will be fetched as well
      variableManager.fetchVariable('customVariable');
    });

    camForm.on('variables-fetched', function() {
      // this callback is executed *after* the variables have been fetched from the server
      var variableValue = variableManager.variableValue('customVariable');
      $( '#my-container', camForm.formElement).text(variableValue);
    });
  </script>

</form>

Submitting Additional Variables

Similar to fetching additional variables using a script, it is also possible to add additional variables to the submit:

<form role="form">

  <script cam-script type="text/form-script">
    var variableManager = camForm.variableManager;

    camForm.on('submit', function() {
      // this callback is executed when the form is submitted, *before* the submit request to
      // the server is executed

      // creating a new variable will add it to the form submit
      variableManager.createVariable({
        name: 'customVariable',
        type: 'String',
        value: 'Some Value...',
        isDirty: true
      });

    });
  </script>

</form>

Implementing Custom Fields

The following is a small usage example which combines some of the features explained so far. It uses custom JavaScript to implement a custom interaction with a form field which does not use any cam-variable-* directives. It shows how custom scripting can be used for

declaring a variable to be fetched from the backend,
writing the variable’s value to a form field,
reading the value upon submit.

<form role="form">

  <!-- custom control which does not use cam-variable* directives -->
  <input type="text"
         class="form-control"
         id="customField">

  <script cam-script type="text/form-script">
    var variableManager = camForm.variableManager;
    var customField = $('#customField', camForm.formElement);

    camForm.on('form-loaded', function() {
      // fetch the variable 'customVariable'
      variableManager.fetchVariable('customVariable');
    });

    camForm.on('variables-fetched', function() {
      // value has been fetched from the backend
      var value = variableManager.variableValue('customVariable');
      // write the variable value to the form field
      customField.val(value);
    });

    camForm.on('submit', function(evt) {
      var fieldValue = customField.val();
      var backendValue = variableManager.variable('customVariable').value;

      if(fieldValue === backendValue) {
        // prevent submit if value of form field was not changed
        evt.submitPrevented = true;

      } else {
        // set value in variable manager so that it can be sent to backend
        variableManager.variableValue('customVariable', fieldValue);
      }
    });
  </script>

</form>

The above example uses jQuery for interacting with the HTML controls. If you use AngularJS, you can also populate the $scope in the variables-fetched callback and read the values from the $scope in the submit callback:

<form role="form">

<!-- custom control which does not use cam-variable* directives
     but binds to the angular scope -->
<input type="text"
       class="form-control"
       id="customField"
       ng-model="customerId">

<script cam-script type="text/form-script">
  var variableManager = camForm.variableManager;

  $scope.customerId = null;

  camForm.on('form-loaded', function() {
    // fetch the variable 'customVariable'
    variableManager.fetchVariable('customVariable');
  });

  camForm.on('variables-fetched', function() {
    // value has been fetched, bind to $scope.customerId
    $scope.customerId = variableManager.variable('customVariable').value;
  });

  camForm.on('submit', function(evt) {
    // set value in variable manager so that it can be sent to backend
    variableManager.variableValue('customVariable', $scope.customerId);
  });
</script>

</form>

​Fetching Additional Variables

​Submitting Additional Variables

​Implementing Custom Fields

Fetching Additional Variables

Submitting Additional Variables

Implementing Custom Fields