SelectorHandlerPlugin Schema

Schema definition for the Selector Handler Plugin, which provides CSS selector-based HTML manipulation via HTTP Range headers.

Schema Information

Property	Value
Schema URL	`https://rustybeam.net/schema/SelectorHandlerPlugin`
Parent Schema	https://rustybeam.net/schema/HandlerPlugin
Description	CSS selector processing for HTML manipulation using HTTP Range headers

Properties

Property	Type	Cardinality	Description
name	https://rustybeam.net/schema/Text	0..1	Plugin instance name for logging and identification. Defaults to "selector-handler" if not specified.
root_dir	https://rustybeam.net/schema/Text	0..1	Root directory for serving files. Defaults to "." (current directory). Used as base path for file resolution.

Usage Examples

Basic Selector Handler Configuration

<tr itemscope itemtype="https://rustybeam.net/schema/SelectorHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_selector_handler.so</span>
</tr>

Custom Root Directory

<tr itemscope itemtype="https://rustybeam.net/schema/SelectorHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_selector_handler.so</span>
    <span itemprop="root_dir">./examples/guestbook</span>
    <span itemprop="name">guestbook_selector</span>
</tr>

CSS Selector Usage

The Selector Handler Plugin processes HTTP Range headers with CSS selector syntax:

Client-Side Usage Examples

// Fetch specific table rows
fetch('/data.html', {
    headers: {
        'Range': 'selector=table tr.user'
    }
});

// Get form inputs only
fetch('/form.html', {
    headers: {
        'Range': 'selector=form input, form select'
    }
});

// Extract microdata items
fetch('/config.html', {
    headers: {
        'Range': 'selector=[itemtype="https://rustybeam.net/schema/Plugin"]'
    }
});

Supported CSS Selectors

Element selectors: div, table, tr
Class selectors: .user, .config-row
ID selectors: #header, #main-content
Attribute selectors: [itemtype], [data-id="123"]
Descendant selectors: table tr, form input
Multiple selectors: h1, h2, h3
Pseudo-selectors: :first-child, :last-of-type

Range Header Format
The plugin intentionally "abuses" the HTTP Range header for CSS selector processing. Use the format: Range: selector={css-selector}. Only HTML files are processed for selectors; other file types are served normally.

Schema Inheritance

This schema inherits from the HandlerPlugin schema, which provides:

config_file - Configuration file path
rulesfile - Rules file path

And ultimately from the base Plugin schema, which provides:

library - Plugin library path
plugin - Base plugin reference property

HTML Structure Preservation

The Selector Handler Plugin includes special handling for HTML elements that require structural preservation:

Table elements: <td>, <tr>, <thead>, <tbody>
List elements: <li>, <ol>, <ul>
Form elements: <option>, <optgroup>
Document structure: Maintains proper HTML hierarchy

Validation Rules

The root_dir property must be a valid directory path
The directory specified in root_dir must be readable by the server
The name property should be unique if multiple selector handler plugins are used
CSS selectors in Range headers must be valid CSS selector syntax
Only HTML files (Content-Type: text/html) are processed for selectors

Plugin Pipeline Placement
The Selector Handler Plugin should be placed after authentication and authorization plugins but before the File Handler Plugin. This ensures that selector processing happens on authorized content.

Use Cases

Microdata Extraction: Extract configuration data from HTML using itemtype selectors
Partial Page Updates: Fetch specific page sections for AJAX updates
Content API: Create REST-like APIs from HTML content using selectors
Data Integration: Extract structured data from HTML for processing
Progressive Enhancement: Load page sections incrementally
Component Architecture: Fetch individual UI components

Response Format

When a selector matches elements, the plugin returns:

Content-Type: text/html (preserves HTML structure)
Content-Range: selector {css-selector} (documents the selector used)
Body: Matched HTML elements with preserved structure
Status: 206 Partial Content (for selector matches) or 200 OK (for full files)

Integration with Other Plugins

File Handler Plugin: Works together for file serving and selector processing
Authorization Plugin: Ensures selector access follows authorization rules
Basic Auth Plugin: Protects sensitive HTML content from unauthorized selector access
CORS Plugin: Enables cross-origin selector requests for API usage
Compression Plugin: Compresses selector response content

JavaScript Integration

// DOM-aware primitives integration
document.querySelector('[itemtype="https://rustybeam.net/schema/Plugin"]')
    .POST(newPluginHTML)
    .then(response => {
        // Plugin added successfully
    });

// Fetch configuration data
async function getPluginConfig() {
    const response = await fetch('/config.html', {
        headers: {
            'Range': 'selector=[itemtype="https://rustybeam.net/schema/Plugin"]'
        }
    });
    return response.text();
}