SubmitForm is the all purpose function to enter values in a form and then submit the form.

There is an alternate function UpdateForm which performs just the first part, altering the form, and does not submit the result. It has the same syntax, but does not require the submit method to be defined.

A very simple example:

SubmitForm with
  %Submit% value:Save
  %Params% with
    %name% Hammy First
    %country% CA
  end
end

Parameters

Form

This is the predicate→ specifying which form on the page is to be submitted. It should identify the form element.

If it is not specified then the default form on the page will be used -- which means only one form may exist. If more than one form exists you may get an error.

Submit

Submit is the predicate→ which indicates how the form is to be submitted.

value:string is a common form for HTML as the submit buttons use the "value" attribute to display to the user and it is what is submitted to the server.

name:string is also quite common as submit elements can be given names (usually the name attribute of the element, such as a button).

label:string is a more generic alternative which will match the string against the text appearing in the form. If any submittable element contains the text it will be used to submit the form.

If it is omitted the first button will be used. Not specifying a method is discouraged as even slight alterations in the HTML or JavaScript can alter what is the default, and sometimes it simply can't be identified.

Pressing Enter

A special predicate exists to simulate pressing enter on a form. key:enter will work as though the user pressed enter in one of the text fields in the form.

Params

This is a map containing the values of all items in the form which are to be set.

The type of the value will be appropriately mapped to the type of the field in the form.

Multiple Items

If multiple values must be set for an entry with the same name (perhaps either checkboxes or a multiple selection list), then a vector should be used to specify that value.

%Params% with
    %CB_Many% withvector
    b43
    nk004
    nfj44
  end
end

Ordering

If the parameters must be specified in a particular order due to dynamic scripting then an additional parameter must be specified. This is a more convenient option to calling UpdateForm multiple times for each field.

ParamPrecedence is a space separated list of parameter names. The items will be set in the order they appear.

%Params% with
    %country% CA
    %postal% T0K 9WZ
  end
  %ParamPrecedence% country postal

Any items not specified in the ordering will be done in an unspecified order after the other parameters.