Hooks & Filters

The supported API for installed WordPress plugins that extend Lay Theme without changing theme files.

This is a developer reference. Only the functions and hooks listed here are part of Lay Theme's supported plugin API. Other hooks found inside the theme are implementation details and may change in an update.

This does not make your website publicly writable. These functions are not web endpoints and cannot be called by website visitors. They are available to server-side PHP code, normally inside a WordPress plugin installed by an administrator. The Browser Bridge does not gain additional permissions from this reference: its write operations remain restricted to authenticated administrators and continue to use the validate → confirm → apply workflow.

Before adding custom code, check whether AI Mode already supports the task. Project-specific PHP, scheduled jobs, exports, admin screens, custom URLs and new data models belong in a separate plugin. Learn how to expose that plugin safely to an AI assistant under Plugin Extensions.

Each entry includes a reference signature and a separate PHP usage example. Put the code in your own WordPress plugin. Examples are independent: replace the sample post types, group IDs, field IDs and URLs with those configured on your site. Function examples define helpers for your plugin to call after Lay Theme has loaded; write helpers belong in authenticated, nonce-checked handlers.

Shop and WooCommerce

For visual changes, start with Custom Shop Styles. For functionality, use an installed WordPress plugin. Lay's classic Product, Cart and Checkout templates retain WooCommerce's standard hooks, including woocommerce_single_product_summary, woocommerce_after_single_product_summary, woocommerce_checkout_before_customer_details, woocommerce_checkout_after_order_review and cart item filters. See the official WooCommerce template/hook documentation.

The following additional hooks cover Lay Theme's native Side Cart and product thumbnail overlays. Side Cart hooks run only when the native Lay provider is active. Header/footer hooks also run during fragment replacement, so render repeatable markup without side effects.

lay_native_sidecart_options

Filter

Filter display labels and visibility options for the native Lay Side Cart. Keep commerce controls and accessibility labels intact.

Filter signature
apply_filters( 'lay_native_sidecart_options', array $options )

Change the native cart heading without removing other options.

Usage example · PHP
add_filter( 'lay_native_sidecart_options', function ( $options ) {
    $options['sct-cart-heading'] = 'Your selection';
    return $options;
} );

lay_native_sidecart_container_classes

Filter

Append sanitized classes to the native Side Cart dialog.

Filter signature
apply_filters(
    'lay_native_sidecart_container_classes',
    string[] $classes,
    WC_Cart $cart
)

Add a class your plugin can use to style the drawer.

Usage example · PHP
add_filter( 'lay_native_sidecart_container_classes', function ( $classes, $cart ) {
    $classes[] = 'studio-cart';
    return array_values( array_unique( $classes ) );
}, 10, 2 );

lay_native_sidecart_before_header

Action

Output inside the native Side Cart header before its contents.

Action signature
do_action( 'lay_native_sidecart_before_header', WC_Cart $cart )

Add a short announcement at the start of the header.

Usage example · PHP
add_action( 'lay_native_sidecart_before_header', function ( $cart ) {
    echo '<p class="studio-cart-announcement">Made by independent makers.</p>';
} );

These hooks also run for AJAX cart refreshes. Output repeatable markup; do not create orders or change the cart here.

lay_native_sidecart_after_header

Action

Output inside the native Side Cart header after its contents.

Action signature
do_action( 'lay_native_sidecart_after_header', WC_Cart $cart )

Add a packing note after the header contents.

Usage example · PHP
add_action( 'lay_native_sidecart_after_header', function ( $cart ) {
    echo '<p class="studio-cart-note">Every order is packed with care.</p>';
} );

These hooks also run for AJAX cart refreshes. Output repeatable markup; do not create orders or change the cart here.

lay_native_sidecart_before_body

Action

Output before the native Side Cart product list or empty state.

Action signature
do_action( 'lay_native_sidecart_before_body', WC_Cart $cart )

Show an item count before the product list.

Usage example · PHP
add_action( 'lay_native_sidecart_before_body', function ( $cart ) {
    printf( '<p>%s items in your selection.</p>', esc_html( $cart->get_cart_contents_count() ) );
} );

These hooks also run for AJAX cart refreshes. Output repeatable markup; do not create orders or change the cart here.

lay_native_sidecart_after_body

Action

Output after the native Side Cart body, before its footer.

Action signature
do_action( 'lay_native_sidecart_after_body', WC_Cart $cart )

Add a help link below the products.

Usage example · PHP
add_action( 'lay_native_sidecart_after_body', function ( $cart ) {
    printf( '<p><a href="%s">Questions about your order?</a></p>', esc_url( home_url( '/contact/' ) ) );
} );

These hooks also run for AJAX cart refreshes. Output repeatable markup; do not create orders or change the cart here.

lay_native_sidecart_before_footer

Action

Output inside the native Side Cart footer before totals and buttons.

Action signature
do_action( 'lay_native_sidecart_before_footer', WC_Cart $cart )

Add a delivery note before totals and buttons.

Usage example · PHP
add_action( 'lay_native_sidecart_before_footer', function ( $cart ) {
    echo '<p class="studio-delivery-note">Dispatch within 2–3 working days.</p>';
} );

These hooks also run for AJAX cart refreshes. Output repeatable markup; do not create orders or change the cart here.

lay_native_sidecart_after_footer

Action

Output after the native Side Cart footer.

Action signature
do_action( 'lay_native_sidecart_after_footer', WC_Cart $cart )

Add a return-policy link after the footer.

Usage example · PHP
add_action( 'lay_native_sidecart_after_footer', function ( $cart ) {
    printf( '<p><a href="%s">Read our return policy</a></p>', esc_url( home_url( '/returns/' ) ) );
} );

These hooks also run for AJAX cart refreshes. Output repeatable markup; do not create orders or change the cart here.

lay_native_sidecart_before_product

Action

Output inside a Side Cart product before its native contents.

Action signature
do_action( 'lay_native_sidecart_before_product', array $product_args )

Mark items sold individually before their native contents.

Usage example · PHP
add_action( 'lay_native_sidecart_before_product', function ( $args ) {
    if ( ! empty( $args['sold_individually'] ) ) {
        echo '<span class="studio-item-note">One per order</span>';
    }
} );

lay_native_sidecart_after_product

Action

Output inside a Side Cart product after its native contents.

Action signature
do_action( 'lay_native_sidecart_after_product', array $product_args )

Show a product-specific note after the native item contents.

Usage example · PHP
add_action( 'lay_native_sidecart_after_product', function ( $args ) {
    $note = get_post_meta( $args['product']->get_id(), '_studio_cart_note', true );
    if ( is_string( $note ) && $note !== '' ) {
        echo '<p class="studio-item-note">' . esc_html( $note ) . '</p>';
    }
} );

The optional _studio_cart_note value belongs to your plugin; it is not a Lay Theme storage key.

lay_native_sidecart_product_args

Filter

Filter native Side Cart product display data. Keep item keys and quantity limits valid.

Filter signature
apply_filters(
    'lay_native_sidecart_product_args',
    array $args,
    WC_Product $product,
    array $cart_item,
    string $cart_item_key
)

Append the product SKU to its display metadata.

Usage example · PHP
add_filter( 'lay_native_sidecart_product_args', function ( $args, $product, $item, $key ) {
    if ( $product->get_sku() !== '' ) {
        $args['meta'] .= '<p>SKU: ' . esc_html( $product->get_sku() ) . '</p>';
    }
    return $args;
}, 10, 4 );

lay_native_sidecart_item_updated

Action

React after a successful native Side Cart quantity update and totals recalculation.

Action signature
do_action(
    'lay_native_sidecart_item_updated',
    string $cart_key,
    int $quantity,
    array $cart_item
)

Remember the last cart update in the WooCommerce session.

Usage example · PHP
add_action( 'lay_native_sidecart_item_updated', function ( $key, $quantity, $item ) {
    if ( WC()->session ) {
        WC()->session->set( 'studio_last_cart_update', array(
            'product_id' => (int) $item['product_id'],
            'quantity'   => (int) $quantity,
        ) );
    }
}, 10, 3 );

This notification runs after the update. Avoid triggering another quantity update from the same callback.

lay_woocommerce_on_thumbnail_image

Filter

Filter overlay markup on a native product thumbnail.

Filter signature
apply_filters(
    'lay_woocommerce_on_thumbnail_image',
    string $markup,
    WC_Product $product
)

Append an out-of-stock label inside a product thumbnail.

Usage example · PHP
add_filter( 'lay_woocommerce_on_thumbnail_image', function ( $markup, $product ) {
    if ( ! $product->is_in_stock() ) {
        $markup .= '<span class="studio-stock-label">Currently unavailable</span>';
    }
    return $markup;
}, 10, 2 );
add_action( 'lay_native_sidecart_after_header', function ( $cart ) {
    echo '<p class="studio-cart-note">Packed with care by our studio.</p>';
} );

add_filter( 'lay_native_sidecart_container_classes', function ( $classes, $cart ) {
    $classes[] = 'studio-cart';
    return $classes;
}, 10, 2 );

JavaScript events on jQuery(document.body): lay_sidecart_opened, lay_sidecart_closed, and lay_sidecart_updated (second argument: fragment response). Existing WooCommerce events include added_to_cart, removed_from_cart, wc_fragments_refreshed, updated_cart_totals and updated_checkout. Bind delegated listeners because fragments replace DOM nodes. Lay also emits woocommerce_initialized and variation_selected through window.laytheme.

jQuery(document.body).on('lay_sidecart_updated.studio', function(event, response) {
    // Read the freshly rendered Side Cart here.
});

The same signatures and JavaScript event information are supplied to connected assistants by GET /wp-json/laytheme/v1/ai/hooks?category=shop. These hooks are server-side plugin integration points; they do not give website visitors editing access.

Plugin Functions

lay_ai_register_extension_provider

Function

Expose focused plugin resources and reversible actions to AI Mode.

Function signature
lay_ai_register_extension_provider( string $id, array $definition )

Register a small read-only resource for the connected assistant.

Usage example · PHP
add_action( 'lay_ai_register_extensions', function () {
    if ( ! function_exists( 'lay_ai_register_extension_provider' ) ) {
        return;
    }
    lay_ai_register_extension_provider( 'studio-info', array(
        'name' => 'Studio information',
        'resources' => array(
            'site' => array(
                'description' => 'The public site name.',
                'callback' => function () {
                    return array( 'name' => get_bloginfo( 'name' ) );
                },
            ),
        ),
    ) );
} );

The normal AI Mode read permission applies. For validated write actions, see Plugin Extensions.

lay_get_gridder_document

Function

Read a normalized Desktop or Phone Gridder document.

Function signature
lay_get_gridder_document( int $post_id, string $layout = 'desktop' )

Count the native Desktop Gridder elements for the current post.

Usage example · PHP
function studio_count_gridder_elements( $post_id ) {
    if ( ! function_exists( 'lay_get_gridder_document' ) ) {
        return 0;
    }
    $document = lay_get_gridder_document( $post_id, 'desktop' );
    if ( is_wp_error( $document ) || ! is_array( $document ) ) {
        return 0;
    }
    return count( $document['cont'] ?? array() );
}

An unavailable layout can be null. Test for an array as well as WP_Error.

lay_update_gridder_document

Function

Save through Lay Theme normalization, preview generation and cache invalidation.

Function signature
lay_update_gridder_document(
    int $post_id,
    array $document,
    string $layout = 'desktop',
    string $source = 'plugin'
)

Create a plugin helper that changes only the first Desktop row gutter.

Usage example · PHP
function studio_set_first_row_gutter( $post_id ) {
    if ( ! function_exists( 'lay_update_gridder_document' ) ) {
        return new WP_Error( 'studio_missing_lay', 'Update Lay Theme first.' );
    }
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return new WP_Error( 'studio_forbidden', 'This post is not editable.' );
    }
    $document = lay_get_gridder_document( $post_id, 'desktop' );
    if ( is_wp_error( $document ) || ! is_array( $document ) ) {
        return new WP_Error( 'studio_no_layout', 'Choose a Desktop Gridder layout.' );
    }
    if ( ! array_key_exists( 0, $document['rowGutters'] ?? array() ) ) {
        return new WP_Error( 'studio_no_gutter', 'This layout has no row gutter.' );
    }
    $document['rowGutters'][0] = 4;
    return lay_update_gridder_document( $post_id, $document, 'desktop', 'studio' );
}

Call this helper from your authenticated, nonce-checked admin handler. It preserves the rest of the document and the Phone layout.

lay_get_content_context

Function

Read the structured post context used by Liquid-compatible Custom Elements and Views.

Function signature
lay_get_content_context( int $post_id )

Render a link using Lay’s structured post title and URL.

Usage example · PHP
function studio_project_link( $post_id ) {
    if ( ! function_exists( 'lay_get_content_context' ) ) {
        return '';
    }
    $context = lay_get_content_context( $post_id );
    if ( is_wp_error( $context ) || ! is_array( $context ) ) {
        return '';
    }
    return sprintf( '<a href="%s">%s</a>',
        esc_url( $context['url'] ?? '' ),
        esc_html( $context['title'] ?? '' )
    );
}

lay_get_custom_field_group_values

Function

Read one native Custom Field group without accessing private meta.

Function signature
lay_get_custom_field_group_values(
    int $post_id,
    string $group_id,
    bool $include_defaults = true
)

Read a configured project group and return its client label.

Usage example · PHP
function studio_client_label( $post_id ) {
    if ( ! function_exists( 'lay_get_custom_field_group_values' ) ) {
        return '';
    }
    $values = lay_get_custom_field_group_values( $post_id, 'project' );
    if ( is_wp_error( $values ) ) {
        return '';
    }
    return esc_html( $values['client'] ?? '' );
}

Use a native Custom Field group with ID project and a text field with ID client, or replace both IDs with your own.

lay_update_custom_field_group_values

Function

Validate and save one native Custom Field group.

Function signature
lay_update_custom_field_group_values(
    int $post_id,
    string $group_id,
    array $values,
    bool $partial = true
)

Update one configured field while retaining the other saved values.

Usage example · PHP
function studio_save_client( $post_id, $client ) {
    if ( ! function_exists( 'lay_update_custom_field_group_values' ) ) {
        return new WP_Error( 'studio_missing_lay', 'Update Lay Theme first.' );
    }
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return new WP_Error( 'studio_forbidden', 'This post is not editable.' );
    }
    return lay_update_custom_field_group_values(
        $post_id, 'project',
        array( 'client' => sanitize_text_field( $client ) ),
        true
    );
}

The project group and client text field must already exist. Call this from a nonce-checked admin handler and handle a possible WP_Error.

lay_prepare_gridder_rows

Function

Prepare the canonical row objects for a Gridder document.

Function signature
lay_prepare_gridder_rows( array $document, bool $cover_active = false )

Count the prepared native rows of an existing presentation.

Usage example · PHP
function studio_count_presentation_rows( $post_id ) {
    if ( ! function_exists( 'lay_prepare_gridder_rows' ) ) {
        return 0;
    }
    $document = lay_get_gridder_document( $post_id, 'desktop' );
    if ( is_wp_error( $document ) || ! is_array( $document ) ) {
        return 0;
    }
    $rows = lay_prepare_gridder_rows( $document, false );
    return is_array( $rows ) ? count( $rows ) : 0;
}

Pass a document obtained through lay_get_gridder_document() and handle WP_Error. The returned rows retain native row attributes and element columns.

lay_get_gridder_rows_margin_css

Function

Generate native row-gutter CSS for prepared rows.

Function signature
lay_get_gridder_rows_margin_css(
    array $document,
    array $rows,
    string $selector,
    bool $is_phone = false
)

Return native row-spacing style markup for a composed presentation.

Usage example · PHP
function studio_presentation_spacing( $document ) {
    if ( ! function_exists( 'lay_get_gridder_rows_margin_css' ) ) {
        return '';
    }
    $rows = lay_prepare_gridder_rows( $document );
    if ( is_wp_error( $rows ) || ! is_array( $rows ) ) {
        return '';
    }
    $css = lay_get_gridder_rows_margin_css(
        $document, $rows, '.studio-presentation', false
    );
    return is_wp_error( $css ) ? '' : $css;
}

The result contains a complete style element, including its media query. Output it in your plugin’s trusted layout/head rendering; do not pass it to wp_add_inline_style() as raw CSS. Use a wrapper matching .studio-presentation.

lay_get_site_chrome_visibility

Function

Read per-post site title, menu and footer visibility.

Function signature
lay_get_site_chrome_visibility( int $post_id )

Check whether Lay’s footer is enabled for a post.

Usage example · PHP
function studio_post_shows_footer( $post_id ) {
    if ( ! function_exists( 'lay_get_site_chrome_visibility' ) ) {
        return false;
    }
    $visibility = lay_get_site_chrome_visibility( $post_id );
    return ! is_wp_error( $visibility ) && ! empty( $visibility['footer'] );
}

lay_update_site_chrome_visibility

Function

Update per-post site title, menu and footer visibility.

Function signature
lay_update_site_chrome_visibility( int $post_id, array $visibility )

Provide a controlled helper that hides chrome for a presentation.

Usage example · PHP
function studio_hide_presentation_chrome( $post_id ) {
    if ( ! function_exists( 'lay_update_site_chrome_visibility' ) ) {
        return new WP_Error( 'studio_missing_lay', 'Update Lay Theme first.' );
    }
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return new WP_Error( 'studio_forbidden', 'This post is not editable.' );
    }
    return lay_update_site_chrome_visibility( $post_id, array(
        'site_title' => false,
        'menu' => false,
        'footer' => false,
    ) );
}

Call this from a nonce-checked admin handler. Additional menus use menu_2, menu_3 and menu_4 and are left unchanged here.

AI Mode, Content Types, Gridder and Content

lay_ai_register_extensions

Action

Register AI Mode extension providers.

Action signature
do_action( $hook )

Publish a read-only count after Lay’s provider API is ready.

Usage example · PHP
add_action( 'lay_ai_register_extensions', function () {
    if ( ! function_exists( 'lay_ai_register_extension_provider' ) ) {
        return;
    }
    lay_ai_register_extension_provider( 'studio-projects', array(
        'name' => 'Studio projects',
        'resources' => array(
            'count' => array(
                'description' => 'Number of published projects.',
                'callback' => function () {
                    return array( 'published' => (int) wp_count_posts( 'post' )->publish );
                },
            ),
        ),
    ) );
} );

lay_add_gridder_meta_boxes_to

Filter

Add a registered WordPress post type to the native Gridder editor.

Filter signature
string[] $post_types

Add the Gridder editor to an existing Exhibition post type.

Usage example · PHP
add_filter( 'lay_add_gridder_meta_boxes_to', function ( $post_types ) {
    if ( post_type_exists( 'exhibition' ) ) {
        $post_types[] = 'exhibition';
    }
    return array_values( array_unique( $post_types ) );
} );

Your plugin must register the exhibition post type first.

lay_gridder_post_types

Filter

Add a registered WordPress post type to every canonical Gridder consumer, including editor and frontend.

Filter signature
string[] $post_types

Include an existing Exhibition post type in the canonical Gridder consumers.

Usage example · PHP
add_filter( 'lay_gridder_post_types', function ( $post_types ) {
    if ( post_type_exists( 'exhibition' ) ) {
        $post_types[] = 'exhibition';
    }
    return array_values( array_unique( $post_types ) );
} );

Your plugin must register the exhibition post type first.

lay_ai_gridder_post_types

Filter

Advertise additional Gridder-capable post types to AI Mode.

Filter signature
string[] $post_types

Let AI Mode recognize the Gridder of an existing Exhibition post type.

Usage example · PHP
add_filter( 'lay_ai_gridder_post_types', function ( $post_types ) {
    if ( post_type_exists( 'exhibition' ) ) {
        $post_types[] = 'exhibition';
    }
    return array_values( array_unique( $post_types ) );
} );

Your plugin must register the exhibition post type first. It must already use the Gridder; this filter does not add an editor or grant permissions.

lay_ai_writable_content_types

Filter

Advertise an alias-to-post-type map as writable Lay content.

Filter signature
array<string,string> $aliases

Expose a readable alias for an existing editable content type.

Usage example · PHP
add_filter( 'lay_ai_writable_content_types', function ( $aliases ) {
    if ( post_type_exists( 'exhibition' ) ) {
        $aliases['exhibition'] = 'exhibition';
    }
    return $aliases;
} );

Register exhibition first and retain its WordPress capabilities. AI Mode still checks the connected user’s editing permissions.

lay_custom_elements_liquid_post_types

Filter

Expose post types to Liquid collections and structured content context.

Filter signature
string[] $post_types

Make an existing Exhibition post type available to Liquid collections.

Usage example · PHP
add_filter( 'lay_custom_elements_liquid_post_types', function ( $post_types ) {
    if ( post_type_exists( 'exhibition' ) ) {
        $post_types[] = 'exhibition';
    }
    return array_values( array_unique( $post_types ) );
} );

Your plugin must register the exhibition post type first.

lay_gridder_document

Filter

Filter a normalized Gridder document returned through the supported plugin helper.

Filter signature
array $document, int $post_id, string $layout

Adjust the first gutter only in the document returned to your plugin.

Usage example · PHP
add_filter( 'lay_gridder_document', function ( $document, $post_id, $layout ) {
    if ( is_array( $document ) && $layout === 'desktop'
        && get_post_type( $post_id ) === 'exhibition'
        && array_key_exists( 0, $document['rowGutters'] ?? array() ) ) {
        $document['rowGutters'][0] = 4;
    }
    return $document;
}, 10, 3 );

This changes the helper’s read result. It does not save the layout or change the frontend by itself.

lay_gridder_document_before_save

Filter

Filter a plugin-supplied Gridder document before normalization and save.

Filter signature
array $document, int $post_id, string $layout, string $source

Normalize the first gutter for saves originating in your plugin.

Usage example · PHP
add_filter( 'lay_gridder_document_before_save', function ( $document, $post_id, $layout, $source ) {
    if ( $source === 'studio' && $layout === 'desktop'
        && array_key_exists( 0, $document['rowGutters'] ?? array() ) ) {
        $document['rowGutters'][0] = max( 0, (float) $document['rowGutters'][0] );
    }
    return $document;
}, 10, 4 );

lay_gridder_document_saved

Action

React after a save from the editor, AI Mode or the supported plugin helper.

Action signature
int $post_id, array $before, array $after, string $source

Record a plugin-owned timestamp after an actual Gridder change.

Usage example · PHP
add_action( 'lay_gridder_document_saved', function ( $post_id, $before, $after, $source ) {
    if ( $before !== $after ) {
        update_post_meta( $post_id, '_studio_layout_updated_at', gmdate( 'c' ) );
    }
}, 10, 4 );

Do not save the same Gridder document again inside this callback; that would trigger this action recursively.

lay_gridder_prepared_rows

Filter

Filter canonical prepared rows returned to a plugin.

Filter signature
array $rows, array $document, bool $cover_active

Adjust spacing in the prepared rows used by a plugin layout.

Usage example · PHP
add_filter( 'lay_gridder_prepared_rows', function ( $rows, $document, $cover_active ) {
    if ( is_array( $rows ) && isset( $rows[0]['rowGutter'] ) && ! $cover_active ) {
        $rows[0]['rowGutter'] = 4;
    }
    return $rows;
}, 10, 3 );

This filter belongs to the supported row-preparation helper; it does not rewrite stored Gridder data.

lay_gridder_rows_margin_css

Filter

Filter native row-gutter CSS generated for a plugin layout.

Filter signature
string $css, array $document, array $rows, string $selector, bool $is_phone

Append a spacing adjustment only for your presentation wrapper.

Usage example · PHP
add_filter( 'lay_gridder_rows_margin_css', function ( $markup, $document, $rows, $selector, $is_phone ) {
    if ( $selector === '.studio-presentation' && ! $is_phone ) {
        $rule = '.studio-presentation .row:last-child { margin-bottom: 0; }';
        $markup = str_replace( '}</style>', $rule . '}</style>', $markup );
    }
    return $markup;
}, 10, 5 );

The helper returns style markup. Insert the rule before the closing media query and style element so the markup remains valid.

lay_custom_field_group_values

Filter

Filter a Custom Field group returned through the supported plugin helper.

Filter signature
array $values, int $post_id, string $group_id, bool $include_defaults

Supply a fallback client label when your plugin reads the project group.

Usage example · PHP
add_filter( 'lay_custom_field_group_values', function ( $values, $post_id, $group_id, $with_defaults ) {
    if ( $group_id === 'project' && empty( $values['client'] ) ) {
        $values['client'] = 'Independent project';
    }
    return $values;
}, 10, 4 );

This example assumes an existing project group with a client text field and changes only the helper’s returned values.

lay_custom_field_group_values_before_save

Filter

Filter validated Custom Field values before the supported plugin helper saves them.

Filter signature
array $values, int $post_id, string $group_id, bool $partial

Trim a configured text field before the plugin helper saves it.

Usage example · PHP
add_filter( 'lay_custom_field_group_values_before_save', function ( $values, $post_id, $group_id, $partial ) {
    if ( $group_id === 'project' && isset( $values['client'] )
        && is_string( $values['client'] ) ) {
        $values['client'] = trim( $values['client'] );
    }
    return $values;
}, 10, 4 );

lay_custom_fields_saved

Action

React after native Lay Custom Field values were saved.

Action signature
int $post_id, string $group_id, array $before, array $after

Record when the configured project fields actually changed.

Usage example · PHP
add_action( 'lay_custom_fields_saved', function ( $post_id, $group_id, $before, $after ) {
    if ( $group_id === 'project' && $before !== $after ) {
        update_post_meta( $post_id, '_studio_fields_updated_at', gmdate( 'c' ) );
    }
}, 10, 4 );

The timestamp is plugin-owned metadata. Avoid writing the same Lay Custom Field group again from its saved callback.

lay_content_updated

Action

Receive a general notification after supported Lay content areas change.

Action signature
int $post_id, string[] $areas, string $source

Invalidate a plugin’s derived preview after supported Lay content changes.

Usage example · PHP
add_action( 'lay_content_updated', function ( $post_id, $areas, $source ) {
    delete_transient( 'studio_project_preview_' . (int) $post_id );
}, 10, 3 );

lay_content_duplicated

Action

React after AI Mode duplicated a content item.

Action signature
int $source_post_id, int $new_post_id

Give the duplicated item a fresh plugin-specific reference.

Usage example · PHP
add_action( 'lay_content_duplicated', function ( $source_post_id, $new_post_id ) {
    update_post_meta( $new_post_id, '_studio_reference', wp_generate_uuid4() );
}, 10, 2 );

lay_content_context

Filter

Extend the structured content context returned to plugins.

Filter signature
array $context, int $post_id

Add a derived year to the structured post data read by plugins.

Usage example · PHP
add_filter( 'lay_content_context', function ( $context, $post_id ) {
    $context['studio_year'] = get_the_date( 'Y', $post_id );
    return $context;
}, 10, 2 );

This filter extends the public helper’s return value. It does not modify stored fields or automatically extend every Liquid render.

Frontend, Styles, Elements and Navigation

lay_frontend_layout_response

Filter

Filter the final structured frontend layout response.

Filter signature
array $layout, int $id, string $type, array $object

Attach a small plugin-owned value to the final layout response.

Usage example · PHP
add_filter( 'lay_frontend_layout_response', function ( $layout, $id, $type, $object ) {
    if ( $type === 'project' ) {
        $layout['studio_project_year'] = get_the_date( 'Y', $id );
    }
    return $layout;
}, 10, 4 );

The final argument is an array. Your frontend plugin can read the added value; Lay does not render it automatically.

lay_site_chrome_visibility

Filter

Control the site title, menus and footer for one frontend layout.

Filter signature
array $visibility, int $post_id, string $type = ''

Hide the footer for a presentation post type.

Usage example · PHP
add_filter( 'lay_site_chrome_visibility', function ( $visibility, $post_id, $type = '' ) {
    if ( get_post_type( $post_id ) === 'presentation' ) {
        $visibility['footer'] = false;
    }
    return $visibility;
}, 10, 3 );

The frontend supplies the third argument; lay_get_site_chrome_visibility() supplies only the first two, so the callback uses a default.

lay_site_chrome_visibility_saved

Action

React after the supported plugin helper changes site chrome visibility.

Action signature
int $post_id, array $visibility

Invalidate a plugin’s preview after a visibility setting is saved.

Usage example · PHP
add_action( 'lay_site_chrome_visibility_saved', function ( $post_id, $visibility ) {
    delete_transient( 'studio_presentation_preview_' . (int) $post_id );
}, 10, 2 );

laytheme_after_bodytag

Action

Output markup immediately after the opening body tag.

Action signature
do_action( $hook )

Add a skip link for a main region rendered by your plugin.

Usage example · PHP
add_action( 'laytheme_after_bodytag', function () {
    echo '<a class="screen-reader-text" href="#studio-main">Skip to main content</a>';
} );

Use this only when your custom layout provides an element with id="studio-main". Keep the skip link visible on keyboard focus.

lay_after_navbar_markup

Filter

Append markup after Lay Theme navbar markup.

Filter signature
string $markup

Append a small contact link after the navbar.

Usage example · PHP
add_filter( 'lay_after_navbar_markup', function ( $markup ) {
    return $markup . sprintf( '<a class="studio-header-contact" href="%s">Contact</a>',
        esc_url( home_url( '/contact/' ) )
    );
} );

lay_mobile_menu_markup_before_ul

Filter

Insert markup before the mobile menu list.

Filter signature
string $markup

Add a short introduction before the mobile menu links.

Usage example · PHP
add_filter( 'lay_mobile_menu_markup_before_ul', function ( $markup ) {
    return $markup . '<p class="studio-menu-intro">Design, objects and spaces.</p>';
} );

lay_mobile_menu_markup_after_ul

Filter

Insert markup after the mobile menu list.

Filter signature
string $markup

Add an email link after the mobile menu links.

Usage example · PHP
add_filter( 'lay_mobile_menu_markup_after_ul', function ( $markup ) {
    return $markup . '<a class="studio-menu-contact" href="mailto:hello@example.com">Email the studio</a>';
} );

lay_shared_styles

Filter

Append CSS shared by Desktop, Tablet and Phone.

Filter signature
string $css

Style markup added by your plugin on every device.

Usage example · PHP
add_filter( 'lay_shared_styles', function ( $css ) {
    return $css . "\n.studio-menu-intro { letter-spacing: .02em; }";
} );

lay_desktop_and_tablet_styles

Filter

Append Desktop and Tablet CSS to the generated stylesheet.

Filter signature
string $css

Adjust your plugin’s header link on desktop and tablet.

Usage example · PHP
add_filter( 'lay_desktop_and_tablet_styles', function ( $css ) {
    return $css . "\n.studio-header-contact { margin-left: 2rem; }";
} );

lay_mobile_styles

Filter

Append Phone CSS to the generated stylesheet.

Filter signature
string $css

Adjust your plugin’s menu introduction on Phone.

Usage example · PHP
add_filter( 'lay_mobile_styles', function ( $css ) {
    return $css . "\n.studio-menu-intro { margin-bottom: 1rem; }";
} );

lay_phone_menu_styles_above_breakpoint

Filter

Append Phone Menu CSS above the configured breakpoint.

Filter signature
string $css

Style your plugin’s link above the Phone Menu breakpoint.

Usage example · PHP
add_filter( 'lay_phone_menu_styles_above_breakpoint', function ( $css ) {
    return $css . "\n.studio-header-contact { padding-inline: 1rem; }";
} );

lay_phone_menu_styles_under_breakpoint

Filter

Append Phone Menu CSS below the configured breakpoint.

Filter signature
string $css

Style your plugin’s email link below the Phone Menu breakpoint.

Usage example · PHP
add_filter( 'lay_phone_menu_styles_under_breakpoint', function ( $css ) {
    return $css . "\n.studio-menu-contact { display: block; padding-block: 1rem; }";
} );

laytheme_video_element_markup

Filter

Filter native Gridder video element markup.

Filter signature
string $markup, array $args

Mark native video elements for a plugin integration.

Usage example · PHP
add_filter( 'laytheme_video_element_markup', function ( $markup, $args ) {
    if ( ! class_exists( 'WP_HTML_Tag_Processor' ) ) {
        return $markup;
    }
    $tags = new WP_HTML_Tag_Processor( $markup );
    while ( $tags->next_tag( 'video' ) ) {
        $tags->set_attribute( 'data-studio-video', 'native' );
    }
    return $tags->get_updated_html();
}, 10, 2 );

This adds an attribute while retaining Lay’s video markup, sources and controls.

lay_thumbnail_tag_markup

Filter

Filter the tag-label markup of a project thumbnail.

Filter signature
string $markup, int $post_id

Append the project year to a thumbnail’s tag-label markup.

Usage example · PHP
add_filter( 'lay_thumbnail_tag_markup', function ( $markup, $post_id ) {
    return $markup . '<span class="studio-project-year">'
        . esc_html( get_the_date( 'Y', $post_id ) ) . '</span>';
}, 10, 2 );

This hook filters the thumbnail’s tag labels, not the opening thumbnail link.

lay_navigation_requires_full_page_load

Filter

Require a full page load for a resolved navigation target.

Filter signature
bool $blocked, int $id, string $type

Require a full reload for a plugin’s booking page.

Usage example · PHP
add_filter( 'lay_navigation_requires_full_page_load', function ( $blocked, $id, $type ) {
    if ( $type === 'page' && get_page_template_slug( $id ) === 'studio-booking.php' ) {
        return true;
    }
    return $blocked;
}, 10, 3 );

Existing full-reload requirements stay intact; the filter never forces a blocked target back into AJAX navigation.

lay_navigation_full_reload_page_ids

Filter

Provide post IDs that must use full-page navigation.

Filter signature
int[] $post_ids

Resolve a page by path and add it to the full-reload list.

Usage example · PHP
add_filter( 'lay_navigation_full_reload_page_ids', function ( $post_ids ) {
    $page = get_page_by_path( 'booking' );
    if ( $page ) {
        $post_ids[] = (int) $page->ID;
    }
    return array_values( array_unique( $post_ids ) );
} );

SEO and Media

lay_meta_enabled

Filter

Disable Lay Theme description and social meta output when a plugin owns those tags.

Filter signature
bool $enabled, int $post_id

Let an installed SEO integration own meta output.

Usage example · PHP
add_filter( 'lay_meta_enabled', function ( $enabled, $post_id ) {
    return get_option( 'studio_owns_meta', '' ) === 'yes' ? false : $enabled;
}, 10, 2 );

Use this only when your plugin already prints the required meta tags. The studio_owns_meta option belongs to your plugin.

lay_meta_title

Filter

Filter the final HTML document title.

Filter signature
string $title, int $post_id

Use a plugin-owned title override for one post.

Usage example · PHP
add_filter( 'lay_meta_title', function ( $title, $post_id ) {
    $override = get_post_meta( $post_id, '_studio_seo_title', true );
    return is_string( $override ) && $override !== '' ? $override : $title;
}, 10, 2 );

lay_meta_description

Filter

Filter the HTML meta description.

Filter signature
string $description, int $post_id

Use a plugin-owned description when one has been set.

Usage example · PHP
add_filter( 'lay_meta_description', function ( $description, $post_id ) {
    $override = get_post_meta( $post_id, '_studio_seo_description', true );
    return is_string( $override ) && $override !== ''
        ? wp_strip_all_tags( $override ) : $description;
}, 10, 2 );

lay_og_tags

Filter

Filter or replace the Open Graph property-to-content map.

Filter signature
array $tags, int $post_id

Set the social-preview locale from the WordPress site locale.

Usage example · PHP
add_filter( 'lay_og_tags', function ( $tags, $post_id ) {
    $tags['og:locale'] = get_locale();
    return $tags;
}, 10, 2 );

lay_twitter_tags

Filter

Filter or replace the Twitter name-to-content map.

Filter signature
array $tags, int $post_id

Set the studio’s social account while retaining the existing card data.

Usage example · PHP
add_filter( 'lay_twitter_tags', function ( $tags, $post_id ) {
    $tags['twitter:site'] = '@yourstudio';
    return $tags;
}, 10, 2 );

Replace @yourstudio with your actual account.

lay_image_alt

Filter

Filter image alternative text when Lay renders an attachment.

Filter signature
string $alt, int $attachment_id, int $post_id

Prefer the attachment’s own alt text when it is available.

Usage example · PHP
add_filter( 'lay_image_alt', function ( $alt, $attachment_id, $post_id ) {
    $attachment_alt = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
    return is_string( $attachment_alt ) && $attachment_alt !== ''
        ? $attachment_alt : $alt;
}, 10, 3 );

Common Examples

React once Lay content has been saved, regardless of whether the change came from the Gridder editor, AI Mode or a plugin:

add_action( 'lay_gridder_document_saved', function ( $post_id, $before, $after, $source ) {
	studio_sync_project_data( $post_id );
}, 10, 4 );

Replace selected SEO values without rewriting the final HTML:

add_filter( 'lay_meta_description', function ( $description, $post_id ) {
	return get_post_meta( $post_id, '_studio_description', true ) ?: $description;
}, 10, 2 );

add_filter( 'lay_image_alt', function ( $alt, $attachment_id, $post_id ) {
	return get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) ?: $alt;
}, 10, 3 );

Hide the standard Lay Theme chrome on one custom presentation:

lay_update_site_chrome_visibility( $presentation_id, array(
	'site_title' => false,
	'menu'       => false,
	'footer'     => false,
) );

Search and Cache

lay_search_placeholder_text

Filter

Change the frontend search input placeholder.

Filter signature
string $placeholder

Give the search field a studio-specific label.

Usage example · PHP
add_filter( 'lay_search_placeholder_text', function ( $placeholder ) {
    return 'Search projects and exhibitions';
} );

lay_search_post_types

Filter

Choose post types included in Lay Theme search.

Filter signature
string[] $post_types

Include a registered Exhibition post type in Lay search.

Usage example · PHP
add_filter( 'lay_search_post_types', function ( $post_types ) {
    if ( post_type_exists( 'exhibition' ) ) {
        $post_types[] = 'exhibition';
    }
    return array_values( array_unique( $post_types ) );
} );

Your plugin must register the exhibition post type first.

lay_search_enable_hidden_projects

Filter

Enable hidden-project metadata and the separate hidden-project search behavior.

Filter signature
bool $enabled

Enable Lay’s separate hidden-project search behavior.

Usage example · PHP
add_filter( 'lay_search_enable_hidden_projects', '__return_true' );

This enables hidden-project metadata and the special *+ search. Normal searches exclude those projects; *+ searches target them. This is search behavior, not an access-control mechanism.

lay_search_exclude_taxonomies

Filter

Exclude taxonomies from search metadata.

Filter signature
string[] $taxonomies

Keep a plugin’s internal classification out of searchable taxonomy labels.

Usage example · PHP
add_filter( 'lay_search_exclude_taxonomies', function ( $taxonomies ) {
    $taxonomies[] = 'studio_internal_group';
    return array_values( array_unique( $taxonomies ) );
} );

lay_search_custom_taxonomies

Filter

Filter custom taxonomy values collected for one search item.

Filter signature
array $taxonomies, WP_Post $post

Add an existing taxonomy’s labels to one post’s search metadata.

Usage example · PHP
add_filter( 'lay_search_custom_taxonomies', function ( $taxonomies, $post ) {
    $terms = wp_get_object_terms( $post->ID, 'studio_medium', array( 'fields' => 'names' ) );
    if ( ! is_wp_error( $terms ) && $terms ) {
        $taxonomies['studio_medium'] = $terms;
    }
    return $taxonomies;
}, 10, 2 );

The studio_medium taxonomy must already be registered and assigned to the relevant post type.

lay_search_full_content_post_ids

Filter

Filter IDs used for full-content search matching.

Filter signature
int[] $post_ids, string $query, string $language

Extend full-content results with a plugin’s public summary field.

Usage example · PHP
add_filter( 'lay_search_full_content_post_ids', function ( $ids, $query, $language ) {
    if ( trim( $query ) === '' || ! post_type_exists( 'exhibition' ) ) {
        return $ids;
    }
    $matches = get_posts( array(
        'post_type' => 'exhibition',
        'post_status' => 'publish',
        'fields' => 'ids',
        'numberposts' => 50,
        'suppress_filters' => false,
        'lang' => $language,
        'meta_query' => array( array(
            'key' => 'studio_public_summary',
            'value' => $query,
            'compare' => 'LIKE',
        ) ),
    ) );
    return array_values( array_unique( array_merge( $ids, $matches ) ) );
}, 10, 3 );

The example searches only published exhibitions and passes through the active language for multilingual integrations.

lay_search_post_array

Filter

Filter the complete normalized frontend search index.

Filter signature
array $items

Remove items explicitly excluded by your plugin’s own setting.

Usage example · PHP
add_filter( 'lay_search_post_array', function ( $items ) {
    return array_values( array_filter( $items, function ( $item ) {
        return empty( $item['postid'] ) || ! get_post_meta(
            $item['postid'], '_studio_exclude_from_search', true
        );
    } ) );
} );

lay_search_result_config

Filter

Filter search result rendering configuration.

Filter signature
array $config, int[] $thumbnail_ids

Show two thumbnail columns in Phone search results.

Usage example · PHP
add_filter( 'lay_search_result_config', function ( $config, $thumbnail_ids ) {
    $config['phone']['colCount'] = 2;
    return $config;
}, 10, 2 );

lay_layout_cache_entry_allowed

Filter

Reject a stale or incompatible layout cache entry at read time.

Filter signature
bool $allowed, int $layout_id, array $layout

Bypass cached layouts for posts showing a plugin’s live availability.

Usage example · PHP
add_filter( 'lay_layout_cache_entry_allowed', function ( $allowed, $layout_id, $layout ) {
    if ( get_post_meta( (int) $layout_id, '_studio_live_availability', true ) ) {
        return false;
    }
    return $allowed;
}, 10, 3 );

Existing cache restrictions remain intact. This marks selected layouts as dynamic; it does not disable caching across the entire site.

lay_element_markup_cache_taxonomies

Filter

Add taxonomies whose changes invalidate cached element markup.

Filter signature
string[] $taxonomies

Invalidate cached element markup when a custom taxonomy changes.

Usage example · PHP
add_filter( 'lay_element_markup_cache_taxonomies', function ( $taxonomies ) {
    $taxonomies[] = 'studio_medium';
    return array_values( array_unique( $taxonomies ) );
} );

Use the name of a taxonomy registered by your plugin.

For AI Assistants

The Browser Bridge exposes the same reference as JSON through its authenticated AI Mode route. This is not a freely accessible website API. An authorized assistant can focus the reference by category, type, query or exact hook.

GET /wp-json/laytheme/v1/ai/hooks
GET /wp-json/laytheme/v1/ai/hooks?category=gridder
GET /wp-json/laytheme/v1/ai/hooks?hook=lay_content_updated

If the required event or input is missing, name the exact integration point and ask for a new supported plugin hook. Do not read private meta keys or modify Lay Theme files as a workaround.

Compatibility

if ( function_exists( 'lay_get_gridder_document' ) ) {
	$document = lay_get_gridder_document( $post_id, 'desktop' );
}

Guard Lay Theme helpers with function_exists() or class_exists(), fail gracefully on older versions, preserve unknown document properties, and use WordPress capability checks for every plugin write.