Cortex Form

Cortex Form is a web component.

Registering the custom element

Firstly, the following JavaScript needs to be loaded in order to register the custom element:

<script src="https://form.cortextech.io/index.js"></script>

Once the script is loaded, the custom element <cortex-form> will be available.

Attributes

The <cortex-form> custom element supports the following attributes:

id

Required ID of the form.

client-id

Required ID of the client.

stage

Optional Boolean, if set to true, the web component will talk to the Cortex stage backend.

server

Optional string. If the form was produced in the Cortex USA environment, you need to set server to us.

access-token

Optional string for passing in a Cortex JWT token. It is advised to not use this attribute to pass in the token on the web as it will be observable in the DOM tree.

access-token-cookie-name

Deprecated as it is advised to not store a token in a cookie, but it is implemented for backward compatibility.

Optional, when provided, it will be used to get the token from the specified cookie.

access-token-callback-name

Optional string, when provided, it will be used to get the token from the specified callback function. It is expected that this function is a property of globalThis and will return the token when called. Supports nested properties, e.g. globalThis.myObject.myFunction.

event-tracking-key

Optional string, when provided, it will be used to track the REQUEST event. The event won't be tracked if a key is not provided or if trackingEnabled (a form property) is false.

on-submit

Optional string, when provided, it will be used to find and call a function. It is expected that this function is a property of globalThis. Supports nested properties, e.g. globalThis.myObject.myFunction.

consent

Boolean, which defaults to true. If set to false, the web component will not track any event or set any cookie.

cookie-domain

Optional string, when provided, it will be used to set the cookie domain.

device-id-cookie-name

Optional string, default is cortex_device_id. It will be used to get the device ID from the specified cookie.

device-id-callback-name

Optional string, when provided, it will be used to get the device ID from the specified callback function. It is expected that this function is a property of globalThis and will return the device ID when called. Supports nested properties, e.g. globalThis.myObject.myFunction.

Usage

<cortex-form id="FORM_ID" client-id="CLIENT_ID"></cortex-form>

You will be given a client ID at your initial account setup.

You can get the form ID from:

• The Cortex platform
• The data provided by the form block in an article

Usage example:

<cortex-form id="668d33af0981f25d218f3224" client-id="DEMO"></cortex-form>

If using the Cortex staging environment:

If the form was produced in the Cortex staging environment, stage must be set:

<cortex-form id="FORM_ID" client-id="CLIENT_ID" stage></cortex-form>

Adding an access token

To enable some features, for example, to track responses against a single sign-on account, the access token needs to be passed into the form embed. While it is possible to pass in the token directly or pass in a cookie name as described in the above Attributes section. It is advised to use access-token-callback-name instead:

<script>
  globalThis.myFunctionToGetToken = (context) => {
    return 'ACCESS_TOKEN'
  }
</script>
<cortex-form
  id="FORM_ID"
  client-id="CLIENT_ID"
  access-token-callback-name="myFunctionToGetToken"
></cortex-form>

On submit callback

You can pass in the name of a callback function to be triggered when the ‘Submit’ button is clicked.

The primary use case for this is tracking, i.e. you might create a function that will fire a tracking event tag, although there may be other use cases that can be served via a callback function.

For example, see on-submit in the below, in which you can replace myFunctionOnSubmit with your function name.

<script>
  globalThis.myFunctionOnSubmit = (context) => {
    console.log(context)
  }
</script>
<cortex-form id="FORM_ID" client-id="CLIENT_ID" on-submit="myFunctionOnSubmit"></cortex-form>

Global configuration

You can configure the web component globally by setting properties on globalThis.cortextech object.

globalThis.cortextech = {
  clientId: 'CLIENT_ID',
  accessTokenCallbackName: 'cortextech.myFunctionToGetToken',
  myFunctionToGetToken: (context) => {
    return 'ACCESS_TOKEN'
  },
  onSubmit: 'cortextech.myFunctionOnSubmit',
  myFunctionOnSubmit: (context) => {
    console.log(context)
  }
}

Values set directly on custom element will take precedence over global configuration. The following properties are available to be set globally:

• clientId
• server
• accessTokenCookieName
• accessTokenCallbackName
• eventTrackingKey
• onSubmit
• cookieDomain
• deviceIdCookieName
• deviceIdCallbackName

Obtaining the form ID

Obtaining the form ID from the Cortex platform

The easiest way to get the form ID is as follows:

1. Open the Cortex platform, and navigate to Forms in the left-hand sidebar.
2. Find the form you want to embed from the list of forms, and click the three dots on the right-hand side.
3. Click View embed code. A popup containing the embed code is displayed.

Note that this method returns the entire embed code, including the form ID and an appropriate environment declaration and client ID for this form.

Obtaining the form ID from a form block in an article

When a form block is added to an article, the JSON for that article will include the form ID. For example, in a demo article, the entire form block looks like this:

{
  id: "6e265370-bd4f-4e1e-be6f-4763bb63bb0a",
  contentType: "FORM",
  sponsor: { },
  formId: "668d33af0981f25d218f3224"
}

The website or app can then inherit the form ID from the article and use it to populate the embed code.

Note that, using this method, a content author does not have to add the embed code for each use, they just have to add a form block to their article. This method is recommended for any website powered by the Cortex CMS.

Getting the responses via API

For a full listing of all the API responses, see the Postman articles here.