npm package: @keepeek/keepicker-react
Description: ## Steps to use the Keepicker.
Latest version: 1.23.0

# Integration.

## Steps to use the Keepicker.

### Import the JavaScript file registering kpk-keepicker web component:

```html
<head>
  <script
    async
    src="https://cdn.jsdelivr.net/npm/@keepeek/keepicker-react@1/dist/index.js"
  ></script>
</head>
```

### Add the web component tag in the DOM:

```html
<body>
  <kpk-keepicker
    id="keepicker"
    keycloak-client-id="XXX"
    api-endpoint="XXX"
    data-locale="FR"
    ui-locale="FR"
  ></kpk-keepicker>
</body>
```

### Add a callback that will be triggered when selecting an asset:

```html
<script>
  document
    .querySelector("#keepicker")
    .addEventListener("kpk-insert", (event) => {
      console.log(event.detail);
    });
  document
    .querySelector("#keepicker")
    .addEventListener("kpk-insert-link", (event) => {
      console.log(event.detail);
    });
</script>
```

### Use the events to insert content

Keepicker events are triggered for all asset types: pictures, videos, audio files, documents and other assets. Below are some examples of event content.

#### Event for a picture

`kpk-insert` event detail will contain the following JSON content for a picture:

```json
{
  "element": {
    "id": 123,
    "title": {
      "id": "title",
      "type": "TEXT",
      "name": "Title",
      "value": "Media title"
    },
    "originalFileName": "123.jpg",
    "previewUrl": "https://keepeek.com/previewUrl.jpg",
    "fields": [
      {
        "id": "title",
        "type": "TEXT",
        "name": "Title",
        "value": "Media title"
      },
      { "id": "...", "type": "...", "name": "...", "value": "..." }
    ],
    "permalinks": [
      {
        "title": "whr",
        "description": "...",
        "url": "https://keepeek.com/permanentPreviewUrl.jpg"
      },
      {
        "title": "...",
        "description": "...",
        "url": "..."
      }
    ],
    "imagesServiceUrl": "kpk://dynameek-kpk/1200/bwb6bw8xrm.jpg",
    "imagesServicePermalinks": "kpkp://dynameek-kpk/1200/g9g0wtj8ky.jpg",
    "...": "..."
  }
}
```

To get a picture, use the following code:

```js
const url = event.detail.element.permalinks.find(
  (permalink) => permalink.title === "whr",
)?.url;
```

#### Event for a video

`kpk-insert` event detail will contain the following JSON content for a video:

```json
{
  "element": {
    "id": 123,
    "title": {
      "id": "title",
      "type": "TEXT",
      "name": "Title",
      "value": "Media title"
    },
    "previewUrl": "https://keepeek.com/previewUrl.jpg",
    "fields": [
      {
        "id": "title",
        "type": "TEXT",
        "name": "Title",
        "value": "Media title"
      },
      {
        "id": "...",
        "type": "...",
        "name": "...",
        "value": "..."
      }
    ],
    "mediaType": "video/mp4",
    "permalinks": [
      {
        "title": "preview",
        "description": "...",
        "url": "https://keepeek.com/permanentPreviewVideo.mp4"
      },
      {
        "title": "...",
        "description": "...",
        "url": "..."
      }
    ],
    "...": "..."
  }
}
```

To get preview video, use the following code:

```js
const url = event.detail.element.permalinks.find(
  (permalink) => permalink.title === "preview",
)?.url;
```

#### Event for a generated picture

`kpk-insert-link` event detail will contain the following JSON content for a generated picture:

```json
{
  "element": {
    "id": 123,
    "title": {
      "id": "title",
      "type": "TEXT",
      "name": "Title",
      "value": "Media title"
    },
    "fields": [
      {
        "id": "title",
        "type": "TEXT",
        "name": "Title",
        "value": "Media title"
      },
      {
        "id": "...",
        "type": "...",
        "name": "...",
        "value": "..."
      }
    ],
    "permalinks": [
      {
        "title": "...",
        "description": "...",
        "url": "..."
      }
    ],
    "imagesServiceUrl": "kpk://dynameek-kpk/1200/bwb6bw8xrm.jpg",
    "imagesServicePermalinks": "kpkp://dynameek-kpk/1200/b9g0wtj8ky.jpg",
    "...": "..."
  },
  "link": "https://keepeek.com/generatedPictureUrl.jpg"
}
```

In this example, the `imagesServiceUrl` and `imagesServicePermalinks` keys contain the picture URLs used to call the Dynameek service. `imagesServiceUrl` is used to target the current picture version, while `imagesServicePermalinks` always points to the last picture version.

To get generated picture, use the following code:

```js
const url = event.detail.link;
```

## Examples

### React

```jsx
function App() {
  const ref = useRef();

  useEffect(() => {
    if (ref && ref.current) {
      const currentRef = ref.current;
      const handleInsert = (event) => console.log(event.detail.element);
      currentRef.addEventListener("kpk-insert", handleInsert);
      return () => {
        currentRef.removeEventListener("kpk-insert", handleInsert);
      };
    }
  }, []);
  return (
    <div className="App">
      <kpk-keepicker
        ref={ref}
        keycloak-client-id="XXX"
        api-endpoint="XXX"
        data-locale="FR"
        ui-locale="FR"
      ></kpk-keepicker>
    </div>
  );
}
```

### Drupal form

To integrate component in a form, add a container:

```jsx
$form['container']['picker'] = [
  '#type' => 'container',
  '#attributes' => array('id'=>'kpk-keepicker-container'),
];
```

Add a behaviour to mount web component:

```jsx
Drupal.behaviors.addKeepickerWebComponentMarkup = {
  attach: function (context) {
    if (context.id === "node-article-edit-form") {
      document.querySelector("#kpk-keepicker-container").innerHTML =
        '<kpk-keepicker id="keepicker" keycloak-client-id="XXX" api-endpoint="XXX" data-locale="FR" ui-locale="FR"></kpk-keepicker>';
      document
        .querySelector("#keepicker")
        .addEventListener("kpk-insert", (event) => {
          document.querySelector(".keepicker-url").value =
            event.detail.element.previewUrl;
        });
    }
  },
};
```

## List of attributes

| Name               | Mandatory | Type   | Default value               | Description                                                                                       |
| ------------------ | --------- | ------ | --------------------------- | ------------------------------------------------------------------------------------------------- |
| api-endpoint       | no        | String |                             | API Endpoint<br/>If not provided, the user will need to enter the Keepeek instance URL to connect |
| keycloak-client-id | no        | String | Default Keepicker Client ID | Keycloak Client ID                                                                                |
| keycloak-idp       | no        | String | FR                          | Keycloak IDP to add a SSO button                                                                  |
| data-locale        | no        | String | FR                          | Data locale                                                                                       |
| ui-locale          | no        | String | FR                          | Interface locale                                                                                  |

## List of events

| Name            | Description                                        |
| --------------- | -------------------------------------------------- |
| kpk-insert      | Event dispached when inserting one element         |
| kpk-insert-link | Event dispached when inserting a generated picture |