@readme

Use the contact form pattern to start a task in Relay when a user outside of Relay submits a contact form.

Setup

Install the extension into your Relay instance.

From the Relay module, use the New high-level folder option to create a new Enquiries folder. In the portal, go to Settings/Folders to locate the new folder, and copy its URL.

Edit the form in Content/Contact form, and on the Advanced tab:

• Set Execute node to the newly-created group.

How to use

Use the URL link on the Start page. When a visitor complete the contact form, you will get a new task and be sent a notification. The visitor will also be emailed a copy of what they entered.

From within the contact form folder, Relay users can submit a contact form themselves using the New enquiry icon. Relay users are not emailed a copy of what they entered, but a Relay notification will be created.

How it works

Enquiry process

The core of the contact form pattern is the Enquiry template. This includes all the components from the Standard standalone collection but excluding the change template component, and with additions:

• Init enquiry which includes Init Enquiry Process. This that sets the request data area to the data property of the incoming init data, which contains the data from the contact form. It also overrides the standard "initPartial" action to set up the task, including creating an event that indicates a new enquiry has been received.
• Enquiry view task which overrides the standard task view step and includes additional progress descriptions which are used to build the next steps text that tells the user what to do when they receive a new enquiry.
• Notify enquiry which extends the standard Notify and overrides the event types that should result in a notification.
• View contact form which includes both View Contact Form Process and View Contact Form Status Rules. This displays the contact form.

Initiating an enquiry

The contact form in the contact area is based on Contact form in the library area. It uses standard Form functionality to execute the enquiry folder when the user submits the form. This is intercepted by the Import Task Process steps which are included into the Enquiries folder group profile using the Import task component. There are two steps in Import Task Process:

• An "enquiry.email_responder" step that creates an email, using the Email Responder Script script.
• An "enquiry.import_task" step that creates a new task, setting the init data to the received contact form data.

An enquiry can also be submitted directly from the enquiries folder. This uses the New enquiry component which uses the standard Start Process Component Script to create a new instance of a task using the Enquiry template. This uses Contact form as the new task confirmation form, and sets up init data the same way as a submitted enquiry. The New enquiry component generates a status rule to show an icon in the enquiry folder to create a new enquiry.

Sub tasks

The user can create sub tasks beneath enquiries, and can create new tasks in the folder. This uses New task which is a copy of the standard component, but with a different reference so it does not impact the standard one, with the step name set to the same as the standard one, and with different options so that it does not generate an icon (which would confuses with the New enquiry icon).

Customization

Changing the form

Edit the library Contact form to include whatever fields you like. The form must include:

• A hidden "redirect" field. If you don't want to pass a redirect when linking to the contact form, set a "value" property on the redirect field to the URL of your thank you page.
• A "name" field. If you are not collecting the responder's name, have a hidden name field that can be used as the task name, e.g. "Survey response".
• An "email" field, if you are using the email responder.

The contact form in the content area that is completed by the visitor inherits from the contact form in the library area. Make sure you edit the library version.

Changing the email

For clarity, this example includes a very simple Email Responder Script. You can amend this script or use a templating approach if you want to make it easy for end users to modify the email.

Setting permissions

Grant execute permission on the contact form to the intended audience. Use "anonymous" to allow anyone to use it, or grant specific permissions to a user group if you intend to use it internally.

Changing the form location and the start and thank you pages

Optionally, move the contact_form from the Content folder to an accessible location in your site. You may want to set the form in an iframe and use CSS in the form definition to hide the standard page structure.

Provide a link to the contact form and in that link include a redirect parameter that identifies the URL of a thank you form. See the start page in the content for an example. Alternatively, modify the form definition and provide the URL of your thank you page as the value of the redirect field.

If you want to use the included start and thank you pages, they will need some editing.

Next steps

Progress descriptions are used to build the next steps section in the task view. You can modify these in Enquiry View Task Process, or override them in the Enquiry view task component.

Changing references

The contact form pattern uses a number of group profile and component references. These are global across a Relay instance and you might need to change these to avoid name clashes, especially if you use the pattern more than once.

• The Enquiries folder group profile uses the reference enquiries.
• Import task uses the reference enquiry.import_task.
• New task uses the reference enquiry.new_task.
• New enquiry uses the reference new_enquiry.

Removing the email

If you don't want to send emails, edit the form in Content/Contact form, and on the Advanced tab:

• Set Execute action to enquiry.import_task

Contact form submission will then skip over the email step and create an enquiry task straight away. You can delete the step to send the emails if you like.

Changing the enquiry process

The enquiry process is based on the standard standalone process. You can change the enquiry process by modifying the components listed in Enquiry and including components that reference your own process.