scalar_ui_formatter

Scalar UI Formatter — Drupal 10/11 Module

A professional Drupal module that integrates [Scalar API Reference](https://scalar.com)
into field formatters, giving you a beautiful, interactive OpenAPI/Swagger documentation

UI inside your Drupal developer portal — without any build tools or npm dependencies.

---

Features

- 10 built-in themes — Default, Moon, Purple, Solarized, Blue Planet, Saturn, Kepler, Mars, Deep Space, and more
- Two layouts — Modern (sidebar navigation) or Classic (accordion)
- Two formatter types — for `link`/`uri`/`string` fields and for `file` fields
- CORS proxy support — Works with remote OpenAPI specs via `proxy.scalar.com` or your own proxy
- CDN or local — Load Scalar from jsDelivr CDN or an offline local bundle
- Inline spec option — Embed the spec content directly in the page (no extra HTTP request)
- Per-field overrides — Every formatter setting can override the site-wide default
- Custom CSS — Inject CSS custom properties into the viewer for brand theming
- Accessible — Semantic markup, ARIA labels, visible loading and error states
- Drupal best practices — Strict typing, service injection, config schema, cache tags

---

Requirements

| Requirement | Version |
|---|---|
| PHP | ≥ 8.1 |
| Drupal | 10.x or 11.x |
| Drupal modules | `field`, `file`, `link` (core) |

No npm, no Composer packages, no build step required for standard CDN usage.

---

Installation

Via Composer (recommended)

composer require drupal/scalar_ui_formatter
drush en scalar_ui_formatter

Manual

1. Download this module and place it in `web/modules/custom/scalar_ui_formatter/`.
2. Enable it: **Extend → Scalar UI Formatter** or `drush en scalar_ui_formatter`.

---

Configuration

Global settings

Navigate to Administration → Configuration → Web Services → Scalar UI Formatter
(`/admin/config/services/scalar-ui-formatter`).

| Setting | Default | Description |
|---|---|---|
| CDN version | `latest` | jsDelivr version string — `latest` or e.g. `1.25.0` |
| Use local library | No | Load Scalar from a local file instead of CDN |
| Local library path | — | Relative path to `standalone.js` if using local mode |
| Proxy URL | `https://proxy.scalar.com` | CORS proxy for remote OpenAPI specs |
| Default theme | `default` | Site-wide theme fallback |
| Default layout | `modern` | Site-wide layout fallback |
| Show sidebar | Yes | Toggle navigation sidebar |
| Hide download button | No | Remove the spec download button |
| Dark mode toggle | No | Show dark/light mode switch |
| Force dark mode | No | Always render in dark mode |

---

Usage

1. Add a field to your content type

Add one of the following field types to any content type:

| Field type | Use case |
|---|---|
| **Link** | Store a URL pointing to a remote or local OpenAPI spec |
| **File** | Upload a `.json` or `.yaml` OpenAPI spec file |
| **String / URI** | Store a raw URL string |

2. Configure the field display

Go to Manage display for your content type and select one of:

- Scalar API Reference — for Link, String, or URI fields
- Scalar API Reference (File) — for File fields

Click the gear icon to configure per-field settings.

3. Use per-field overrides

Every global setting can be overridden per formatter:

Theme: Moon          ← overrides site default
Layout: Classic
Proxy URL: https://my-internal-proxy.example.com
Height: 800px
Custom CSS:
  :root {
    --scalar-color-1: #your-brand-color;
  }

Leave any field blank to inherit the site-wide default.

---

Local / offline Scalar library

For air-gapped environments:

1. Download the Scalar standalone bundle from npm:

   npm pack @scalar/api-reference
   # or
   curl -L https://cdn.jsdelivr.net/npm/@scalar/api-reference/dist/browser/standalone.js \
     -o web/libraries/scalar-api-reference/standalone.js

2. Place the file at e.g. `web/libraries/scalar-api-reference/standalone.js`.
3. In the module settings, enable Use local library and set the path to
`libraries/scalar-api-reference/standalone.js`.

---

Custom CSS theming

Scalar exposes a comprehensive set of CSS custom properties. Use the Custom CSS
formatter setting to brand the reference to your design system:

```css
:root {
  --scalar-color-1: #1a1a2e;
  --scalar-color-accent: #e94560;
  --scalar-background-1: #ffffff;
  --scalar-font: 'Inter', system-ui, sans-serif;
}

```

Find all available variables in the
[Scalar theming documentation](https://scalar.com/products/api-references/themes).

---

Architecture

scalar_ui_formatter/
├── scalar_ui_formatter.info.yml         Module metadata
├── scalar_ui_formatter.module           Hooks: hook_theme, hook_help
├── scalar_ui_formatter.routing.yml      Admin settings route
├── scalar_ui_formatter.links.menu.yml   Admin menu entry
├── scalar_ui_formatter.libraries.yml    CDN + local library definitions
├── scalar_ui_formatter.services.yml     Service container definitions
│
├── config/
│   ├── install/scalar_ui_formatter.settings.yml   Default config
│   └── schema/scalar_ui_formatter.schema.yml      Config schema
│
├── src/
│   ├── ScalarLibraryVersionResolver.php   CDN URL resolution service
│   ├── Form/
│   │   └── ScalarUiFormatterSettingsForm.php   Global admin form
│   └── Plugin/Field/FieldFormatter/
│       ├── ScalarUiFormatterBase.php      Shared formatter base class
│       ├── ScalarUiLinkFormatter.php      Link/string/URI formatter
│       └── ScalarUiFileFormatter.php      File formatter
│
├── templates/
│   └── scalar-ui-formatter.html.twig     Scalar mount HTML
│
├── js/
│   └── scalar_ui_formatter.js            Drupal behavior / Scalar init
│
└── css/
    └── scalar_ui_formatter.css           Wrapper & loading skeleton styles

---

Frequently asked questions

Why does the reference not load?
Open the browser DevTools console. The most common causes are:
- CORS — the remote spec server does not allow cross-origin requests. Enable the proxy URL.
- Invalid spec — run your spec through [editor.scalar.com](https://editor.scalar.com).
- Scalar CDN blocked — switch to a local library copy.

Can I display multiple APIs on one page?
Yes — add multiple values to a multi-value field, or add multiple fields, each with the
Scalar formatter. Each instance is isolated and independently configured.

Does this work with Apigee Kickstart?
Yes — add a Link or File field to any Apigee-related node type and use the Scalar formatter.
This pairs naturally with Apigee API product documentation pages.