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

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

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

  • 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"?>
    <icon>fa-solid fa-font-awesome</icon>
            <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">
                            <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=""/>
                                <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 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 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 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 ngShow="[assignment_type]==2" type="astroidassignment" label="ASTROID_ASSIGN_TO_MENU_ITEM" name="assignment"/>

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.

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

$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.

Last updated

© Astroid Framework 2023.