# Lay Theme LLM Context This file gives AI assistants and LLMs practical context for writing small Custom JavaScript and Custom CSS snippets for Lay Theme websites. Lay Theme is a WordPress theme for visual portfolio, shop and presentation websites. Layouts are built in the Gridder, a visual editor with rows, columns and draggable elements. Common content types are Pages, Projects, News posts, WooCommerce Products and Deck slides. Use this file together with the public documentation: - Documentation overview: https://laytheme.com/documentation.html - Custom JavaScript: https://laytheme.com/documentation/custom-javascript.html - Custom CSS Styling: https://laytheme.com/documentation/custom-css-styling.html - Gridder: https://laytheme.com/documentation/gridder.html - Gridder Elements: https://laytheme.com/documentation/gridder-elements.html - Gridder Rows: https://laytheme.com/documentation/gridder-rows.html - Layout Modes: https://laytheme.com/documentation/layout-modes.html - Page Settings: https://laytheme.com/documentation/page-settings.html - Textformats and Webfonts: https://laytheme.com/documentation/textformats-and-webfonts.html - Buttons: https://laytheme.com/documentation/buttons.html - Overlays / Desktop Burger Menu: https://laytheme.com/documentation/overlays.html - Navigation Animations: https://laytheme.com/documentation/navigation-animations.html - Multilanguage: https://laytheme.com/documentation/multilanguage.html ## What to ask before writing code When a user asks for Lay Theme code, clarify these points if they are not obvious: - Should the code run globally or only on one page/project? - Should it run once on initial load, or after every Ajax page change? - Should it target desktop, phone, or both? - Which element should it target? Ask for a CSS class or ID when needed. - Should it react to clicks, scroll, mouseover, a page change, an overlay opening, or a navigation animation? - Is the user trying to solve something that Lay Theme can already do without code, such as Page Settings, Textformats, Button Manager, Gridder sidebar settings or Custom Phone Layouts? ## Where users paste code For global custom scripts, users usually paste code into: Lay Options -> Custom CSS & HTML -> Custom content Wrap JavaScript in script tags: ```html ``` For global CSS, use: Lay Options -> Custom CSS & HTML -> Custom CSS There are also separate Desktop CSS and Mobile CSS fields. For page-specific CSS, the Gridder header has a CSS dropdown with Edit CSS, Edit Desktop CSS and Edit Phone CSS. Before writing CSS, prefer built-in Lay Theme controls when possible: - Page Settings can override site title, menu, menu bar and burger colors for a page. - The Customizer controls site title, menus, project thumbnails, filters, links in texts, shop text and other global frontend styles. - Textformats should be used for reusable text styling. - Button Manager should be used for button styling. - Gridder sidebar settings control opacity, corner radius, spacing, offsets, borders, shadows, sticky behavior, text width and other element settings. - Custom Phone Layouts or phone-specific sidebar settings should be used for many phone layout differences. ## jQuery Lay Theme already includes jQuery. Do not add another jQuery script tag. Use `jQuery`, not `$`, to avoid conflicts: ```html ``` Use delegated event handlers for content that may be loaded with Ajax: ```js jQuery(document).on("click", ".my-button", function(event) { event.preventDefault(); }); ``` Do not bind dynamic elements only once with `jQuery(".my-button").on(...)` unless the element is guaranteed to exist on initial page load and never be replaced. ## Ajax page loading Lay Theme websites can load new pages via Ajax. `jQuery(document).ready(...)` or `DOMContentLoaded` only fires once, on the first page load. For code that should run after every Lay Theme page change, use: ```html ``` The `newpageshown` event is the main event for custom code that needs to initialize elements after navigation. The `type` value is commonly `normal` or `project_overlay`. The current page or project can be read from the body: ```js var slug = jQuery("body").attr("data-slug"); var id = jQuery("body").attr("data-id"); var type = jQuery("body").attr("data-type"); var catid = jQuery("body").attr("data-catid"); ``` Common `data-type` values include `page`, `project`, `category`, `news`, `product` and `lay_deck`. ## Idempotent code `newpageshown` can fire more than once during some flows, especially with overlays, lazy loading or direct overlay loads. Write custom code so it can run repeatedly without duplicating DOM elements or binding duplicate handlers. Good pattern: ```html ``` For repeated event handlers, prefer one delegated handler outside `newpageshown`: ```html ``` If code creates timers, observers, animation instances or third-party widgets, clean up old instances before creating new ones. ## Lay Theme frontend events Lay Theme exposes an event emitter at `window.laytheme`. It supports common event-emitter methods such as `on`, `off`, `once` and `emit`. Use `on` for most custom code: ```js window.laytheme.on("event_name", function() { // ... }); ``` Important public-facing events: ```js window.laytheme.on("newpage", function(layoutObj, type, obj) {}); window.laytheme.on("newpageshown", function(layoutObj, type, obj, isProjectOverlayObj) {}); window.laytheme.on("newpageshownfast", function(layoutObj, type, obj, isProjectOverlayObj) {}); window.laytheme.on("gridshown", function(gridObj, targetRegion, type, obj) {}); window.laytheme.on("sizechanged", function(size) {}); window.laytheme.on("pushstate", function() {}); ``` Navigation animation events: ```js window.laytheme.on("navigation_out_start", function(type) {}); window.laytheme.on("navigation_out_end", function(type) {}); window.laytheme.on("navigation_in_start", function(type) {}); window.laytheme.on("navigation_in_end", function(type) {}); ``` Project overlay events: ```js window.laytheme.on("project_overlay_open_start", function($overlay, project) {}); window.laytheme.on("project_overlay_open_end", function($overlay, project) {}); window.laytheme.on("project_overlay_close_start", function($overlay) {}); window.laytheme.on("project_overlay_close_end", function($overlay) {}); ``` Page overlay events: ```js window.laytheme.on("page_overlay_open_start", function($overlay) {}); window.laytheme.on("page_overlay_open_end", function($overlay) {}); window.laytheme.on("page_overlay_close_start", function($overlay) {}); window.laytheme.on("page_overlay_close_end", function($overlay) {}); ``` Overlay event handlers receive the overlay as a jQuery object. Advanced/internal events exist too, for example `content_ready`, `overlayshown`, `overlayhidden`, `tabshown`, `tabhidden`, `searchshown`, `searchresultshown`, `newsLoadMore`, `woocommerce_initialized` and animation lifecycle events. Prefer the documented events above unless the user has a specific advanced need. ## Common DOM areas Useful selectors for frontend snippets: ```js jQuery("body") jQuery("#grid") jQuery("#custom-phone-grid") jQuery(".cover-region-desktop") jQuery(".cover-region-phone") jQuery("#footer") jQuery("#footer-custom-phone-grid") jQuery("body > .lay-content") ``` Gridder elements often render as columns with a `data-type` attribute: ```css .col[data-type="text"] {} .col[data-type="img"] {} .col[data-type="video"] {} .col[data-type="thumbnailgrid"] {} ``` Prefer asking the user to set a custom class or ID in the Gridder instead of relying on fragile generated selectors. In the Gridder, users can right-click an element and choose "Set HTML class and id". ## Page-specific targeting Use body data attributes when code should run only on one page/project: ```html ``` For CSS, page-specific classes or body data attributes can be used, but first check whether Page Settings can do the job without CSS. ## Links and Ajax navigation Lay Theme uses `a[data-type]` links for internal Ajax navigation. Avoid removing or overwriting these attributes on Lay Theme-generated links: - `data-type` - `data-id` - `data-catid` - `data-slug` If custom code creates links to Lay Theme pages or projects and should use Ajax navigation, preserve the normal URL and relevant data attributes. If the link should open normally, use a standard link or `target="_blank"` where appropriate. ## Overlays Lay Theme has two overlay concepts: - Project Overlays: project links open as overlays above the current overview page. - Page Overlays / Desktop Burger Menu: a page opens as an overlay, often used as a desktop burger menu or info panel. Use overlay lifecycle events when custom code needs to initialize or clean up something inside an overlay: ```html ``` ## Custom code examples ### Run code after every page change ```html ``` ### Add a click behavior to Gridder elements Ask the user to add the class `clickme` to the relevant element in the Gridder. ```html ``` ### Run only on one project ```html ``` ### Add a body class for a page ```html ``` ### React to navigation animation timing ```html ``` ## CSS guidance Use CSS only when the visual change cannot be done with Lay Theme settings. Prefer simple selectors based on explicit classes added by the user: ```css .my-custom-section { background: #f3f3f3; } ``` Avoid overly broad rules like: ```css div { margin: 0; } ``` Avoid styling admin/editor UI from frontend custom CSS unless the user explicitly asks for admin UI customization. If the user wants different styling per device, use Lay Theme's Desktop CSS and Mobile CSS fields or media queries. ## Feature-aware advice When users ask for layout code, first consider these Lay Theme features: - Gridder Rows: row spacing, row size, row backgrounds, row gutters, background fades and row background media. - Layout Modes: Place Freely for free positioning, Auto Layout for flexible rows and logo-wall style layouts. - Full Width Element: use when one element should stretch beyond the content frame. - Text Width in Pixels: text element sidebar setting for controlling readable line length. - Page Settings: per-page colors and show/hide controls for site title, menu, footer and burger/menu colors. - Page Templates: reusable Gridder layouts. - Custom Phone Layouts: separate phone layouts when automatic responsive behavior is not enough. - Textformats: reusable type styles for text editor content and Customizer text settings. - Button Manager: reusable Button 1, 2 and 3 styles, including menu active states. - Project Thumbnail settings: Customizer and Lay Options control project thumbnail appearance, descriptions, mouseover images and thumbnail video behavior. - Horizontal Scroll: changes how pages/projects/categories scroll on the frontend. - Fixed Header: uses a normal page as fixed header content. - Overlays: project overlays and page overlays / desktop burger menu. - Scroll Animations: element animations, float physics, simple parallax and marquee scroll behavior. ## Multilanguage Lay Theme can work with qTranslate-XT for multilingual content. In the admin panel and Gridder text editor, language switchers may be shown when qTranslate-XT is active. Avoid custom code that removes or replaces those language controls. Lay Theme admin translations are separate from website languages. Admin UI language support is defined by Lay Theme's own translation files and WordPress admin language settings. ## WooCommerce / Shop When WooCommerce is active, Lay Theme can expose shop-related Gridder elements such as Add to Cart Button, Product Thumbnail Grid and Product Index. Custom code should not interfere with WooCommerce form submissions, variation selects or cart fragments unless the user specifically asks for shop behavior. If custom code targets product pages, check `body[data-type="product"]`. ## What not to do - Do not load jQuery again. - Do not rely only on `jQuery(document).ready(...)` for Ajax-loaded page content. - Do not use `$` unless the code safely wraps it in a no-conflict closure. - Do not overwrite Lay Theme's `data-type`, `data-id`, `data-catid` or `data-slug` attributes. - Do not assume generated Gridder markup is stable forever; prefer user-defined classes/IDs. - Do not insert the same DOM element repeatedly on every `newpageshown`. - Do not write destructive WordPress/admin code unless explicitly requested. - Do not tell users to edit Lay Theme source files for small custom snippets. Use Lay Options custom code fields instead. ## Good LLM answer style for Lay Theme users When giving code to a Lay Theme user: 1. State where to paste it. 2. Include the complete snippet with script tags if it is JavaScript for the Custom head field. 3. Use `jQuery`, not `$`. 4. Use `window.laytheme.on("newpageshown", ...)` when the code must run after Ajax navigation. 5. Ask the user to add a class or ID in the Gridder when selecting a specific element. 6. Mention any built-in Lay Theme setting that may solve the same problem without code. 7. Keep the code small and explain which selector/class the user can change.