# Custom elements

Custom events are *synthetic events* in Javascript that can be dispatched to our SDK.

Use custom events to communicate with our custom elements to wrap your code and handle all logic, analytics and API requests.

* [didomi-container-headless](#didomi-container-headless)
* [didomi-if-not-authenticated](#didomi-if-not-authenticated)
* [didomi-if-authenticated](#didomi-if-authenticated)
* [didomi-auth-headless](#didomi-auth-headless)
* [didomi-consent-asked](#didomi-consent-asked)
* [didomi-consent-receiver](#didomi-consent-receiver)
* [didomi-pending-consent-receiver](#didomi-pending-consent-receiver)
* [didomi-component-content](#didomi-component-content)
* [didomi-entity-content](#didomi-entity-content)

#### didomi-container-headless

Add the custom element `didomi-container-headless` to wrap your widget. This component should wrap all other widget related elements as it contains a boundary intercepting events and communicating with our API.

| Properties | Description      |
| ---------- | ---------------- |
| `id`       | ID of the widget |

```html
<didomi-container-headless id="widgetId">
  // Add your HTML here
</didomi-container-headless>
```

#### didomi-if-not-authenticated

To display content when the end-user is not logged into the Didomi system, add the custom element `didomi-if-not-authenticated`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-if-not-authenticated container-id="widgetId">
	<p> I am displayed when end-user is not authenticated </p>
</didomi-if-not-authenticated>
```

#### didomi-if-authenticated

To display content only when the end-user is logged into the Didomi system, add the custom element `didomi-if-authenticated`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-if-authenticated container-id="widgetId">
  <p> I am displayed when end-user is authenticated </p>
</didomi-if-authenticated>
```

#### didomi-auth-headless

Add the custom element `didomi-auth-headless` to wrap a login form and handle end-user authentication.

To request authentication, you will need to create and dispatch the custom event `didomi:send-authentication`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-auth-headless container-id="widgetId">
  // Add your auth form here
</didomi-auth-headless>
```

This custom element takes care of sending the `authentication.asked` and `authentication.sent` analytic events.

#### didomi-consent-asked

To send `consent.asked` analytics event, add the custom element `didomi-consent-asked`.

Please make sure to only add this component once in your page to avoid sending multiple events.

| Prop           | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-consent-asked container-id="widgetId"></didomi-consent-asked>
```

#### didomi-consent-receiver

To send end-users' choices through our SDK upon click, wrap your entities in the custom element `didomi-consent-receiver`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-consent-receiver container-id="widgetId">
    // Add your input/checkbox/radio... here
</didomi-consent-receiver>
```

To save end-users' choices through our SDK upon clicking, create and dispatch the custom event `didomi:set-consents`.

This custom element takes care of sending the `consent.given` analytic event.

#### didomi-pending-consent-receiver

To store end-users' choices in the application state before saving them, wrap your entities in the custom element `didomi-pending-consent-receiver`, create and dispatch the custom event `didomi:set-pending-consents`.

Within the `didomi-pending-consent-receiver`, you will also need to add a save button, create and dispatch the custom event `didomi:save-pending-consents` to save the consent state in our database.

| Prop           | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-pending-consent-receiver container-id="widgetId">
  // Add your input/checkbox/radio... as well as your save button here
</didomi-consent-receiver>
```

This custom element takes care of sending the `consent.given` analytic event.

#### didomi-component-content

To display a content option of a component of your widget, use the custom element `didomi-component-content`.

| Properties           | Description                                                                                                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `container-id`       | ID of the widget                                                                                                                                                                    |
| `component-id`       | ID of the layout-component                                                                                                                                                          |
| `component-property` | Property of the layout-component. For example `saveButton.text.content` (if it has been edited at the layout-component level) or `icon.src` to get the URL of the preference value. |

```html
<didomi-component-content
    container-id="widgetId"
    component-id="componentId"
    component-property="pathOfProperty"
></didomi-component-content>
```

#### didomi-entity-content

To display an entity of your widget, such as the title or description from a purpose or preference, use the custom element `didomi-component-content`.

| Properties               | Description                                                                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `container-id`           | ID of the widget                                                                                                                                                                             |
| `entity-id`              | ID of the selected purpose, selected preference or preference value. You can easily find them in the Configuration Tree section on the Console.                                              |
| `entity-property`        | This property determines which content of the entity object should be displayed. It can be `name` or `description`.                                                                          |
| `entity-type`            | Specify the type of property. It can be either `purpose`, `preference` or `preference-value`.                                                                                                |
| `with-component-content` | This property is used to determine whether to override the entity content with the layout component one set a widget level, if any (`true`), or to display the entity content (`undefined`). |

```html
<didomi-entity-content
    container-id="widgetId"
    entity-id="entityId"
    entity-property="pathOfProperty"
    entity-type="entityType"
    with-component-content="true"
></didomi-entity-content>
```