# Editor integration

**Module:** `wow_editor` (optional — requires `wow` + `drupal:ckeditor5`)

The WoW Editor module adds a CKEditor 5 toolbar button that lets content editors search for and insert styled links to WoW game data — items, achievements, creatures, quests, mounts, pets, toys, and titles.

## Enabling the module

1. Enable `wow_editor`:

    ```
    drush en wow_editor
    ```

2. Add the **WoW Link** button to your CKEditor 5 toolbar at **Administration > Configuration > Content authoring > Text formats and editors**. Edit the desired format, drag the **W** button into the toolbar.

3. Configure the text format's **Allowed HTML tags** to include the attributes the link needs:

    ```
    <a href class data-wow-type data-wow-id data-wow-icon>
    ```

    Without these attributes the inserted links will be stripped on save.

## Permission requirements

Users need the **`access wow search`** permission to use the WoW Link toolbar button. Without this permission, the search modal will not return results. The same permission is required for the `/wow/search/import` endpoint used when inserting remote results.

Assign the permission at **Administration > People > Permissions** (`/admin/people/permissions`).

## Using the toolbar button

Click the **W** icon in the CKEditor 5 toolbar. A modal dialog opens with:

- **Type dropdown** — filter by data type (Items, Achievements, Creatures, Quests, Mounts, Pets, Toys, Titles), or search across all types.
- **Search input** — type at least 2 characters. Results appear after a 300ms debounce, querying the `/wow/search` JSON endpoint.
- **Results list** — each result shows an icon (where available), name, type label, and quality color for items. Local results (already imported) and remote results (from the Blizzard Search API, not yet imported) are both shown.
- **Insert / Cancel buttons** — select a result and click Insert to place the link at the cursor position.

### Remote results

When you select a result that came from the Blizzard Search API (not yet in the local database), the editor calls `/wow/search/import` to sync the entity on demand before inserting the link. This ensures the canonical URL resolves immediately.

## What gets inserted

A link with WoW-specific data attributes and CSS classes:

```html
<a href="/wow/item/19019/thunderfury-blessed-blade-of-the-windseeker"
   class="wow-link wow-quality--legendary"
   data-wow-type="items"
   data-wow-id="19019"
   data-wow-icon="https://render.worldofwarcraft.com/...">
  Thunderfury, Blessed Blade of the Windseeker
</a>
```

### Quality colors

Items (and other entity types with quality tiers) get a CSS class reflecting their rarity:

| Quality | Class | Color |
|---|---|---|
| Poor | `wow-quality--poor` | Gray |
| Common | `wow-quality--common` | White |
| Uncommon | `wow-quality--uncommon` | Green |
| Rare | `wow-quality--rare` | Blue |
| Epic | `wow-quality--epic` | Purple |
| Legendary | `wow-quality--legendary` | Orange |

The color definitions live in `quality.css` in the parent `wow` module and are shared across all contexts (editor, frontend, character pages).

### Icons

Icons are rendered via a CSS `::before` pseudo-element. The `data-wow-icon` attribute on the link carries the icon URL. A Drupal behavior (`wow-link.js`) bridges this to a `--wow-icon` CSS custom property at runtime, which the `::before` rule uses as `background-image`.

## Available search types

The types available in the dropdown depend on which submodules are enabled. Each submodule registers a `SearchableDataProvider` plugin:

| Type | Module | Remote search | Canonical page |
|---|---|---|---|
| Items | `wow_item` | Yes (Blizzard Search API) | `/wow/item/{id}/{slug}` |
| Creatures | `wow_creature` | Yes (Blizzard Search API) | `/wow/creature/{id}/{slug}` |
| Achievements | `wow_achievement` | No (local catalog only) | `/wow/achievement/{id}/{slug}` |
| Quests | `wow_quest` | No (local catalog only) | `/wow/quest/{id}/{slug}` |
| Mounts | `wow_mount` | No (local catalog only) | `/wow/mount/{id}/{slug}` |
| Pets | `wow_pet` | No (local catalog only) | `/wow/pet/{id}/{slug}` |
| Toys | `wow_toy` | No (local catalog only) | `/wow/toy/{id}/{slug}` |
| Titles | `wow_title` | No (local catalog only) | `/wow/title/{id}/{slug}` |

"Local catalog only" types require the catalog to be synced first (via drush or the dashboard). Items and creatures support on-demand import from Blizzard's Search API for entities not yet in the local database.

## See also

- [Search providers](../development/search-providers.md) — how the search system works under the hood and how to implement a new provider
- [Blizzard API coverage](../reference/apis.md) — what data is available
