Lexxy

https://lexxy.dev/docs
Admin
Lexxy is a rich text editor designed for seamless integration with Ruby on Rails Action Text,...
Tokens:7,998
Snippets:123
Trust Score:4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Development Server

Source: https://lexxy.dev/docs/development.html

Starts both the Rails server and the JavaScript watcher for local development.

```bash
bin/dev

```

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

### Install Bundled Gems

Source: https://lexxy.dev/docs

Execute this command after adding the gem to your Gemfile to install all dependencies.

```bash
bundle install
```

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

### Full Lexxy Extension Example

Source: https://lexxy.dev/docs/extensions.html

A comprehensive example demonstrating a custom Lexxy extension, including configuration, enabled state, allowed elements, lexical extension definition, and toolbar initialization.

```javascript
import * as Lexxy from "@37signals/lexxy"

Lexxy.configure({
  global: {
    extensions: [ MyLexxyExtension ]
  },
  default: {
    my_extension: {
      enableCoolFeature: true
    }
  }
})

class MyLexxyExtension extends Lexxy.Extension {
  // optional: defaults to true
  get enabled() {
    // depend on an editor config
    return this.editorElement.supportsRichText

    // ... or a custom configuration
    return this.#config.enableCoolFeature
  }

  // optional: allow additional elements
  get allowedElements() {
    return [ { tag: "iframe", attributes: [ "src", "loading", "allow" ] } ]
  }

  get lexicalExtension() {
    return this.defineExtension({
      name: "lexxy/my_lexical_extension",
      config: this.#config,
      ///...
      register(editor, config) {
        // ... custom Lexical behavior
      }
    })
  }

  initializeToolbar(lexxyToolbar) {
    // ...Toolbar initialization code

    lexxyToolbar.querySelector("button[name=bold]").insertAdjacentElement(myToolbarElement)
  }

  get #config() {
    return this.editorConfig.get("my_extension")
  }
}


```

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

### Install Project Dependencies

Source: https://lexxy.dev/docs/development.html

Installs all necessary dependencies including Ruby gems, Node packages, Playwright browsers, and database.

```bash
bin/setup

```

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

### Start Development Server on Custom Port

Source: https://lexxy.dev/docs/development.html

Runs the development server on a specified port, useful for parallel worktrees.

```bash
PORT=3100 bin/dev

```

```bash
PORT=3200 bin/dev

```

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

### Run Jekyll Site Locally

Source: https://lexxy.dev/docs/development.html

Installs dependencies and serves the Jekyll site locally. The site will be available at http://localhost:4000/.

```bash
cd home
bundle install
bundle exec jekyll serve

```

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

### Install Lexxy NPM Package

Source: https://lexxy.dev/docs

Use yarn to add the Lexxy and Active Storage NPM packages when using JavaScript bundlers.

```bash
yarn add @37signals/lexxy
yarn add @rails/activestorage # to support attachments
```

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

### Configure Named Presets

Source: https://lexxy.dev/docs/configuration.html

Define named presets to organize alternative editor setups. This example creates a 'simple' preset that disables rich text editing.

```javascript
Lexxy.configure({
  simple: {
    richText: false
  }
})

```

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

### Basic Editor Element

Source: https://lexxy.dev/docs/configuration.html

An example of a basic Lexxy editor element with no specific configuration.

```html
<lexxy-editor></lexxy-editor>

```

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

### Restrict Prompt to Document Start

Source: https://lexxy.dev/docs/prompts/options-reference.html

Configures the prompt to only trigger when it is the very first character of the document.

```html
<lexxy-prompt trigger="!" name="bot" only-at="^">
  …
</lexxy-prompt>
```

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

### Stimulus Controller for Syntax Highlighting

Source: https://lexxy.dev/docs/css-setup.html

Create a Stimulus controller to apply syntax highlighting to Action Text content using Lexxy's highlightCode function. Ensure Lexxy is installed or imported correctly.

```javascript
import { highlightCode } from "lexxy"
// Or if you installed via a javascript bundler:
// import { highlightCode } from "@37signals/lexxy"

export default class extends Controller {
  connect() {
    highlightCode()
  }
}

```

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

### Configure Headings via Preset

Source: https://lexxy.dev/docs/configuration.html

Configure the available heading levels in the toolbar dropdown via a preset. This example sets the default headings to h1, h2, and h3.

```javascript
// Via preset
Lexxy.configure({
  default: { headings: ["h1", "h2", "h3"] }
})

```

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

### Configure Default Options

Source: https://lexxy.dev/docs/configuration.html

Override the default preset to change the behavior of all editors. This example disables the toolbar for all editors.

```javascript
Lexxy.configure({
  default: {
    toolbar: false
  }
})

```

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

### Basic Lexxy Prompt Setup

Source: https://lexxy.dev/docs/prompts.html

This snippet shows how to add a `<lexxy-prompt>` element to a form's rich text area. The `trigger` attribute specifies the character that opens the prompt.

```erb
<%= form.rich_text_area :body do %>
  <lexxy-prompt trigger="@">
  </lexxy-prompt>
<% end %>

```

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

### Configure Remote Source for Mentions

Source: https://lexxy.dev/docs/prompts/remote-attachments.html

Use the `src` attribute to specify the remote endpoint for loading prompt items. This example configures mentions triggered by '@'.

```html
<lexxy-prompt trigger="@" src="<%= people_path %>" name="mention">
</lexxy-prompt>

```

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

### Default Prompt Trigger

Source: https://lexxy.dev/docs/prompts/options-reference.html

The default behavior for the prompt trigger, allowing it to activate at the start of the document or after whitespace/paragraph breaks.

```html
<lexxy-prompt trigger="@" name="mention">
  …
</lexxy-prompt>
```

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

### Default Attachment Rendering Partial

Source: https://lexxy.dev/docs/prompts/inline-attachments.html

Define the partial for rendering the attachment in the view. This example renders the person's name and initials.

```erb
<%# app/views/people/_person.html.erb %>
<em><%= person.name %></em> (<strong><%= person.initials %></strong>)

```

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

### Benchmark Browser Scenarios

Source: https://lexxy.dev/docs/development.html

Provides options to customize benchmark runs, such as listing available scenarios, running a specific scenario with reduced samples, or setting a shorter time budget.

```bash
# List scenarios
yarn benchmark:browser --list-scenarios

# Run one scenario with smaller sample sizes
yarn benchmark:browser --scenario load-very-large-table --warmup 1 --iterations 3

# Use a shorter time budget per sample (default is 5000 ms)
yarn benchmark:browser --time-budget 2000

```

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

### Import Lexxy

Source: https://lexxy.dev/docs/configuration.html

Import the Lexxy library. This should be done immediately after your import statement.

```javascript
import * as Lexxy from "lexxy"

```

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

### Pin Lexxy with Import Maps

Source: https://lexxy.dev/docs

Configure import maps to include Lexxy and Active Storage for attachments.

```ruby
# importmap.rb
pin "lexxy", to: "lexxy.js"
pin "@rails/activestorage", to: "activestorage.esm.js" # to support attachments
```

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

### Run Browser Benchmark Suite

Source: https://lexxy.dev/docs/development.html

Executes the full suite of browser benchmarks for the editor's JavaScript side. Results are saved to `tmp/browser-benchmarks.json` by default.

```bash
yarn benchmark:browser

```

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

### Import highlightCode Helper from Submodule

Source: https://lexxy.dev/docs/css-setup.html

If using the npm package and aiming for bundle splitting, import the highlightCode helper directly from the Lexxy helpers submodule.

```javascript
import { highlightCode } from "@37signals/lexxy/helpers"

```

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

### Import Lexical

Source: https://lexxy.dev/docs/extensions.html

Import the Lexical package from the top-level module.

```javascript
import { Lexical } from "@37signals/lexxy"

```

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

### Use a Preset

Source: https://lexxy.dev/docs/configuration.html

Opt into a named preset for an individual editor using the 'preset' attribute.

```html
<lexxy-editor preset="simple"></lexxy-editor>

```

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

### Render Prompt Items Partial

Source: https://lexxy.dev/docs/prompts/remote-attachments.html

The controller action renders a partial for each item in the collection, formatting them as prompt items for Lexxy.

```erb
<%= render partial: "people/prompt_item", collection: @people %>

```

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

### Configure Highlighting Colors

Source: https://lexxy.dev/docs/highlighting.html

Use this configuration to set custom colors for highlighting buttons and to permit specific colors during paste operations. The `color` and `background-color` arrays within `buttons` define the available toolbar options, while `permit` allows Lexxy to conserve additional colors on paste.

```javascript
Lexxy.configure({
  default: {
    highlight: {
      buttons: {
        color: [ "red", "rgb(255, 0, 0)", "var(--text-color-1)" ],
        "background-color": [ "red", "rgba(0, 255, 0, 0.5)", "var(--bg-color-1)" ]
      },
      permit: {
        color: [ "pink", "blue", "var(--legacy-text-color)" ],
        "background-color": [ "light-pink", "light-blue", "var(--legacy-bg-color)" ]
      }
    }
  }
})

```

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

### Controller Action for Remote Prompt Items

Source: https://lexxy.dev/docs/prompts/remote-attachments.html

Define a controller action to fetch and serve all potential prompt items (e.g., people) from the database. Ensure `layout: false` is set for rendering only the partials.

```ruby
class PeopleController < ApplicationController
  def index
    @people = Person.all

    render layout: false
  end
end

```

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

### Include Lexxy via CDN

Source: https://lexxy.dev/docs

Link to Lexxy's CSS and import its JavaScript module directly from a CDN like esm.sh.

```html
<link rel="stylesheet" href="https://unpkg.com/@37signals/lexxy@latest/dist/stylesheets/lexxy.css">
<script type="module">
  import * as Lexxy from "https://esm.sh/@37signals/lexxy@latest"; /* <-- consider pinning to a stable version */
  // You can also configure Lexxy with:
  // Lexxy.configure(...)
</script>

<lexxy-editor class="lexxy-content" placeholder="Write something…">
</lexxy-editor>
```

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

### Import Lexxy in JavaScript Entry Point

Source: https://lexxy.dev/docs

Import the Lexxy JavaScript file into your application's main JavaScript entry point.

```javascript
// app/javascript/application.js
import "lexxy"
```

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

### Compare Benchmark Results

Source: https://lexxy.dev/docs/development.html

Compares two benchmark result files to identify regressions. This is useful for CI checks and understanding performance changes over time.

```bash
yarn benchmark:browser:compare tmp/baseline.json tmp/current.json

```

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

### Run JavaScript Unit Tests

Source: https://lexxy.dev/docs/development.html

Executes the JavaScript unit tests using Vitest.

```bash
yarn test

```

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

### Attaching Multiple Editors to a Prompt Item

Source: https://lexxy.dev/docs/prompts/multiple-attachments.html

Use multiple `<template type="editor">` tags within a `<lexxy-prompt-item>` to associate several attachments. Each template tag should have a unique `sgid` attribute pointing to the attachable content.

```html
<lexxy-prompt-item search="<%= group.name %>" >
  <template type="menu"><%= group.name %></template>
  <template type="editor" sgid="<% first.attachable_sgid %>">
    <%# first content %>
  </template>
  <template type="editor" sgid="<% second.attachable_sgid %>">
    <%# second content %>
  </template>
  <%# etc... %>
</lexxy-prompt-item>

```

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

### Import Lexical Node

Source: https://lexxy.dev/docs/extensions.html

Import specific Lexical nodes from the top-level module.

```javascript
import { ActionTextAttachmentNode } from "@37signals/lexxy"

```

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

### Import Lexxy with JavaScript Bundlers

Source: https://lexxy.dev/docs

Import the Lexxy package in your JavaScript entry point when using bundlers like esbuild or webpack.

```javascript
// app/javascript/application.js
import "@37signals/lexxy"
```

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

### Run All Rails System Tests

Source: https://lexxy.dev/docs/development.html

Executes all Rails system tests.

```bash
bin/rails test:all

```

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

### Run Linting Checks

Source: https://lexxy.dev/docs/development.html

Performs linting checks using both RuboCop for Ruby and a JavaScript linter.

```bash
bin/rubocop

```

```bash
yarn lint

```

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

### Run Playwright Browser Tests in Headed Mode

Source: https://lexxy.dev/docs/development.html

Executes Playwright browser tests with a visible browser window.

```bash
yarn test:browser:headed

```

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

### Run All Playwright Browser Tests

Source: https://lexxy.dev/docs/development.html

Executes all Playwright browser tests across all supported browsers.

```bash
yarn test:browser

```

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

### Link Unfurling with Stimulus Controller

Source: https://lexxy.dev/docs/events.html

This Stimulus controller handles the `lexxy:insert-link` event to unfurl pasted plain text links into richer HTML previews. It sends the URL to a backend endpoint for metadata retrieval and then replaces the link using provided callbacks.

```javascript
// app/javascript/controllers/link_unfurl_controller.js
import { Controller } from "@hotwired/stimulus"
import { post } from "@rails/request.js"

export default class extends Controller {
  static values = { url: String } // endpoint that handles unfurling

  unfurl(event) {
    this.#unfurlLink(event.detail.url, event.detail)
  }

  async #unfurlLink(url, callbacks) {
    const { response } = await post(this.urlValue, {
      body: JSON.stringify({ url }),
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    })

    const metadata = await response.json()
    this.#insertUnfurledLink(metadata, callbacks)
  }

  #insertUnfurledLink(metadata, callbacks) {
    // Replace the pasted link with your custom HTML
    callbacks.replaceLinkWith(this.#renderUnfurledLinkHTML(metadata))

    // Or, insert below the link as an attachment:
    // callbacks.insertBelowLink(this.#renderUnfurledLinkHTML(metadata), { attachment: true })
  }

  #renderUnfurledLinkHTML(link) {
    return `<a href="${link.canonical_url}">${link.title}</a>`
  }
}
```

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

### Enable Free HTML Attachments

Source: https://lexxy.dev/docs/prompts/free-html.html

Add the `insert-editable-text` attribute to your `<lexxy-prompt>` element to allow direct HTML insertion from prompt items into the editor. This is useful for inline elements like hashtags or emojis.

```html
<lexxy-prompt trigger="@" src="<%= people_path %>" insert-editable-text>
</lexxy-prompt>

```

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

### Insert Lexxy Editor in Vanilla HTML

Source: https://lexxy.dev/docs/usage.html

Insert a `<lexxy-editor>` tag to use Lexxy as a first-class form control in vanilla HTML.

```html
<lexxy-editor name="post[body]"...>...</lexxy-editor>

```

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

### Individual Prompt Item Definition

Source: https://lexxy.dev/docs/prompts/inline-attachments.html

Define the structure for each prompt item, including search attributes and templates for menu and editor representations. Ensure the sgid attribute is present for Action Text.

```html
<lexxy-prompt-item search="<%= "#{person.name} #{person.initials}" %>" sgid="<%= person.attachable_sgid %>">
  <template type="menu"><%= person.name %></template>
  <template type="editor">
    <%= render "people/person", person: person %>
  </template>
</lexxy-prompt-item>

```

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

### Add Lexxy Gem to Gemfile

Source: https://lexxy.dev/docs

Include this line in your application's Gemfile to add the Lexxy gem.

```ruby
gem 'lexxy', '~> 0.9.21'
```

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

### Include Lexxy Stylesheet with Rails Helper

Source: https://lexxy.dev/docs/css-setup.html

Use this Rails helper to include the Lexxy stylesheet in your application.

```erb
<%= stylesheet_link_tag "lexxy" %>
```

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

### Update Action Text Content Template for Stimulus

Source: https://lexxy.dev/docs/css-setup.html

Add the 'data-controller' attribute to the Action Text content wrapper to enable the Stimulus controller for syntax highlighting.

```erb
<div data-controller="syntax-highlight" class="lexxy-content">
  <%= yield -%>
</div>

```

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

### Configure Headings via HTML Attribute

Source: https://lexxy.dev/docs/configuration.html

Configure the available heading levels in the toolbar dropdown for an individual editor using the 'headings' HTML attribute.

```html
<!-- Via element attribute -->
<lexxy-editor headings='["h2", "h3"]'></lexxy-editor>

```

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

### Wrap Action Text Content

Source: https://lexxy.dev/docs/css-setup.html

Override the default Action Text content template to wrap content in a div with the 'lexxy-content' class for consistent styling.

```erb
<div class="lexxy-content">
  <%= yield -%>
</div>

```

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

### Allow Prompt Anywhere

Source: https://lexxy.dev/docs/prompts/options-reference.html

Enables the prompt trigger to activate anywhere in the document, including within words.

```html
<lexxy-prompt trigger="#" name="tag" only-at=".*">
  …
</lexxy-prompt>
```

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

### Enable Remote Filtering in Lexxy Prompt

Source: https://lexxy.dev/docs/prompts/remote-filtering.html

Add the 'remote-filtering' attribute to the '<lexxy-prompt>' element to enable server-side filtering for large datasets or complex searches.

```html
<lexxy-prompt trigger="@" src="<%= people_path %>" name="mention" remote-filtering>
</lexxy-prompt>

```

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

### Inline Prompt Rendering in Form

Source: https://lexxy.dev/docs/prompts/inline-attachments.html

Render prompt items inline within the <lexxy-prompt> element in the rich text area form. This approach displays all prompt options directly.

```erb
<%# app/views/form.html.erb %>
<%= form.rich_text_area :body do %>
  <lexxy-prompt trigger="@" name="mention">
    <%= render partial: "people/prompt_item", collection: Person.all, as: :person %>
  </lexxy-prompt>
<% end %>

```

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

### Lexxy Prompt Item Structure

Source: https://lexxy.dev/docs/prompts.html

Defines the structure of a prompt item, including the text for filtering, how it appears in the menu, and how it renders in the editor.

```html
<lexxy-prompt-item search="...">
  <template type="menu">...</template>
  <template type="editor">
    ...
  </template>
</lexxy-prompt-item>

```

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

### Add Lexxy Instance in Rails

Source: https://lexxy.dev/docs/usage.html

Use the regular Action Text form helper to add a Lexxy instance within a Rails form.

```erb
<%= form_with model: @post do |form| %>
  <%= form.rich_text_area :content %>
<% end %>

```

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

### Add Block Spacing on Markdown Insert

Source: https://lexxy.dev/docs/events.html

This snippet utilizes the `addBlockSpacing()` helper available on the `lexxy:insert-markdown` event's detail object. It ensures visual spacing between top-level elements, particularly paragraphs, by inserting `<p><br></p>`.

```javascript
editor.addEventListener("lexxy:insert-markdown", (event) => {
  event.detail.addBlockSpacing()
})
```

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

### Release NPM Package

Source: https://lexxy.dev/docs/development.html

Command to release the NPM package. Ensure version is updated in `version.rb` and `Gemfile.lock` is updated via `bundle` before committing.

```bash
yarn release

```

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

### Allow Spaces in Search Queries with Remote Filtering

Source: https://lexxy.dev/docs/prompts/remote-filtering.html

Include the 'supports-space-in-searches' attribute along with 'remote-filtering' to allow spaces within the search query, facilitating searches by full names.

```html
<lexxy-prompt trigger="@" src="<%= people_path %>" name="mention" remote-filtering supports-space-in-searches>
</lexxy-prompt>

```

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

### Override Options with HTML Attributes

Source: https://lexxy.dev/docs/configuration.html

Override individual options on a single editor using element attributes. These take precedence over presets and defaults.

```html
<lexxy-editor preset="simple" rich-text="true"></lexxy-editor>

```

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

### Run Playwright Browser Tests for a Single Browser

Source: https://lexxy.dev/docs/development.html

Executes Playwright browser tests for a specific browser (Chromium, Firefox, or WebKit).

```bash
yarn test:browser:chromium

```

```bash
yarn test:browser:firefox

```

```bash
yarn test:browser:webkit

```

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

### Configure Global Attachment Tag Name

Source: https://lexxy.dev/docs/configuration.html

Set the global attachment tag name. This option can only be set globally and affects how Action Text custom attachments are rendered.

```javascript
Lexxy.configure({
  global: {
    attachmentTagName: "bc-attachment"
  }
})

```

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

### Disable Lexxy Action Text Override

Source: https://lexxy.dev/docs

Configure application.rb to disable Lexxy's automatic override of Action Text form helpers.

```ruby
# config/application.rb
config.lexxy.override_action_text_defaults = false
```

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

### Declare Allowed HTML Elements

Source: https://lexxy.dev/docs/extensions.html

Declare custom HTML elements and their attributes that should be preserved during sanitization.

```javascript
get allowedElements() {
  return [ "figure", { tag: "iframe", attributes: [ "src", "loading", "allow" ] } ]
}

```

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

### Remove Images on Markdown Insert

Source: https://lexxy.dev/docs/events.html

This snippet listens for the `lexxy:insert-markdown` event and removes all `<img>` elements from the parsed document before it's inserted into the editor. This is useful for preventing images from being pasted.

```javascript
editor.addEventListener("lexxy:insert-markdown", (event) => {
  event.detail.document.querySelectorAll("img").forEach((img) => img.remove())
})
```

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

### Include Attachable Concern in Model

Source: https://lexxy.dev/docs/prompts/inline-attachments.html

Include the ActionText::Attachable concern and define the content_type method in your model. This sets up the model to be used as an attachment.

```ruby
class Person < ApplicationRecord
  include ActionText::Attachable

  def content_type
    "application/vnd.actiontext.mention"
  end
end

```
Tokens:
Raw