# How to use

After installation, you can use hypermedia template partials in any theme.

This plugin will include the active hypermedia library by default, locally from the plugin folder. Libraries like HTMX, Alpine.js, Hyperscript, and Datastar are supported.

The plugin has an opt-in option, not enforced, to include these third-party libraries from a CDN (using the unpkg.com service). You must explicitly enable this option for privacy and security reasons.

Create a `hypermedia` folder in your theme's root directory. This plugin includes a demo folder that you can copy to your theme. Don't put your templates inside the demo folder located in the plugin's directory, because it will be deleted when you update the plugin.

Inside your `hypermedia` folder, create as many templates as you want. All files must end with `.hp.php`.

For example:

```
hypermedia/live-search.hp.php
hypermedia/related-posts.hp.php
hypermedia/private/author.hp.php
hypermedia/private/author-posts.hp.php
```

Check the demo template at `hypermedia/demo.hp.php` to see how to use it.

For a full working example of REST endpoint usage, see the showcase/demo theme at [EstebanForge/Hypermedia-Theme-WordPress](https://github.com/EstebanForge/Hypermedia-Theme-WordPress).

Then, in your theme, use your Hypermedia library to GET/POST to the endpoint generated by `hp_get_endpoint_url('template-name')` (do not hardcode `/wp-html/v1/`).

**Example:**

```php
// Recommended: always use the helper
$url = hp_get_endpoint_url('live-search');
// Output: http://your-site.com/wp-html/v1/live-search
```

```
/wp-html/v1/live-search
/wp-html/v1/related-posts
/wp-html/v1/private/author
/wp-html/v1/private/author-posts
```

## Passing Data to Templates

You can pass data to templates using URL parameters via GET or POST.

```
/wp-html/v1/live-search?search=hello
/wp-html/v1/related-posts?category_id=5
```

All parameters and values are available inside your template as an array named `$hp_vals`.

## No Swap Response Templates

Hypermedia libraries support templates that do not return HTML but run server-side logic and optionally respond via headers. See HTMX “Swapping” docs for background.

For convenience, use the `noswap/` endpoint convention:

```
/wp-html/v1/noswap/save-user?user_id=5&name=John&last_name=Doe
/wp-html/v1/noswap/delete-user?user_id=5
```

Template files are located under `hypermedia/noswap/` in your theme:

```
hypermedia/noswap/save-user.hp.php
hypermedia/noswap/delete-user.hp.php
```

You can pass data to these templates the same way as regular templates. Alternatively, you can handle non-visual actions in regular templates; `noswap/` is just a convenience.

## Helper Functions

The plugin provides a comprehensive set of helper functions for developers to interact with hypermedia template partials and manage responses. All functions are designed to work with HTMX, Alpine Ajax, and Datastar.

### URL Generation Functions

**`hp_get_endpoint_url(string $template_path = ''): string`**

Generates the full URL for your hypermedia template partials. Automatically adds the `/wp-html/v1/` prefix and applies proper URL formatting. Always use this helper for endpoint URLs.

```php
// Basic usage
echo hp_get_endpoint_url('live-search');
// Output: http://your-site.com/wp-html/v1/live-search

// With subdirectories
echo hp_get_endpoint_url('admin/user-list');
// Output: http://your-site.com/wp-html/v1/admin/user-list

// With namespaced templates (plugin/theme specific)
echo hp_get_endpoint_url('my-plugin:dashboard/stats');
// Output: http://your-site.com/wp-html/v1/my-plugin:dashboard/stats
```

**`hp_endpoint_url(string $template_path = ''): void`**

Same as `hp_get_endpoint_url()` but echoes the result directly. Useful for template output.

```php
// HTMX usage
<div hx-get="<?php hp_endpoint_url('search-results'); ?>">
    Loading...
</div>

// Datastar usage
<div data-on:click="@get('<?php hp_endpoint_url('user-profile'); ?>')">
    Load Profile
</div>

// Alpine Ajax usage
<div @click="$ajax('<?php hp_endpoint_url('dashboard-stats'); ?>')">
    Refresh Stats
</div>
```

### Response Management Functions

**`hp_send_header_response(array $data = [], string $action = null): void`**

Sends hypermedia-compatible header responses for non-visual actions. Automatically validates nonces and terminates execution. Perfect for "noswap" templates that perform backend actions without returning HTML.

```php
// Success response (works with HTMX/Alpine Ajax)
hp_send_header_response([
    'status' => 'success',
    'message' => 'User saved successfully',
    'user_id' => 123
], 'save_user');

// Error response
hp_send_header_response([
    'status' => 'error',
    'message' => 'Invalid email address'
], 'save_user');

// Silent success (no user notification)
hp_send_header_response([
    'status' => 'silent-success',
    'data' => ['updated_count' => 5]
]);

// For Datastar SSE endpoints, use the ds helpers instead:
// hypermedia/save-user-sse.hp.php

// Get user data from Datastar signals
$signals = hp_ds_read_signals();
$user_data = $signals; // Signals contain the form data
$result = save_user($user_data);

if ($result['success']) {
    // Update UI with success state
    hp_ds_patch_elements('<div class="success">User saved!</div>', ['selector' => '#message']);
    hp_ds_patch_signals(['user_saved' => true, 'user_id' => $result['user_id']]);
} else {
    // Show error message
    hp_ds_patch_elements('<div class="error">Save failed: ' . $result['error'] . '</div>', ['selector' => '#message']);
    hp_ds_patch_signals(['user_saved' => false, 'error' => $result['error']]);
}
```

**`hp_die(string $message = '', bool $display_error = false): void`**

Terminates template execution with a 200 status code (allowing hypermedia libraries to process the response) and sends error information via headers.

```php
// Die with hidden error message
hp_die('Database connection failed');

// Die with visible error message
hp_die('Please fill in all required fields', true);
```