diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8ab86c134..7dd3d3971 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,7 +8,12 @@ on: jobs: build: - name: Browser tests + name: "Browser tests (Trix.config.editor.formAssociated = ${{ matrix.formAssociated }})" + strategy: + matrix: + formAssociated: [true, false] + env: + FORM_ASSOCIATED: "${{ matrix.formAssociated }}" runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 diff --git a/README.md b/README.md index 2645b79cd..e6f404922 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ This is the approach that all modern, production ready, WYSIWYG editors now take
Trix supports all evergreen, self-updating desktop and mobile browsers.
-Trix is built with established web standards, notably [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), [Mutation Observer](https://dom.spec.whatwg.org/#mutation-observers), and [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). +Trix is built with established web standards, notably [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), [Element Internals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), [Mutation Observer](https://dom.spec.whatwg.org/#mutation-observers), and [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). # Getting Started @@ -88,6 +88,16 @@ If the attribute is defined in `Trix.config.blockAttributes`, Trix will apply th Clicking the quote button toggles whether the block should be rendered with `
`. +## Integrating with Element Internals + +Trix will integrate `` elements with forms depending on the browser's support for [Element Internals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals). By default, Trix will enable support for `ElementInternals` when the feature is enabled in the browser. If there is a need to disable support for `ElementInternals`, set `Trix.config.editor.formAssociated = false`: + +```js +import Trix from "trix" + +Trix.config.editor.formAssociated = false +``` + ## Invoking Internal Trix Actions Internal actions are defined in `controllers/editor_controller.js` and consist of: @@ -148,6 +158,126 @@ To populate a `` with stored content, include that content in the a Always use an associated input element to safely populate an editor. Trix won’t load any HTML content inside a `` tag. +## Validating the Editor + +Out of the box, `` elements support browsers' built-in [Constraint +validation][]. When rendered with the [required][] attribute, editors will be +invalid when they're completely empty. For example, consider the following HTML: + +```html + + +``` + +Since the `` element is `[required]`, it is invalid when its value +is empty: + +```js +const editor = document.querySelector("trix-editor") + +editor.validity.valid // => false +editor.validity.valueMissing // => true +editor.matches(":valid") // => false +editor.matches(":invalid") // => true + +editor.value = "A value that isn't empty" + +editor.validity.valid // => true +editor.validity.valueMissing // => false +editor.matches(":valid") // => true +editor.matches(":invalid") // => false +``` + +In addition to the built-in `[required]` attribute, `` +elements support custom validation through their [setCustomValidity][] method. +For example, consider the following HTML: + +```js + + +``` + +Custom validation can occur at any time. For example, validation can occur after +a `trix-change` event fired after the editor's contents change: + +```js +addEventListener("trix-change", (event) => { + const editorElement = event.target + const trixDocument = editorElement.editor.getDocument() + const isValid = (trixDocument) => { + // determine the validity based on your custom criteria + return true + } + + if (isValid(trixDocument)) { + editorElement.setCustomValidity("") + } else { + editorElement.setCustomValidity("The document is not valid.") + } +} +``` + +[Constraint validation]: https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation +[required]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required +[setCustomValidity]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity + +## Disabling the Editor + +To disable the ``, render it with the `[disabled]` attribute: + +```html + +``` + +Disabled editors are not editable, cannot receive focus, and their values will +be ignored when their related `
` element is submitted. + +To change whether or not an editor is disabled, either toggle the `[disabled]` +attribute or assign a boolean to the `.disabled` property: + +```html + + + +``` + +When disabled, the editor will match the [:disabled CSS +pseudo-class][:disabled]. + +[:disabled]: https://developer.mozilla.org/en-US/docs/Web/CSS/:disabled + +## Providing an Accessible Name + +Like other form controls, `` elements should have an accessible name. The `` element integrates with `