UX Driver

https://github.com/pentiminax/ux-driver
Admin
UX Driver is a Symfony bundle that integrates Driver.js to render product tours, highlights, and...
Tokens:10,756
Snippets:141
Trust Score:9.6
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure autostart behavior

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/control-and-persistence.mdx

Control whether a Tour or Hint group starts automatically using component attributes or builder methods.

```twig
<twig:Driver:Tour id="welcome" :autostart="true">
    ...
</twig:Driver:Tour>

<twig:Driver:Hints id="help" :autostart="false">
    ...
</twig:Driver:Hints>
```

```twig
{% set tour = create_tour('welcome') %}
{% set hints = create_hints('help') %}

{# A builder Tour always waits: give it a trigger. #}
<button {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>Start tour</button>

{# Hints autostart unless the second argument says otherwise. #}
<div {{ ux_hints(hints, false) }}></div>
```

```php
$tour = $this->tourBuilder->create('welcome');
$hints = $this->hintsBuilder->create('help');
```

--------------------------------

### Install UX Driver via Composer

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Run this command in your terminal to add the package to your Symfony project.

```bash
composer require pentiminax/ux-driver
```

--------------------------------

### Style custom popover class

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/styling-and-localization.mdx

Example CSS for customizing the popover appearance and arrow colors using a custom class.

```css
.driver-popover.checkout-popover {
  --popover-bg: #111827;

  background-color: var(--popover-bg);
  color: #f9fafb;
}

.checkout-popover .driver-popover-title {
  color: #ffffff;
}

.checkout-popover .driver-popover-description,
.checkout-popover .driver-popover-progress-text {
  color: #d1d5db;
}

.checkout-popover .driver-popover-footer-btn {
  background-color: #f9fafb;
  color: var(--popover-bg);
}

.checkout-popover .driver-popover-arrow-side-top { border-top-color: var(--popover-bg) }
.checkout-popover .driver-popover-arrow-side-right { border-right-color: var(--popover-bg) }
.checkout-popover .driver-popover-arrow-side-bottom { border-bottom-color: var(--popover-bg) }
.checkout-popover .driver-popover-arrow-side-left { border-left-color: var(--popover-bg) }
```

--------------------------------

### Create a Tour

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/tour.mdx

Initialize a new tour using different authoring methods.

```twig
<twig:Driver:Tour id="onboarding">
    ...
</twig:Driver:Tour>
```

```twig
{% set tour = create_tour('onboarding') %}
```

```php
$tour = $tourBuilder->create('onboarding');
```

--------------------------------

### Tour Creation

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/tour.mdx

Methods to initialize a new Tour instance using different authoring forms.

```APIDOC
## Create Tour

### Component
<twig:Driver:Tour id="onboarding">...</twig:Driver:Tour>

### Twig Builder
{% set tour = create_tour('onboarding') %}

### PHP Builder
$tour = $tourBuilder->create('onboarding');
```

--------------------------------

### Create a tour using PHP

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Use the TourBuilder service to define tours in your controller and pass them to the template.

```php
use Pentiminax\UX\Driver\Builder\TourBuilder;

public function __construct(private readonly TourBuilder $tourBuilder)
{
}

public function dashboard(): Response
{
    $tour = $this->tourBuilder->create('welcome')
        ->addStep('.dashboard-title', 'Dashboard', 'This is your daily overview')
        ->once();

    return $this->render('dashboard.html.twig', ['tour' => $tour]);
}
```

--------------------------------

### Create Hints

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/hints.mdx

Initialize a new hints group using Component, Twig builder, or PHP builder syntax.

```twig
<twig:Driver:Hints id="orders-help">
    ...
</twig:Driver:Hints>
```

```twig
{% set hints = create_hints('orders-help') %}
```

```php
$hints = $hintsBuilder->create('orders-help');
```

--------------------------------

### Declare a highlight using the PHP builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

Build a tour with a single step in PHP and trigger it using the highlight action in Twig.

```php
$highlight = $this->tourBuilder->create('export-highlight')
    ->addStep('#invoice-export', 'Export', 'CSV and PDF are both available here');

return $this->render('invoice/index.html.twig', ['highlight' => $highlight]);
```

```twig
<button type="button" {{ ux_tour(highlight) }} {{ ux_tour_action('highlight') }}>
    Where is export?
</button>
```

--------------------------------

### Create a Step

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/step.mdx

Define a step using component tags or builder methods to specify target, title, description, and alignment.

```twig
<twig:Driver:Step :order="1" title="Title" description="Description" side="bottom" align="start">
    <div class="selector">...</div>
</twig:Driver:Step>
```

```twig
{% set tour = tour.addStep('.selector', 'Title', 'Description', 'bottom', 'start', {}) %}
```

```php
$tour->addStep(
    element: '.selector',
    title: 'Title',
    description: 'Description',
    side: 'bottom',
    align: 'start',
    options: [],
);
```

--------------------------------

### Tour Methods

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/tour.mdx

Methods available on the Tour object for managing steps and configuration.

```APIDOC
## Tour Methods

- **addStep()**: Appends a Step to the tour and returns $this.
- **getSteps()**: Returns serialized Driver.js steps.
- **getOptions()**: Returns serialized Driver.js configuration.
- **isOnce()**: Returns the bundle persistence flag.
```

--------------------------------

### Configure Hint labels

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/styling-and-localization.mdx

Set the button text for hints using different builder methods.

```twig
<twig:Driver:Hints id="checkout-help" buttonText="{{ 'hints.done'|trans }}">
    ...
</twig:Driver:Hints>
```

```twig
{% set hints = create_hints('checkout-help').buttonText('hints.done'|trans) %}
```

```php
$hints = $this->hintsBuilder->create('checkout-help')
    ->buttonText($translator->trans('hints.done'));
```

--------------------------------

### Declare a Tour using PHP builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/installation.mdx

Construct a tour in a PHP controller using the TourBuilder service and render it in the template.

```php
use Pentiminax\UX\Driver\Builder\TourBuilder;

public function __construct(private readonly TourBuilder $tourBuilder)
{
}

public function dashboard(): Response
{
    $tour = $this->tourBuilder->create('welcome')
        ->addStep('.dashboard-title', 'Dashboard', 'This is your daily overview');

    return $this->render('dashboard.html.twig', ['tour' => $tour]);
}
```

```twig
<button {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>Start tour</button>
```

--------------------------------

### Define a Tour using Twig Components

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/authoring-modes.mdx

Use the <twig:Driver:Tour> component to wrap help content directly around the elements it describes within a template.

```twig
<twig:Driver:Tour id="profile-tour">
    <button {{ ux_tour_action('start') }}>Start tour</button>

    <twig:Driver:Step :order="1" title="Profile" description="Keep your public details current">
        <section class="profile-card">...</section>
    </twig:Driver:Step>

    <twig:Driver:Step :order="2" title="Security" description="Review login settings" side="top">
        <section class="security-card">...</section>
    </twig:Driver:Step>
</twig:Driver:Tour>
```

--------------------------------

### Configure hint styles

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/styling-and-localization.mdx

Overrides default hint variables to customize beacon appearance.

```css
.driver-hint {
  --driver-hint-color: #e23845;
  --driver-hint-size: 14px;
}
```

--------------------------------

### Run development and test commands

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Execute these commands to run PHPUnit tests, Stimulus tests, and documentation build checks.

```bash
php vendor/bin/phpunit

cd assets
npm test

cd ../docs
npm run check
npm run build
npm run test:build
```

--------------------------------

### Implement Hints using the Twig Builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/hints.mdx

Create a hints object in Twig using the create_hints function and render it with the ux_hints attribute.

```twig
{% set hints = create_hints('orders-help')
    .addHint('.filters', 'filters', 'Filters', 'Save time by narrowing the list first')
    .addHint('.export', 'export', 'Export', 'Download the current view as a CSV', 'left')
    .buttonText('Done') %}

<div {{ ux_hints(hints) }}></div>
```

--------------------------------

### Observe tour progress

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/events.mdx

Listen to non-cancelable events like ux-driver:highlighted for analytics or UI synchronization tasks.

```js
document.addEventListener('ux-driver:highlighted', (event) => {
  const { tourId, index, element } = event.detail

  analytics.track('tour_step_viewed', { tour: tourId, step: index })
  element.scrollIntoView({ block: 'nearest' })
})
```

--------------------------------

### Implement Hints using the PHP Builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/hints.mdx

Inject the HintsBuilder into your controller to define hints in PHP, then pass the object to your template.

```php
use Pentiminax\UX\Driver\Builder\HintsBuilder;

public function __construct(private readonly HintsBuilder $hintsBuilder)
{
}

public function index(): Response
{
    $hints = $this->hintsBuilder->create('orders-help')
        ->addHint('.filters', 'filters', 'Filters', 'Save time by narrowing the list first')
        ->addHint('.export', 'export', 'Export', 'Download the current view as a CSV', side: 'left')
        ->buttonText('Done');

    return $this->render('order/index.html.twig', ['hints' => $hints]);
}
```

```twig
<div {{ ux_hints(hints) }}></div>
```

--------------------------------

### Configure Tour labels

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/styling-and-localization.mdx

Set progress and navigation button text for tours using different builder methods.

```twig
<twig:Driver:Tour
    id="checkout-tour"
    progressText="{{ '{{current}}' }} / {{ '{{total}}' }}"
    nextBtnText="{{ 'tour.next'|trans }}"
    prevBtnText="{{ 'tour.back'|trans }}"
    doneBtnText="{{ 'tour.done'|trans }}"
>
    ...
</twig:Driver:Tour>
```

```twig
{% set tour = create_tour('checkout-tour')
    .progressText('{{current}} / {{total}}')
    .nextBtnText('tour.next'|trans)
    .prevBtnText('tour.back'|trans)
    .doneBtnText('tour.done'|trans) %}
```

```php
use Symfony\Contracts\Translation\TranslatorInterface;

public function checkout(TranslatorInterface $translator): Response
{
    $tour = $this->tourBuilder->create('checkout-tour')
        ->progressText('{{current}} / {{total}}')
        ->nextBtnText($translator->trans('tour.next'))
        ->prevBtnText($translator->trans('tour.back'))
        ->doneBtnText($translator->trans('tour.done'));

    return $this->render('checkout/index.html.twig', ['tour' => $tour]);
}
```

--------------------------------

### Configure motion animation settings

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/styling-and-localization.mdx

Control the Driver.js transition animation using component attributes or builder methods.

```twig
<twig:Driver:Tour id="checkout-tour" :animate="animate ?? true">
```

```twig
{% set tour = create_tour('checkout-tour').animate(animate ?? true) %}
```

```php
$tour = $this->tourBuilder->create('checkout-tour')
    ->animate($userPrefersMotion);
```

--------------------------------

### Configure Async Targets

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/step.mdx

Use waitForElement and skipMissingElement to handle elements that may not be immediately available in the DOM.

```twig
{% set tour = tour.addStep('#late-panel', 'Panel', options: {
    waitForElement: 2000,
    skipMissingElement: true,
}) %}
```

```php
$tour->addStep('#late-panel', 'Panel', options: [
    'waitForElement' => 2000,
    'skipMissingElement' => true,
]);
```

--------------------------------

### Control Hints with Stimulus Actions

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/hints.mdx

Use the ux_hints_action helper to trigger show, hide, close, or specific hint opening behaviors.

```twig
<button {{ ux_hints_action('show') }}>Show hints</button>
<button {{ ux_hints_action('hide') }}>Hide hints</button>
<button {{ ux_hints_action('close') }}>Close the open popover</button>

<button {{ ux_hints_action('open', {hintId: 'filters'}) }}>Open the filters hint</button>
```

--------------------------------

### Define minimal hints with Twig

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Use the Driver:Hints component to display contextual hints on your page.

```twig
<twig:Driver:Hints id="dashboard-help" buttonText="Done">
    <twig:Driver:Hint hintId="filters" title="Filters" description="Narrow the list before export">
        <button type="button">Filters</button>
    </twig:Driver:Hint>
</twig:Driver:Hints>
```

--------------------------------

### Define a Tour using the PHP builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/first-tour.mdx

Constructs the tour object within a controller, enabling dynamic step generation based on user data or feature flags.

```php
namespace App\Controller;

use Pentiminax\UX\Driver\Builder\TourBuilder;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class OrderController extends AbstractController
{
    public function __construct(private readonly TourBuilder $tourBuilder)
    {
    }

    #[Route('/orders', name: 'orders')]
    public function index(): Response
    {
        $tour = $this->tourBuilder->create('orders-tour')
            ->addStep('.orders-title', 'Orders', 'Review current customer orders')
            ->addStep('.filters', 'Filters', 'Narrow the list before export')
            ->addStep('.export', 'Done', 'Export the filtered result', side: 'left')
            ->once();

        return $this->render('order/index.html.twig', ['tour' => $tour]);
    }
}
```

```twig
<button type="button" {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>
    Start tour
</button>
```

--------------------------------

### Handle hint dismissal

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/events.mdx

Listen to hint events to record user interactions, such as persisting dismissals on the server.

```js
document.addEventListener('ux-driver:hint-dismiss', (event) => {
  const { groupId, hintId } = event.detail

  fetch('/preferences/hints', {
    method: 'POST',
    body: JSON.stringify({ group: groupId, hint: hintId }),
  })
})
```

--------------------------------

### Configure highlight options

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

Pass additional options like popover classes or button text to the ux_highlight helper.

```twig
{{ ux_highlight('#invoice-export', 'Export', 'CSV and PDF are both available', 'left', 'center', {
    doneBtnText: 'Got it',
    popoverClass: 'invoice-popover',
}) }}
```

--------------------------------

### Define a minimal tour with Twig

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Use the Driver:Tour component to define tour steps and trigger actions directly in Twig templates.

```twig
<twig:Driver:Tour id="welcome">
    <button type="button" {{ ux_tour_action('start') }}>
        Start tour
    </button>

    <twig:Driver:Step :order="1" title="Dashboard" description="This is your daily overview">
        <h1>Dashboard</h1>
    </twig:Driver:Step>
</twig:Driver:Tour>
```

--------------------------------

### Implement Hints using Twig Components

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/hints.mdx

Use the twig:Driver:Hints component to define a group of hints directly in your Twig template.

```twig
<twig:Driver:Hints id="orders-help" buttonText="Done" :overlay="true">
    <twig:Driver:Hint hintId="filters" title="Filters" description="Save time by narrowing the order list first">
        <button type="button">Filters</button>
    </twig:Driver:Hint>

    <twig:Driver:Hint hintId="export" title="Export" description="Download the current view as a CSV" side="left">
        <button type="button">Export</button>
    </twig:Driver:Hint>
</twig:Driver:Hints>
```

--------------------------------

### Render a PHP-defined tour in Twig

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Use the ux_tour helper to attach the tour object to a button element.

```twig
<button type="button" {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>Start tour</button>
```

--------------------------------

### Define a Tour using the Twig builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/first-tour.mdx

Uses CSS selectors to associate steps with elements, allowing steps to be defined independently of the markup structure.

```twig
{% set tour = create_tour('orders-tour')
    .addStep('.orders-title', 'Orders', 'Review current customer orders')
    .addStep('.filters', 'Filters', 'Narrow the list before export')
    .addStep('.export', 'Done', 'Export the filtered result', 'left')
    .once() %}

<button type="button" {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>
    Start tour
</button>
```

--------------------------------

### Refresh tour and hints after layout shifts

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/dynamic-targets.mdx

Recomputes the overlay and popover positions against the current DOM state.

```twig
<button {{ ux_tour_action('refresh') }}>Refresh tour</button>
<button {{ ux_hints_action('refresh') }}>Refresh hints</button>
```

--------------------------------

### ux_highlight() function signature

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

The signature for the ux_highlight helper function.

```php
ux_highlight(
    string $element,
    string|Markup $title,
    string|Markup|null $description = null,
    string $side = 'bottom',
    string $align = 'start',
    array $options = [],
)
```

--------------------------------

### addStep(element, title, description, side, align, options)

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/step.mdx

Adds a new step to the tour. The element can be a selector string or null for a centered step.

```APIDOC
## Method: addStep

### Description
Adds a step to the tour. Options provided here override tour-level defaults.

### Parameters
- **element** (string|null) - The CSS selector for the target element, or null for a centered step.
- **title** (string) - The title of the step.
- **description** (string) - The description text for the step.
- **side** (string) - Placement of the popover: top, right, bottom, or left.
- **align** (string) - Alignment of the popover: start, center, or end.
- **options** (array) - Additional configuration options including order, centered, popoverClass, and async settings like waitForElement.
```

--------------------------------

### Declare a highlight using a Twig component

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

Use the Driver:Tour component with a single Step to create a highlight.

```twig
<twig:Driver:Tour id="export-highlight">
    <button type="button" {{ ux_tour_action('highlight') }}>Where is export?</button>

    <twig:Driver:Step :order="1" title="Export" description="CSV and PDF are both available here">
        <button type="button" id="invoice-export">Export</button>
    </twig:Driver:Step>
</twig:Driver:Tour>
```

--------------------------------

### Declare a Tour using Twig builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/installation.mdx

Create a tour programmatically within a Twig template using the create_tour function.

```twig
{% set tour = create_tour('welcome')
    .addStep('.dashboard-title', 'Dashboard', 'This is your daily overview') %}

<button {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>Start tour</button>
```

--------------------------------

### ux_highlight()

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

The ux_highlight() function is a shorthand for creating a one-step tour that highlights a specific element with a popover.

```APIDOC
## ux_highlight(string $element, string|Markup $title, string|Markup|null $description = null, string $side = 'bottom', string $align = 'start', array $options = [])

### Description
Generates a one-step tour highlight for a specified element. This function is used within Twig templates to define the target element, title, description, and positioning of the popover.

### Parameters
- **element** (string) - Required - The CSS selector of the element to highlight.
- **title** (string|Markup) - Required - The title text for the popover.
- **description** (string|Markup|null) - Optional - The description text for the popover.
- **side** (string) - Optional - The side of the element to place the popover ('top', 'right', 'bottom', 'left'). Defaults to 'bottom'.
- **align** (string) - Optional - The alignment of the popover ('start', 'center', 'end'). Defaults to 'start'.
- **options** (array) - Optional - Additional per-step options for the popover (e.g., doneBtnText, popoverClass).
```

--------------------------------

### Create a Centered Step

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/step.mdx

Use a null element or the centered option to display a step without a specific target element.

```twig
<twig:Driver:Step
    :order="1"
    :centered="true"
    title="Welcome"
    description="Start with the big picture"
/>
```

```twig
{% set tour = tour.addStep(null, 'Welcome', 'Start with the big picture') %}
```

```php
$tour->addStep(null, 'Welcome', 'Start with the big picture');
```

--------------------------------

### Declare a Tour using Twig components

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/installation.mdx

Define a tour directly in your Twig template using the Driver:Tour component.

```twig
<twig:Driver:Tour id="welcome">
    <button {{ ux_tour_action('start') }}>Start tour</button>

    <twig:Driver:Step :order="1" title="Dashboard" description="This is your daily overview">
        <h1>Dashboard</h1>
    </twig:Driver:Step>
</twig:Driver:Tour>
```

--------------------------------

### Define a Tour using Twig Components

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/first-tour.mdx

Wraps elements directly within the component tree to define tour steps in the order they appear on the page.

```twig
<twig:Driver:Tour id="orders-tour" :once="true">
    <button type="button" {{ ux_tour_action('start') }}>
        Start tour
    </button>

    <twig:Driver:Step :order="1" title="Orders" description="Review current customer orders">
        <h1>Orders</h1>
    </twig:Driver:Step>

    <twig:Driver:Step :order="2" title="Filters" description="Narrow the list before export" side="bottom">
        <form class="filters">...</form>
    </twig:Driver:Step>

    <twig:Driver:Step :order="3" title="Done" description="Export the filtered result" side="left">
        <button type="button">Export</button>
    </twig:Driver:Step>
</twig:Driver:Tour>
```

--------------------------------

### Trigger Hint Actions

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/hints.mdx

Use the ux_hints_action helper to trigger specific hint behaviors like restoring a dismissed hint.

```twig
<button {{ ux_hints_action('restore', {hintId: 'export'}) }}>
    Restore export hint
</button>
```

--------------------------------

### Declare a highlight using the Twig builder

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

Use the ux_highlight shorthand to generate a one-step tour for a specific element selector.

```twig
<button type="button"
        {{ ux_highlight('#invoice-export', 'Export', 'CSV and PDF are both available here') }}
        {{ ux_tour_action('highlight') }}>
    Where is export?
</button>
```

--------------------------------

### Escaping content in UX Driver

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/security.mdx

Demonstrates how content is escaped by default across different implementation methods.

```twig
<twig:Driver:Step title="<b>Billing</b>" description="<script>alert(1)</script>" />
```

```twig
{% set tour = create_tour('billing-tour')
    .addStep('.billing', '<b>Billing</b>', '<script>alert(1)</script>') %}
```

```php
$tour = $this->tourBuilder->create('billing-tour')
    ->addStep('.billing', '<b>Billing</b>', '<script>alert(1)</script>');
```

--------------------------------

### Use trusted markup in highlights

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/highlights.mdx

Pass Twig/Markup to the title or description to render HTML within the popover.

```twig
{{ ux_highlight('#invoice-export', ux_driver_html('<strong>Export</strong>'), 'CSV and PDF') }}
```

--------------------------------

### Trigger Hints actions

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/control-and-persistence.mdx

Use Stimulus actions to manage the visibility and state of Hints.

```twig
<button {{ ux_hints_action('show') }}>Show hints</button>
<button {{ ux_hints_action('hide') }}>Hide hints</button>
<button {{ ux_hints_action('close') }}>Close the open popover</button>
<button {{ ux_hints_action('restoreAll') }}>Restore dismissed hints</button>
```

--------------------------------

### Add a Hint

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/hints.mdx

Register a new hint within a group using Component, Twig builder, or PHP builder syntax.

```twig
<twig:Driver:Hint hintId="filters" title="Filters" description="Narrow the list first">
    <button type="button">Filters</button>
</twig:Driver:Hint>
```

```twig
{% set hints = hints.addHint('.filters', 'filters', 'Filters', 'Narrow the list first') %}
```

```php
$hints->addHint(
    element: '.filters',
    id: 'filters',
    title: 'Filters',
    description: 'Narrow the list first',
    side: 'bottom',
    align: 'start',
    options: [],
);
```

--------------------------------

### Trigger a Tour manually

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/getting-started/first-tour.mdx

Uses the ux_tour_action attribute on a button to initiate the tour.

```twig
<button {{ ux_tour_action('start') }}>Start tour</button>
```

--------------------------------

### Skip missing elements in tour steps

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/dynamic-targets.mdx

Allows the tour to continue if a selector does not match, useful for role-based UI elements.

```twig
{% set tour = create_tour('admin-tour')
    .addStep('.orders', 'Orders', 'Every account sees this')
    .addStep('.export', 'Export', 'Only admins see this control', options: {
        skipMissingElement: true,
    }) %}

<button type="button" {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>
    Start tour
</button>
```

```php
$tour = $this->tourBuilder->create('admin-tour')
    ->addStep('.orders', 'Orders', 'Every account sees this')
    ->addStep('.export', 'Export', 'Only admins see this control', options: [
        'skipMissingElement' => true,
    ]);
```

--------------------------------

### Enable once-only persistence

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/control-and-persistence.mdx

Prevent a Tour from showing again after completion by setting the 'once' flag, which stores state in localStorage.

```twig
<twig:Driver:Tour id="welcome" :once="true">
    ...
</twig:Driver:Tour>
```

```twig
{% set tour = create_tour('welcome').once() %}
```

```php
$tour = $this->tourBuilder->create('welcome')->once();
```

--------------------------------

### Wait for an element in tour steps

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/dynamic-targets.mdx

Pauses the tour until the specified selector matches or the timeout expires.

```twig
{% set tour = create_tour('invoice-tour')
    .addStep('#open-invoice', 'Invoices', 'Open one to see the preview')
    .addStep('#invoice-preview', 'Preview', 'This renders after the modal opens', options: {
        waitForElement: 2000,
    }) %}

<button type="button" {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>
    Start tour
</button>
```

```php
$tour = $this->tourBuilder->create('invoice-tour')
    ->addStep('#open-invoice', 'Invoices', 'Open one to see the preview')
    ->addStep('#invoice-preview', 'Preview', 'This renders after the modal opens', options: [
        'waitForElement' => 2000,
    ]);
```

--------------------------------

### Apply popoverClass to Tour

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/styling-and-localization.mdx

Adds a custom class to the popover wrapper using different builder methods.

```twig
<twig:Driver:Tour id="checkout-tour" popoverClass="checkout-popover">
    ...
</twig:Driver:Tour>
```

```twig
{% set tour = create_tour('checkout-tour').popoverClass('checkout-popover') %}
```

```php
$tour = $this->tourBuilder->create('checkout-tour')
    ->popoverClass('checkout-popover');
```

--------------------------------

### Block navigation with preventDefault

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/events.mdx

Use preventDefault on cancelable events like ux-driver:next to stop default controller behavior, such as moving to the next step.

```js
document.addEventListener('ux-driver:next', (event) => {
  const { tourId, index } = event.detail

  if (tourId === 'checkout-tour' && index === 1 && !form.reportValidity()) {
    event.preventDefault()
  }
})
```

--------------------------------

### Import Driver.js styles in Webpack Encore

Source: https://github.com/pentiminax/ux-driver/blob/main/README.md

Include these imports in your main application entry file when using Webpack Encore.

```js
import 'driver.js/dist/driver.css'
import 'driver.js/dist/hints.css'
```

--------------------------------

### Twig Functions

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/reference/tour.mdx

Helper functions available in Twig templates for rendering and controlling tours.

```APIDOC
## Twig Functions

- **create_tour(id)**: Creates a new Tour for chaining.
- **ux_tour(tour)**: Renders controller attributes.
- **ux_tour_action(action, params)**: Renders data-action attributes for the Tour controller.
- **ux_highlight(element, title, description, side, align, options)**: Creates a one-Step Tour for highlighting.
- **ux_driver_html(html)**: Marks a string as trusted markup.
```

--------------------------------

### Trigger Tour actions

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/control-and-persistence.mdx

Use Stimulus actions to control Tour navigation and state.

```twig
<button {{ ux_tour_action('start') }}>Start tour</button>
<button {{ ux_tour_action('next') }}>Next</button>
<button {{ ux_tour_action('previous') }}>Previous</button>
<button {{ ux_tour_action('refresh') }}>Refresh position</button>
<button {{ ux_tour_action('destroy') }}>Close tour</button>

<button {{ ux_tour_action('moveTo', {index: 2}) }}>Go to step 3</button>
```

--------------------------------

### Rendering trusted HTML

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/security.mdx

Bypasses default escaping for specific strings using helper functions or Markup instances.

```twig
<twig:Driver:Step :title="ux_driver_html('<strong>Billing</strong>')" />
```

```twig
{% set tour = create_tour('billing-tour')
    .addStep('.billing', ux_driver_html('<strong>Billing</strong>')) %}
```

```php
use Twig\Markup;

$tour = $this->tourBuilder->create('billing-tour')
    ->addStep('.billing', new Markup('<strong>Billing</strong>', 'UTF-8'));
```

--------------------------------

### Sanitizing user-authored rich text

Source: https://github.com/pentiminax/ux-driver/blob/main/docs/src/content/docs/guides/security.mdx

Uses the Symfony HTML sanitizer to safely process user input before marking it as trusted.

```php
use Symfony\Component\HtmlSanitizer\HtmlSanitizerInterface;
use Twig\Markup;

public function __construct(private readonly HtmlSanitizerInterface $htmlSanitizer)
{
}

public function step(string $userHtml): Markup
{
    return new Markup($this->htmlSanitizer->sanitize($userHtml), 'UTF-8');
}
```
Tokens:
Raw