H2I Workflows

H2I Overview #

The plugin’s H2I workflow is the HTML-to-output feature area inside Davix H2I. In the loaded plugin documentation, H2I is described as supporting preview and generate flows for rendering HTML into image or PDF output. It appears in the admin modal as the H2I tab and is also exposed through the plugin REST surface under /davix-h2i/v1/h2i/*.

The H2I interface includes:

• HTML template input
• CSS input
• width
• height
• format
• output mode
• suffix
• token hints

The backend implementation is documented as a PixLab-backed flow. The plugin prepares the H2I payload, applies token replacement, validates permissions and payload size, sends the request to PixLab, and then either returns preview URLs or persists generated output to the Media Library.

HTML to Image #

The plugin supports HTML-to-image rendering through the H2I feature. The loaded overview and behavior docs confirm that both preview and generate are available for HTML-based output. When the resolved format is not pdf, the H2I action is built as image output.

The H2I handlers read these core values:

• html
• css
• width
• height
• format
• attachment_id
• ids
• output_mode
• suffix

The integration and security docs also confirm the request-shape behavior for H2I:

• content type is JSON
• the request includes action
• html is required in the payload build
• css is included if non-empty
• width is included if provided
• height is included if provided
• format is included if provided

For normal HTML-to-image use, the settings and modal docs document the stored/default H2I format allowlist as:

• png
• jpeg

HTML to PDF #

The same H2I workflow can also produce PDF output. The loaded behavior docs state that the request payload uses action image or pdf when format === 'pdf'. That means H2I supports both image rendering and PDF rendering through the same feature area, with the action selected by the format state at runtime.

The plugin overview also describes H2I as HTML-to-image/PDF preview and generate endpoints, confirming that PDF is part of the H2I workflow and not a separate interface family.

For customer-facing documentation, the key distinction is:

• H2I settings store default image-oriented formats in the settings UI
• runtime can switch to PDF generation when the request format resolves to pdf

Supported H2I Fields #

The H2I workflow is documented as reading and processing these fields:

• html
• css
• width
• height
• format
• attachment_id
• ids
• output_mode
• suffix

The H2I settings page is also documented as storing defaults for:

• html
• css
• width
• height
• format

The H2I tab in settings is described as the place for default HTML, CSS, size, format, and output settings. These defaults are surfaced to the interface through DavixH2IData.defaults.h2iDefaults and DavixH2IData.defaults.h2iOutput.

From the user-facing interface perspective, the practical H2I fields are:

• HTML content
• CSS content
• output dimensions
• format
• output mode
• optional suffix
• selected media context when applicable
• token usage inside HTML and CSS

[Image placeholder — H2I tab showing HTML, CSS, width, height, format, output mode, and suffix fields]

Token Replacement System #

Token replacement is a documented core part of the H2I workflow. The supported tokens are:

• {site_name}
• {site_logo_url}
• {selected_image_url}
• {author_name}
• {date}
• {post_title}

The behavior docs explain that the token context is built by davix_h2i_token_context(), the supported token list is exposed by davix_h2i_get_supported_tokens(), and replacement is performed by davix_h2i_replace_tokens() using strtr before the outbound H2I request is sent.

The integration docs also confirm that both HTML and CSS are processed through token replacement before the final payload is sent upstream.

The user guide notes that the H2I interface includes token hints, and the settings page includes a Supported Tokens section, which makes token usage a user-visible part of the H2I workflow rather than a hidden backend-only behavior.

[Image placeholder — H2I editor showing the supported token list beside the HTML/CSS inputs]

Preview vs Generate #

Preview #

Preview is the non-persistent H2I path. The user guide documents that:

• Preview calls /h2i/preview
• it returns url in single mode or results in bulk mode
• no Media Library write happens in preview mode

The behavior docs describe the preview flow as:

• trigger: POST /davix-h2i/v1/h2i/preview
• handler chain: davix_h2i_h2i_preview() → davix_h2i_handle_h2i_request(..., 'preview')
• request validation includes REST nonce, capability checks, and per-attachment permission checks when attachment context is used
• single valid requests return a preview url
• bulk preview returns results, with each item carrying its own preview result or error text

Generate #

Generate is the persistent H2I path. The user guide documents that:

• Generate calls /h2i/generate
• it downloads and writes attachment results
• it returns media references
• in bulk mode, it can reuse preview URLs when those are supplied as preview_results or preview-item maps in the documented flow

The behavior docs describe the generate flow as:

• trigger: POST /davix-h2i/v1/h2i/generate
• handler chain: davix_h2i_h2i_generate() → davix_h2i_handle_h2i_request(..., 'generate')
• request payload is built and sent to PixLab unless a reusable preview URL is provided
• the response is parsed for output URL or binary content
• the output is downloaded or written to temp storage
• the plugin then creates or replaces the WordPress attachment according to output mode

Single vs Bulk H2I Requests #

The H2I workflow supports both single and bulk request handling.

Single Request Handling #

Single mode uses one attachment context or one H2I payload context and returns:

• preview: url
• generate: a persisted media result with attachment data in the response path

Bulk Request Handling #

Bulk mode uses ids and routes through davix_h2i_handle_h2i_bulk_request(). The loaded behavior docs describe the bulk flow as:

• reading ids
• iterating each selected attachment
• applying per-item permission checks
• building item-specific token context and request payloads
• returning results with success or error data per item

The user guide also confirms that bulk generate can reuse preview results when preview URLs are supplied, which is a bulk-specific optimization in the documented implementation.

Output Modes and Saved Media Behavior #

H2I generate uses the same output-mode model as Image generate. The settings docs confirm that H2I output settings are stored as:

• mode
• suffix

with the same sanitizer used for image output settings and the same documented defaults:

• mode: 'replace'
• suffix: ''

The user guide explains the user-facing behavior:

• replace updates the selected existing attachment file/reference and regenerates metadata
• copy creates a new attachment
• suffix is applied only in copy mode

The appendix glossary confirms that suffix is appended to the filename stem when copy mode is used in H2I output.

Replace Mode #

In replace mode, the generated H2I result is written back onto the selected existing attachment. The persistence model uses the same attachment create-or-replace helper family described elsewhere in the plugin docs. That means replace mode is the direct in-place saved-media path.

Copy Mode #

In copy mode, the generated output becomes a new Media Library attachment, and the optional suffix affects the filename stem before insertion.

[Image placeholder — H2I output mode controls showing Replace and Copy with suffix]

H2I Permission and Request Model #

The H2I workflow is protected by the plugin’s shared REST permission model. The behavior and troubleshooting docs confirm:

• header key: x_wp_nonce
• nonce action: wp_rest
• base capability: upload_files
• per-attachment permission: current_user_can( 'edit_post', $attachment_id ) when the request references attachments

This means H2I is an authenticated WordPress-admin and media workflow, not an anonymous frontend renderer in the documented plugin implementation.

H2I Payload Size Rules #

The H2I workflow has a documented payload-size rule based on the combined size of HTML and CSS. The loaded docs confirm:

• option key: davix_h2i_h2i_max_payload_kb
• default setting value shown in the UI is 200
• hard maximum clamp is 500 KB
• runtime compares strlen(html) + strlen(css) to the configured byte limit
• oversized single requests return WP_Error( 'davix_h2i_payload_too_large', ..., 413 )
• bulk requests can produce per-item payload-too-large errors rather than one global success response

This payload check is part of the H2I workflow itself, so users configuring large HTML and CSS templates need to account for it when building reusable defaults and bulk workflows.

Saved Media Sources and Attachment Context #

The H2I token system can use media and WordPress context during rendering. The token list includes {selected_image_url}, which means selected media context can influence generated output. The request handlers also read attachment_id and ids, which ties the H2I workflow directly to selected attachments in single and bulk scenarios.

When generate succeeds, the output is downloaded or otherwise converted into a file that is then persisted into the Media Library using the selected replace or copy behavior.

Common H2I Workflow Errors #

The troubleshooting and behavior docs document the main H2I-specific failure modes.

davix_h2i_payload_too_large #

Raised when the combined HTML and CSS content exceeds the configured payload limit.

davix_h2i_invalid_nonce #

Raised when the x_wp_nonce header is missing or invalid for action wp_rest.

davix_h2i_forbidden_attachment #

Raised when the current user does not have permission to edit one of the referenced attachments.

Missing Output URL or Output Content #

The H2I generate flow requires a usable output URL or reusable output content. Where neither exists, the documented behavior is failure for the affected request or item.

End-to-End H2I Workflow Summary #

The source-backed H2I workflow is:

1. Open the H2I tab in the Davix H2I modal.
2. Enter HTML and optional CSS.
3. Select dimensions, format, and output mode.
4. Use supported tokens where needed inside the template.
5. Run Preview to receive a preview URL or bulk preview results without writing media.
6. Run Generate to persist the result into the Media Library using replace or copy mode.
7. In bulk mode, optionally reuse preview results when generating.