UX Element

Skill: Flatsome UX Element

This skill guides the creation of custom UX Builder elements for the Flatsome theme within the PolyUtilities plugin.

Purpose

Standardize the development of UX elements to ensure consistency across controllers, shortcodes, and templates, with special focus on real-time preview functionality. This skill is portable and uses dynamic prefixes for identity (Shortcode, Namespace, CSS Classes).

Required Variables

When calling this skill, define the following identity prefixes:

• {{namespace_prefix}}: The root namespace (e.g., polyxgo\PolyUtilities).
• {{shortcode_prefix}}: Prefix for shortcode names (e.g., poly_ux_).
• {{class_prefix}}: Prefix for CSS classes (e.g., poly-).
• {{plugin_dir_const}}: The plugin directory constant (e.g., __POLYUTILITIES_PLUGIN_DIR__).

Prerequisites

• Knowledge of PHP, WordPress Shortcodes, and AngularJS (for UX Builder templates).
• Access to inc/Core/Helper.php for utility functions.

Implementation Steps

1. Register Shortcode Logic (The Controller)

Create a new controller class in inc/Controllers/Elements/.

• Namespace: {{namespace_prefix}}\Controllers\Elements
• Method register_hooks(): Add the shortcode {{shortcode_prefix}}{{element_slug}} and ux_builder_setup action.
• Method render_element($atts, $content): Handle the frontend output.

2. Register UX Builder UI (The Shortcode)

Create a registration file in inc/builder/shortcodes/.

• Use add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', ...).
• Define options (textfield, select, colorpicker, slider, etc.).
• Link to the AngularJS template using Helper::get_poly_ux_builder_template().

3. Build the Preview Template (AngularJS)

Create an HTML file in inc/builder/shortcodes/templates/.

• CRITICAL: Wrap the entire content in a <span> with id="{{:: shortcode.$id }}".
• This ensures that clicking the element in the builder correctly selects it and shows options.
• Use ng-style and style scope="scope" for real-time CSS updates.

4. Create SVG Thumbnail

Create an SVG file in inc/builder/shortcodes/thumbnails/.

• Naming: Use {{element_slug}}.svg.
• Dimensions: Use 100x68px.
• Theme: Use the "Pastel Red" theme (#F87171 for accents, #FCA5A5 for fills).

5. Create the Frontend View

(Optional) Extract the HTML into inc/Views/elements/ for cleaner controllers.

Standards and Rules

The Wrapping Rule

Every UX Builder template MUST follow this structure:

<span id="{{:: shortcode.$id }}">
    <!-- Main element (e.g., <a>, <div>, <section>) -->
    <div class="{{class_prefix}}{{element_slug}}" ng-style="{ 'color': shortcode.options.color }">
        {{ shortcode.options.text }}
    </div>
    
    <!-- Scoped styles for hover effects or complex rules -->
    <style scope="scope">
        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
            opacity: 0.8;
        }
    </style>
</span>

Variable Naming (PHP vs AngularJS)

CRITICAL: When accessing shortcode options in the AngularJS template (.html), variables declared with underscores (_) in PHP MUST be accessed via camelCase.

• PHP: bg_color → AngularJS: shortcode.options.bgColor
• PHP: pxg_clock_font → AngularJS: shortcode.options.pxgClockFont
• PHP: text_align → AngularJS: shortcode.options.textAlign

Color Handling

• Use HEX or RGBA strings consistently.
• Always provide default values in the shortcode registration or handle them in the template/controller.

Templates

• Controller.php
• Shortcode.php
• Template.html
• View.php
• Thumbnail.svg