Making small things for the web.
My website ``` The rules tag maps labels to elements. `"name": ".name"` means the name field edits the element with class `name`. `@src` edits the image source, and `@href` edits the link destination. The CMS uses the content already in those elements. `data-cms-view="inline"` tells the page to open the editor on the page instead of in the sidebar. Save it as plain text with the exact filename `profile.htmlclay`. Double-click the file to open it through HTML Clay. If the app asks about the example folder you created, choose **Trust this folder**. ## Edit on the page Find the floating **Edit content** control at the bottom right of the page and click it. If it is missing, see [troubleshooting](#if-something-does-not-work). Click the name or bio and type. To edit the website address, click the pencil beside the link and change the value in the popover. The visible link label stays "My website" because this example maps only its destination. For a photo, click its edit handle and choose an image from your computer. You can reuse `portrait.jpg` to practice. The `data-hcms-crop="1:1"` attribute opens a square crop window. Confirm the crop. Keep the editor open until the progress bar disappears and the selected photo appears on the page, with no error below the upload control. A preview inside that control alone does not mean the upload has finished. Without `data-cms-view="inline"` (or with `data-cms-view="sidebar"`), **Edit content** opens the sidebar instead and presents the same fields together in a side panel. ## Save and check the file Check that the page shows the text, link address, and photo you intended to change. Press **Cmd+S** on macOS or **Ctrl+S** on Windows or Linux. Wait for the small **Saved** status chip at the bottom right. If it says **Couldn't save** or **Offline, not saved**, keep the tab open and [resolve the error](#if-something-does-not-work) before trying again. Do not reload while a save is failing. Closing the editor alone does not save. Reload the page. Each change you made should remain. Reopen `profile.htmlclay` in your text editor to read the saved file, discarding any stale editor buffer without saving it. Find the text you changed. It is now part of the HTML, alongside the rules and the page's styles. The editing popovers and sidebar are temporary controls. They are excluded from the saved page. Uploaded photos go into the host's uploads folder (`~/htmlclay/uploads/assets-profile/` on HTML Clay), and the HTML links them as `/_/uploads/assets-profile/...`, which keeps working when the page is renamed or moved. To take the page somewhere else with its photos, use Export as zip. To enable autosave, first save any browser edits and wait for **Saved**. Close the browser tab and reopen the latest file in your text editor. Change its opening tag to ``, save, then open the file through HTML Clay again. Subsequent edits save after a short pause. HTML Clay must still be running; autosave does not replace the save host. ## Use your own page For the same local workflow, make a copy of your page with the `.htmlclay` extension in a folder inside your home folder. Keep its local images, stylesheets, and other assets at the relative paths the page uses. Add the ClayJS script and a rules tag that points at the content you want to edit. Open the copy through HTML Clay and trust its folder when asked. If the page already loads ClayJS, add `cms` to that script's plugin list rather than adding a second loader. Start with a few fields and check each one. A rule for a heading should point at the heading, not a wrapper containing the whole page. For repeating links, cards, or gallery items, use a list rule from the [reference](https://clayjs.com/docs/plugins/cms/#lists). An AI coding agent can help write the rules. The reference includes a [configuration prompt](https://clayjs.com/docs/plugins/cms/#configure-with-a-coding-agent). Review the result and try the fields before handing the page to someone else. ## If something does not work - **No Edit content button:** confirm the filename ends in `.htmlclay` and open it through HTML Clay from your file manager. Then check the rules tag and ClayJS script. Opening the file directly as `file://` does not provide the saving connection. - **A linked page opens read-only:** open its `.htmlclay` file from your file manager. To let linked `.htmlclay` pages in this example folder open editable too, use **Trusted Folders** in HTML Clay's menu and choose **Trust a Folder**. Copy any file outside your home folder inside it, along with its assets, before opening it through the app. - **The page says the app is out of date:** update HTML Clay to **1.9.0 or newer**, then reopen the file through the app. Changing the rules or forcing edit mode does not repair an older host's saving connection. - **Edit content opens the sidebar instead of editing on the page:** check that the rules tag has `data-cms-view="inline"`. Without that attribute, the page opens the sidebar. - **A field is missing or points at the wrong content:** check its selector against the actual HTML. The sidebar can also expose fields that have no visible target on the page. - **The photo does not load:** confirm `portrait.jpg` sits beside `profile.htmlclay`. After an upload, keep the generated asset folder beside the page too. - **An upload fails:** resolve the error shown below the upload control, then choose the file again. - **A save fails:** keep the page open with your edits intact. Confirm HTML Clay is still running, then try Cmd+S or Ctrl+S again. Follow any permission or conflict message shown by the host; reloading is not a fix for an unsaved change. ## The reference Hyperclay CMS creates editing controls from rules that describe content in an HTML page. The page remains the content store. The CMS reads values from its elements and writes edits back to them. For a complete first example, use the [CMS guide](https://clayjs.com/docs/plugins/cms/). This page explains the model, rule syntax, controls, and JavaScript API. Content: [Rules](#rules), [Rich text](#rich-text), [Lists](#lists), [Views](#inline-and-sidebar-views), [Field controls](#field-controls), [Page style](#page-style-colors-fonts-and-layouts), [Templates](#custom-form-templates), [Images](#images-and-cropping). Integration: [Load the CMS](#load-the-cms), [JavaScript API](#javascript-api), [Open options](#open-options), [Events](#events), [Saving](#saving-and-ownership), [Coding-agent prompt](#configure-with-a-coding-agent), [Hosted AI](https://hyperclay.com/docs/hosted-ai/). ## A content sidebar **Setup is two tags.** Check *"A content sidebar"* in the [configurator](https://clayjs.com#configure) (or add `?plugins=cms` yourself), then tell it what's content with a rules tag: ```html ``` Each entry is a field: a name, then the selector it edits. `@src` becomes an image-upload control, `li[]` a reorderable list, and the `products` shape a list of cards. Open the sidebar with `?cms=true` on the URL or `clay.cms.open()` from a button. The same rules tag can carry more tokens (`data-rules-name="api cms"`) to also power the **data** plugin's JSON API, so you configure content once. ## The page, the rules, and the editor A rules tag gives names to the content you want to edit: ```htmlMaking small things for the web.
``` The CMS reads the named elements into a temporary editing model and builds controls for those fields. Changing a control writes to the corresponding page element. There is no separate CMS database to synchronize. The CMS controls content editing; HTML Clay or Hyperclay supplies saving and uploaded-file storage. This page covers the CMS API, not building a custom save host. ## Load the CMS ```html ``` Use a classic script tag for the loader, without `type="module"`. ClayJS exposes the CMS as `clay.cms`. Put initialization after that loader and wait for `clay.ready` before calling the CMS: ```js clay.ready.then(() => { clay.cms.open({ view: 'inline' }); }); ``` The script and its imported modules need a network connection unless you serve a complete local copy. Copying only `clay.js` does not include those modules. Packaging a self-hosted ClayJS distribution is outside this CMS reference. ### Edit mode and dependencies On a page in edit mode with a `cms` rules tag, the floating **Edit content** control opens the page's declared [view](#inline-and-sidebar-views). HTML Clay **1.9.0 or newer** supplies a `savetoken` on the root of a registered document's served HTML. Opening a file inside your home folder through the app registers it; durable folder trust is not required for that file. Files outside your home folder cannot be opened through HTML Clay. ClayJS recognizes the token as edit mode and loads the editing and saving modules. Older HTML Clay versions use a token this ClayJS build no longer accepts; update the app rather than forcing edit mode. The CMS and crop library also load outside edit mode, but RichClay, the host uploader, and saving do not. If you open a CMS session there, text elements use popovers instead of in-place RichClay editing, and image or file picks can embed data URLs. Native inputs mapped through `@value` remain native controls. See [Saving and ownership](#saving-and-ownership) for the permission boundary. ### Build compatibility This reference targets the two-view HyperCMS 0.11.0 build. After readiness, `typeof clay.cms.currentView === 'function'` checks for its view API. An older sidebar-only bundle lacks that method. Waiting for `clay.ready` does not upgrade the bundle. The [API table](#javascript-api) describes the method's return values. ## Rules Use `type="application/json"` and `data-rules-version="1"`. The default rule source is the `cms` token in `data-rules-name`. A tag can carry multiple space-separated tokens, such as `data-rules-name="cms api"`. Opening a new session throws if no tag matches the requested token or its rules version is unsupported. Correct the tag before calling `open()` again. | Rule value | Content it describes | | --- | --- | | `".name"` | Element text | | `"a.website@href"` | A link destination | | `"img.photo@src"` | An image source | | `".price@data-cents"` | An HTML attribute | | `"input.agree@checked"` | A checkbox's checked state | | `"input.name@value"` | A native input's current value | | `".bio@innerHTML"` | Markup inside an element | | `".tag[]"` | A list of scalar values | | `[".card", { "title": ".title" }]` | A list of objects, with selectors scoped to each card | | `{ "name": ".name", "bio": ".bio" }` | A group of fields | Map a text field to the element holding that text. Mapping a large wrapper as one text field can replace its child structure when you edit it. Prefer a separate rule for each piece of content. Use unique leaf keys across the rules tree. In this build, repeating a key in different groups, such as `title` and `metadata.title`, can bind both fields to the first generated control and overwrite both targets. Use distinct keys such as `pageTitle` and `metadataTitle`. ### Rich text An explicit `@innerHTML` rule preserves markup within the selected element. Use it when retaining formatting is part of the field's contract. With `richText` enabled, the default, a bare scalar selector is also upgraded to `@innerHTML` when its first matching target contains child elements. An explicit `@property` or scalar-list rule ending in `[]` is never automatically upgraded. The [sidebar and inline views](#inline-and-sidebar-views) differ inside object lists. The sidebar does not automatically upgrade those rules. Inline mode does: if any row's matching target contains markup, that child rule is upgraded for every row. For consistent behavior in both views, write `@innerHTML` explicitly on those fields. The inline toolbar offers formatting only when the field's rule can preserve it. The [`richText` option](#open-options) disables automatic upgrading when set to `false`; it does not turn an explicit `@innerHTML` rule into plain text. ### Lists An object list uses `[itemSelector, shape]`. Each matching element is one item, and the shape's selectors run within that item: ```html ``` The editor supplies add, remove, and reorder controls. New items copy the first existing item's structure. The `cms-template` item is excluded from content data and supplies the structure when the list is empty. It belongs inside the list container. In this example, a new link starts with an empty label and URL. The seed supplies structure, not default field values. Hide the seed with `[cms-template]` CSS, as above, not a `hidden` attribute or inline `display: none`. Cloning removes the `cms-template` marker, so the new content item becomes visible. A copied `hidden` attribute would keep it invisible. Without an existing item or a matching seed, adding an item fails with `EmptyListInsert` and leaves the page unchanged. Add a seed inside the list container before retrying. ## Inline and sidebar views Both views use the same rules and editing session. A page declares its view on the rules tag: ```html