domx

https://domx.software/docs.html
Admin
domx is a lightweight JavaScript library for syncing DOM state with JavaScript objects, featuring...
Tokens:1,684
Snippets:22
Trust Score:3.2
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install DOMX via npm

Source: https://domx.software/docs.html/index

Installs the DOMX library using the Node Package Manager (npm). This is the recommended method for project integration.

```bash
npm install domx
```

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

### HTMX Integration Setup with DOMX

Source: https://domx.software/docs.html/index

Details the setup required to integrate DOMX with HTMX. This involves including both libraries and defining a manifest object that can be referenced by the `dx-manifest` attribute on an HTML element.

```html
<script src="https://unpkg.com/htmx.org"></script>
<script src="https://unpkg.com/domx/dist/domx-htmx.min.js"></script>

<script>
const manifest = {
  searchQuery: { selector: '#search', read: 'value' },
  sortDir: { selector: '[data-sort]', read: 'attr:data-sort-dir' }
};
</script>

<body hx-ext="domx" dx-manifest="manifest">
  ...
</body>
```

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

### DOMX Quick Start: Collect, Apply, Observe State

Source: https://domx.software/docs.html/index

Demonstrates the core functionality of DOMX: defining a manifest to map UI elements to state labels, collecting the current state from the DOM, applying new state to the DOM, and observing changes in the DOM state.

```javascript
import { collect, apply, observe } from 'domx';

// Define a manifest
const manifest = {
  username: { selector: '#username', read: 'value', write: 'value' },
  rememberMe: { selector: '#remember', read: 'checked', write: 'checked' }
};

// Collect state from DOM
const state = collect(manifest);
// { username: "alice", rememberMe: true }

// Apply state to DOM
apply(manifest, { username: "bob" });

// Observe changes
const unsubscribe = observe(manifest, (state) => {
  console.log('State changed:', state);
});

// Stop observing
unsubscribe();
```

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

### DOMX apply() Function Example

Source: https://domx.software/docs.html/index

Demonstrates the `apply` function, which takes a manifest and a state object to update the corresponding DOM elements. It only modifies elements that have a `write` property defined in the manifest.

```javascript
apply(manifest, { username: "alice", theme: "dark" });
```

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

### DOMX collect() Function Example

Source: https://domx.software/docs.html/index

Shows how to use the `collect` function to read the current state of DOM elements defined in a manifest. It returns an object where keys are state labels and values are the extracted data. Handles single and multiple element selectors.

```javascript
const state = collect(manifest);
// { searchQuery: "hello", sortDir: "asc" }
```

```javascript
const manifest = {
  tags: { selector: '.tag', read: 'text' }
};
collect(manifest);
// { tags: ["JavaScript", "TypeScript", "Python"] }
```

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

### DOMX observe() Function Example

Source: https://domx.software/docs.html/index

Illustrates the `observe` function, which monitors DOM changes based on a manifest and executes a callback function whenever the state changes. It automatically determines the appropriate event listener (e.g., 'input', 'change', or MutationObserver) based on the 'read' type. Returns a function to stop observing.

```javascript
const unsubscribe = observe(manifest, (state) => {
  console.log('State changed:', state);
});

// Later: stop observing
unsubscribe();
```

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

### HTMX Triggering Search on DOMX State Change

Source: https://domx.software/docs.html/index

An example of using HTMX to automatically trigger an AJAX request whenever the state managed by DOMX changes. The `hx-trigger="dx:change"` attribute listens for the custom DOMX event.

```html
<!-- Auto-search when state changes -->
<div hx-post="/api/search"
     hx-trigger="dx:change"
     hx-target="#results">
  <input id="search" type="text">
  <div id="results"></div>
</div>
```

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

### DOMX send() Function with Fetch API

Source: https://domx.software/docs.html/index

Demonstrates the `send` function, which collects state using a manifest, caches it to localStorage, and then sends it to a specified URL using the Fetch API. It allows for custom request headers and options.

```javascript
const response = await send('/api/save', manifest, {
  headers: { 'X-Custom': 'value' }
});
```

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

### DOMX on() Function for Raw MutationRecords

Source: https://domx.software/docs.html/index

Provides a low-level subscription mechanism using the `on` function to directly access raw MutationRecords. This is intended for advanced use cases, such as framework integrations.

```javascript
const unsubscribe = on((mutations) => {
  // Process raw MutationRecords
});
```

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

### Include DOMX via CDN

Source: https://domx.software/docs.html/index

Includes the DOMX library directly in an HTML document using a Content Delivery Network (CDN) link. Suitable for quick prototyping or simple web pages.

```html
<script src="https://unpkg.com/domx"></script>
```

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

### DOMX Custom Manifest Read/Write Functions

Source: https://domx.software/docs.html/index

Illustrates how to use custom functions within a DOMX manifest for complex state extraction (read) and assignment (write) to DOM elements. This allows for non-standard data handling.

```javascript
const manifest = {
  combined: {
    selector: '#thing',
    read: (el) => `${el.dataset.foo}-${el.dataset.bar}`,
    write: (el, val) => {
      const [foo, bar] = val.split('-');
      el.dataset.foo = foo;
      el.dataset.bar = bar;
    }
  }
};
```

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

### DOMX replay() Function for Cached Requests

Source: https://domx.software/docs.html/index

Explains the `replay` function, which attempts to re-send a previously cached request from localStorage. It's useful for recovering from page refreshes or network interruptions. Returns null if no valid cache exists or if the cache has expired (default 5 minutes).

```javascript
// On page load
const response = await replay();
if (response?.ok) {
  const html = await response.text();
  container.innerHTML = html;
}
```

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

### Include DOMX for HTMX via CDN

Source: https://domx.software/docs.html/index

Includes the DOMX library with HTMX integration support via a CDN link. This version enables DOMX attributes and events within HTMX-powered applications.

```html
<script src="https://unpkg.com/domx/dist/domx-htmx.min.js"></script>
```

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

### DOMX clearCache() Function

Source: https://domx.software/docs.html/index

A simple utility function to clear any cached request data stored in the browser's localStorage by the `send` function.

```javascript
clearCache();
```
Tokens:
Raw