# Signed contracts

Follow this guide to embed the clickwrap snippet in your application and collect your user's signed contract.

## Required data

Running the code requires this data:

| Data Element | Description |
|  --- | --- |
| enviroment | This field is mandatory and receives two values 'staging' or 'production' as input |
| templateVariant | This field is mandatory only if there are multiple template variants created on the contract, it contains the variant name |
| cwGuid | This is a mandatory element and represents a GUID value that identifies the group to which the contract created in the Namirial Clickwrap web app belongs |
| version | This is a non-mandatory element and gives the possibility to insert a specific version of a contract in your application, if omitted it will return the last active version based on the selected environment. |
| customValidation | This is a non-mandatory element, it accepts 3 parameters browser, namirial, bootstrap if the field is left empty the default value will be set on the browser. |
| messaggeValidation | This is a non-mandatory element and must only be used if you take advantage of the custom validation of the library, which allows you to customize the message to be displayed in case of failure to enter a mandatory contract. |
| CSSclassesList | This is a non-mandatory element and is used to insert a CSS class at the beginning of the contract box |


After these parameters we need to insert a unique id field within our configuration, id that will allow us to know where to redirect the called contract.

## Write your HTML for embedding the clickwrap

The snippet consists of:

- A `<div>` indicating where the contract should be displayed.
- A `<script>` tag containing the import of the `namirial_wrap.js` library and the use of the render method with pre-configured parameters listed in the previous section and which are used to identify your contract


There are 3 mandatory fields for displaying the contract:

- **enviroment**
- **cwGuid**
- **templateVariant** (only if multiple template variants are present on the contract)


It is not necessary to assign a value to the other parameters to retrieve the contract, if you do not want to take advantage of the custom validation or do not want to assign a custom css class to the contract's container, just leave the value blank


```html
<!-- HTML wrapper for rendering -->
<div id="namirial__contract"></div>

<!-- Initialization of the contract snippet -->

<script type="module" >
/*  Javascript library for business logic  */

import {clickWrap} from '{url of the desired environment (see get started page)}';

clickWrap.renderContract({
    enviroment: "staging",
    cwGuid: '798c069b-17e0-4d31-a52f-8b56b674c835',
    version:'',
    templateVariant: 'Default variant',
    customValidation:'browser',
    messageValidation: "Your Custom message",
    CSSclassesList: ['css_class_1','css_class_2','css_class_N']
},
'#namirial__contract');
<script>
```

## Use of the Field Collection

In order to collect the user's contract, it is necessary to enter the ID parameters that correspond to the Field Collections entered during the contract configuration phase and that correspond to the required parameters, secondly it is necessary to intercept the submit event through a Javascript function

This configuration allows the retrieval of the form data through the namirial_wrap.js library and to block the sending of the contract in the event that some of this data has not been entered

The parameters entered will be collected when sending the contract expressed by the user, the data collected will then be available in the contract detail sidebar in the clickwrap dashboard

![field collection](/assets/integration_field_collections.90f7b951b77572f573425a11056c82cfae29265a6a8e5b645dcaaedf2617aafa.b0ae38d6.svg)

## Use of External ID

The External ID is the key that identifies the user who is present on the system that integrates the clickwrap snippet, it is a mandatory field for the purpose of registering the contract

The data used to generate the external ID value may or may not belong to the fields of the form in which the clickwrap is used, there is no uniqueness constraint associated with this field on the namirial_wrap library side, it is highly recommended to integrate dynamic values such as email or guid in order to improve and facilitate any research in our systems through the [API integration](/products/clickwrap/api-integration/get-started)

## Submit event with browser validation

The customValidation parameter of the rendering method just illustrated allows you to take advantage of the custom validation of the contract, if you do not want to take advantage of this option it will be sufficient to write the word "browser" as a parameter or simply leave the field blank

You will first need to select the submit button of the form, where the clickwrap has been placed, through a specific class or an id using the querySelector method and assign a submit event to this button via the Javascript addEventListener method


```js
const submitBtn = document.querySelector("<the submit button of your form>");

const form = document.querySelector("#<id of my form>");
const MyFormSubmitHandler = () => {
  let externalId = "<external id value chosen>";
  clickWrap.sendingcontracts(externalId);
};

submitBtn.addEventListener("click", MyFormSubmitHandler);
```

Once this operation has been carried out, it is necessary to place the sendingcontracts() method of the namirial_wrap library inside the callback function of the addEventListener method

This method takes as input a parameter of type string called, externalID and represents the id of the user who is expressing contract

Having left to the browser the burden of validating the fields of the form in the event that a user has not validated a required field, the submission of the form will be automatically blocked

## Submit event with custom validation

The namirial_wrap library provides two types of validation:

- namirial
- bootstrap


You can choose the type of validation using `bootstrap` or `namirial` as input parameter for the customValidation field.

The `namirial_wrap.js` library will automatically insert two parameters in the form where the arrangement will be rendered:

- The novalidate attribute which disables data checks carried out automatically by the browser
- A different class depending on the validation you have chosen to use:
If you have chosen bootstrap validation, the `.needs-validation` class will be added
If you have chosen namirial validation instead, the `.namirial-form-validation` class will be added


HTML form validation is applied via CSS’s two pseudo-classes, `:invalid` and `:valid`


```html
<!-- HTML wrapper for rendering -->
<div id="namirial__contract"></div>

<!-- Initialization of the contract snippet -->

<script type="module" >
/*  Javascript library for business logic  */

import {clickWrap} from '{url of the desired environment (see get started page)}';

clickWrap.renderContract({
    enviroment: "staging",
    cwGuid: '798c069b-17e0-4d31-a52f-8b56b674c835',
    version:'',
    templateVariant: 'Default variant',
    customValidation:'namirial || bootstrap',
    messageValidation: "Your Custom message",
    CSSclassesList: ['css_class_1','css_class_2','css_class_N']
},
'#namirial__contract');
<script>
```


```html
<form class="needs-validation | namirial-form-validation" novalidate></form>
```

## Demo css integration for custom validation

To use the css classes for custom validation you will need to add the following css's to your style sheet, including the css belonging to the validation you have decided to implement

::: details Namirial css


```css
form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid
  ~ label {
  color: #d46f62;
}

form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid
  ~ label
  span {
  border: 3px solid #d46f62;
}

form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid:focus
  ~ label
  span {
  border: 3px solid #d46f62;
  box-shadow: 0 0 0 0.25rem rgb(212 111 98 / 25%);
}

.invalid-feedback {
  display: none;
  width: 100%;
  margin-top: 0.25rem;
  font-size: 0.875em;
  color: #d46f62;
}

form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  :invalid
  ~ .invalid-feedback {
  display: block;
}

form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  input:valid
  ~ label
  span {
  border: 3px solid #5fb99f;
}

form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  input:valid:focus
  ~ label
  span {
  border: 3px solid #5fb99f;
  box-shadow: 0 0 0 0.25rem rgb(95 185 159 / 25%);
}

form.namirial-validation
  #namirial__click-wrap
  .namirial-cw__field-group
  input:valid
  ~ label
  span::after {
  background-color: #5fb99f;
}
```

:::

::: details Bootstrap css


```css
form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid
  ~ label {
  color: #dc3545;
}

form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid
  ~ label
  span {
  border: 3px solid #dc3545;
}

form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid
  ~ label {
  color: #dc3545;
}

form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:invalid:focus
  ~ label
  span {
  border: 3px solid #dc3545;
  box-shadow: 0 0 0 0.25rem rgb(220 53 69 / 25%);
}

form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:valid
  ~ label
  span {
  border: 3px solid #198754;
}

form.was-validate
  #namirial__click-wrap
  .namirial-cw
  .namirial-cw__field-group
  input:required:valid
  ~ label
  span {
  border: 3px solid #198754 !important;
}

form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:valid:focus
  ~ label
  span {
  border: 3px solid #198754;
  box-shadow: 0 0 0 0.25rem rgb(25 135 84 / 25%);
}

form.was-validated
  #namirial__click-wrap
  .namirial-cw__field-group
  input:valid
  ~ label
  span::after {
  background-color: #198754;
}
```

:::

## Submit event interception with browser validation

By eliminating the browser default validation, it is necessary to integrate a condition within the callback function of the addEventListener method in which to insert the `theTermsOfTheContractRequestedAreAccepted()` method of the library and pass to the method the id entered as a parameter

This function will take care of verifying that the contracts set as mandatory have been correctly validated

In order for the contract to be collected correctly, it will be necessary insert the sendigcontracts method inside the condition previously set


```js
constsubmitBtn = document.querySelector("<the submit button of your form>");

constform = document.querySelector("#<id of my form>");
constMyFormSubmitHandler = () => {
  if (
    clickWrap.theTermsOfTheContractRequestedAreAccepted(
      "#<your clickwrap container id>"
    ) === false
  )
    return;
  letexternalId = "<external id value chosen>";
  clickWrap.sendingSignature(externalId);
};

submitBtn.addEventListener("click", MyFormSubmitHandler);
```

## Custom events to manage errors or recover registered contract

The namirial_wrap.js library provides 3 custom events:

- `namirial-renderContract`: used for managing the rendering of the recovery of the contract to be integrated.
- `namirial-onError`: for handling http and library configuration errors.
- `namirial-onApproved`: used to collect the user's newly registered contract.


The information handled by each of the three events can be retrieved through the event parameter of the addEventListner method, in the object of the method there is the detail key that can be used to retrieve the error or confirmation message or, in the case of the `namirial-renderAgreement` event, the boolean value that indicates the end of the process of retrieving and rendering the arrangement

It is advisable to send the data of your application within the `namirial-onApproved` event, in order to retrieve the contractGroupGuid parameter and to be able to search for the contracts expressed by users through the APIs made available by clickwrap


```js
const form = document.querySelector("#id of my form");

window.addEventListener(
  "namirial-onApproved",
  function (e) {
    // ajax call made to the server
    fetch("your endpoint", {
      method: "POST",
      headers: {
        "Content-Type": "application/json;charset=utf-8",
      },
      //The contract in your form
      body: JSON.stringify(e.detail),
    }).then((res) => res);

    //Sending the form to the server
    form.submit();
  },
  false
);
```


```js
window.addEventListener(
  "namirial-onError",
  function (e) {
    console.log(e.detail);
  },
  false
);
```


```js
window.addEventListener(
  "namirial-onApproved",
  function (e) {
    console.log(e.detail);
  },
  false
);
```