Build or Override a Widget

Widget is part of Astroid's Element system and is used to create display elements in Layout Builder or Article Builder. The structure of a widget includes an xml file and a php file.

• The XML file is used to declare fields like a Joomla Extension

• The PHP file is used to query, execute and display results

An example about Icons Widget

To create or override a widget you need to create a folder {WIDGET_NAME} in the JROOT/media/templates/site/{YOUR_TEMPLATE_NAME}/astroid/elements/ folder with an xml file and a php file

• {WIDGET_NAME}.xml

• {WIDGET_NAME}.php

I created a test_widget and located it at JROOT/media/templates/site/{template-name}/astroid/elements/test_widget

The XML structure

I am taking an example of a simple xml structure of Icons Widget below

• title (required): Declare the name of the Widget you want to create.

• description: Declare the description of the Widget

• icon (required): Font Awesome class you can find them at https://fontawesome.com/

• category (required): Declare the category of the Widget

• element_type (required): There are 3 types of widget_type: system, widget, article. You can only choose 1 of the 3.

<?xml version="1.0" encoding="UTF-8"?>
<element>
    <title>ASTROID_WIDGET_ICONS_LABEL</title>
    <description>ASTROID_WIDGET_ICONS_DESC</description>
    <icon>fa-solid fa-font-awesome</icon>
    <category>ASTROID_ELEMENT_CATEGORY_UTILITY</category>
    <element_type>widget</element_type>
    <form>
        <fields>
            <fieldset name="general-settings" label="TPL_ASTROID_GENERAL_SETTINGS_LABEL" addfieldpath="/libraries/astroid/framework/fields">
                <field type="astroidgroup" name="misc_options" title="ASTROID_WIDGET_MISC_OPTIONS_LABEL"/>
                <field astroidgroup="general" name="icons" type="astroidsubform" label="ASTROID_WIDGET_ICONS_LABEL">
                    <form>
                        <fields>
                            <fieldset name="general-settings" label="TPL_ASTROID_GENERAL_SETTINGS_LABEL">
                                <field type="astroidtext" class="form-control" label="JGLOBAL_TITLE" name="title"/>
                                <field type="astroidicons" label="ASTROID_WIDGET_ICON_LABEL" name="icon"/>
                                <field type="astroidtext" label="ASTROID_WIDGET_LINK_LABEL" description="ASTROID_WIDGET_ICON_LINK_DESC" name="link" hint="https://astroidframe.work/"/>
                                <field type="astroidlist" name="target" label="ASTROID_WIDGET_LINK_TARGET_LABEL" default="">
                                    <option value="">Default</option>
                                    <option value="_blank">New Window</option>
                                    <option value="_parent">Parent Frame</option>
                                    <option value="_top">Full body of the window</option>
                                </field>
                            </fieldset>
                        </fields>
                    </form>
                </field>
                <field astroidgroup="misc_options" name="icon_size" type="astroidrange" min="1" max="300" step="1" postfix="px" default="18" label="TPL_ASTROID_BASIC_ICON_SIZE_LABEL" description="TPL_ASTROID_BASIC_ICON_SIZE_DESC" />
                <field astroidgroup="misc_options" type="astroidlist" name="icon_gutter" label="ASTROID_WIDGET_GUTTER_LABEL" default="2">
                    <option value="0">Collapse</option>
                    <option value="1">X-Small</option>
                    <option value="2">Small</option>
                    <option value="3">Medium</option>
                    <option value="4">Large</option>
                    <option value="5">X-Large</option>
                </field>
                <field astroidgroup="misc_options" name="color" type="astroidcolor" label="ASTROID_WIDGET_COLOR_LABEL"/>
                <field astroidgroup="misc_options" name="color_hover" type="astroidcolor" label="ASTROID_WIDGET_COLOR_HOVER_LABEL"/>
            </fieldset>
            <fieldset name="assignment-settings" label="TPL_ASTROID_ASSIGNMENT_SETTINGS_LABEL" addfieldpath="/libraries/astroid/framework/fields">
                <field type="astroidlist" name="assignment_type" label="ASTROID_WIDGET_ASSIGN" default="1">
                    <option value="1">ASTROID_WIDGET_ON_ALL_PAGES</option>
                    <option value="0">ASTROID_WIDGET_NO_PAGES</option>
                    <option value="2">ASTROID_WIDGET_SELECTED_PAGES</option>
                </field>
                <field ngShow="[assignment_type]==2" type="astroidassignment" label="ASTROID_ASSIGN_TO_MENU_ITEM" name="assignment"/>
            </fieldset>
        </fields>
    </form>
</element>

The PHP Structure

In PHP file you simply display what you want with widget. You can use $param->get() variable to call out the widget params defined in XML file. Let's see the example below.

<?php
// No direct access.
defined('_JEXEC') or die;

extract($displayData);
$hello = $params->get('hello_statement', 'Hello World!');
echo $hello;

Use Widget

To use the your widget, go to Administrator > Template Manager > select your Template > Template Options > Layout Builder

Create a block and Add Element. In the Element selection section, you will see your Widget as shown in the example image below. I created a Test Widget.