Form Hooks and Expressions

On This Page

• Where Hooks Are Set
• Hook Settings
• What an Expression Can Do
• Calling Your Own Web Service
• When a Hook Fails
• Conditions and Custom Error Expressions
• Permissions
• Related

A hook is a small piece of logic you attach to a form, page button, or component. It runs in the browser for the person filling in the form, and it can call a web address, evaluate an expression, or do both. Use hooks to look up information from your own web service, fill in answers automatically, or send the person to a specific page. To show or hide a component based on answers, use a condition in most cases instead of a hook; see Conditions and Custom Error Expressions below.

Where Hooks Are Set

You set all hooks in the form designer. See Web Forms for how to open it.

Where	Label	When it runs
A component's Edit <label> dialog, on the Hooks tab	Initialization Hook	Each time the person enters the page that contains the component
Form Properties › Hooks	Initialization	When the form starts
Form Properties › Hooks	Any Back Transition, Any Next Transition	Each time the person chooses Back or Next
Form Properties › Hooks	Cancel, Save, Submit	When the person chooses Cancel, Save & Return Later, or Submit
A page's Transitions tab › a button's Options	Before Processing Hook	Before that button acts on that page

Form Properties also lists Submit & Create Another, but people filling in a form never see that button.

When the person enters a page, all component hooks on that page run at the same time. When the person chooses a button, that button's Before Processing Hook runs first, and the matching form-wide hook runs after it.

Hook Settings

Setting	Options	Default	Effect
Hook type	None, Expression, Web + Expression	None	Expression evaluates an expression in the browser. Web + Expression calls a web address, then evaluates an expression against the response if you entered one
Method/URI	GET, POST; a web address	POST; empty	The request method and web address. The designer does not check the address
POST Data	Text	Empty	With a POST, the hook sends this text exactly as you typed it. It does not insert answers
Include Rhythm authorization JWT in HTTP header	Ticked or not	Ticked	When ticked, the hook sends the signed-in person's sign-in token with the call, only to secure Rhythm addresses
Expression	An expression	Empty	What the hook does. As you type, the editor shows This expression is valid. or Invalid expression provided for this field: <message>

When you change the hook type to None, or change the method to GET, the settings that disappear still stay with the component. Those hidden settings are saved only after you press Save Changes in the dialog, then Save in the designer header.

What an Expression Can Do

An expression can read the web response as webHookResponse and the form's context as context. It changes the form only by calling functions; Rhythm ignores the value it returns.

• setFormValue sets an answer on the form. For example, if an Expression initialization hook sets a field to an empty value, it clears that field each time the page opens. The field that links a contact's address to an organization address (link_work_address_to_organization) is boolean, so clear it by setting it to false rather than to an empty value.
• On a contact edit form, an initialization hook meant to clear an existing value may not clear some prepopulated fields. This has been seen with certain yes/no custom fields and with link_work_address_to_organization when it is added as a one-off field in a field group.
• setDestinationPageId, setDestinationPageIndex, and setDestinationPageOffset choose where Next or Back goes when you use them in a navigation hook. Each needs a page identifier or index within the same form, so they cannot send the person to a portal or microsite page outside the form. If the page cannot be found, the person stays on the current page.
• A hook on Cancel, Save & Return Later, or Submit can stop that action. If it stops Save, the person sees Unable to save draft; if it stops Cancel or Submit, no message appears.

Because a hook's result can arrive after the page is already showing, the person can use the page while the hook finishes.

Calling Your Own Web Service

This is also the usual way to send real-time updates out of Rhythm for a purchase, membership join or renewal, event registration, or record change. Use this pattern when you need an outbound webhook.

1. Open the component's Edit <label> dialog, or Form Properties › Hooks, and choose Web + Expression.
2. Choose GET or POST in Method/URI, then enter your address. Add POST Data if the service needs it.
3. If the address is not a secure Rhythm address, untick Include Rhythm authorization JWT in HTTP header.
4. In Expression, use webHookResponse to read the reply, for example with setFormValue.
5. Press Save Changes, then Save. Test with Test this form in the forms list.

Before you begin, make sure your web service accepts requests from your portal's web address. If it does not accept those cross-origin requests, the browser blocks the call and the form continues without it.

Warning

Rhythm accepts any web address for a hook. Anything the hook sends to an address outside Rhythm leaves Rhythm's control, so use only services your organization trusts.

Rhythm attaches the sign-in token only when the box is ticked and the address is a secure (https://) address on a Rhythm domain. If you leave the box ticked for any other address, or leave the address empty, the hook and the page it runs on can stop working. The box is ticked by default for every new hook, so check it each time.

Tip

A component left with its hook set to Web + Expression but no address or expression can stop the person from moving to the next page, not just fail quietly. If a page will not advance, check the component's Hooks tab; switching the hook to None and saving clears the block.

When a Hook Fails

• A web call fails or gets no reply: The result is empty. The expression still runs against the empty response, the form continues, and no one sees a message. You usually notice this when a looked-up price or value is missing.
• An expression throws an error: Nothing happens for that hook. The error appears only in the browser's developer console.
• The form's own start hook fails: The form can stay on Initializing form.... Other start-up failures show Unable to initialize form, and reloading is the only recovery.

Rhythm does not log or count hook calls. To troubleshoot, run the form with Test this form, watch the browser's network panel, and check your own service's logs. If a component's hook causes an error, for example on the Success Message component of a completion page after the form is submitted, set that hook's type to None and save to confirm the hook is the cause. The submission itself can still have succeeded even though the completion page shows an error.

When a portal action that runs an abstract workflow errors unexpectedly, open the backing form in the designer and review the component's Hooks configuration; a hook enabled there is a common cause.

The designer cannot run a hook for you. If a component's hook expression is invalid, the designer refuses Save Changes and shows You haven't entered a valid value for On Init.

Conditions and Custom Error Expressions

Two other designer tabs accept expressions, and both read the answers as formValue:

• Conditional Visibility: Select This component is only visible in certain conditions, then choose Rule Set for conditions from lists under Form Data, or choose Expression. If the expression fails, the component stays shown.
• Custom Errors: Set This error occurs when: to An expression is evaluated to be true. If the expression fails, it counts as not true, so no error is shown. A custom error expression written to catch a missing work address has been seen not to raise an error when that address is linked to an organization address and the linked organization address is itself blank.

Conditions can test only the fields of the record the form collects. They cannot test who the person is or what role they hold. The person's browser checks conditions and custom errors to guide them, and the application that saves the record still checks what it receives. To see how these behave on the page, see How a Form Behaves for the Person Filling It In.

Permissions

You need the application's permission to manage its forms before you can open the designer. The hook, condition, and custom error tabs do not ask for any further permission. Portal members cannot change a form. After you save, the changes reach everyone who opens the form.

Related

• Web Forms: Learn about the rest of the designer.
• Rules and Expressions Explained: See how rules and expressions work elsewhere in Rhythm.