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

The system will scan widgets from folders with the following priority order:

1. media/templates/site/{YOUR_TEMPLATE_NAME}/astroid/elements

2. plugins/astroid/{YOUR_PLUGIN_NAME}/elements

3. libraries/astroid/framework/elements

Create a Widget using Joomla Template

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

Create a Widget using Joomla Plugin

You are a Joomla extension developer and want to create widgets for Astroid so that you can easily include them in your templates or 3rd party templates without having to use template override. So using Astroid element plugin is the easiest way.

You can download Example plugin below >> extract ZIP file and try with it. This is a Joomla plugin, so you can install it via administrator >> System >> Install Extensions >> Upload package file

When you upload plugin successfully. Go to Template Options >> Layout >> Add Element >> You can see it

Go to ROOT/plugins/astroid/plg_elements_example/elements You can see the structure

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>Example Widget</title>
    <description>Example Widget</description>
    <icon>fa-solid fa-snowflake</icon>
    <category>Example</category>
    <element_type>widget</element_type>
    <form>
        <fields>
            <fieldset name="general-settings" label="TPL_ASTROID_GENERAL_SETTINGS_LABEL" addfieldpath="/libraries/astroid/framework/fields">
                <field astroidgroup="general" type="astroidtext" label="Say Hi" name="statement"/>
            </fieldset>
            <fieldset name="assignment-settings" label="TPL_ASTROID_ASSIGNMENT_SETTINGS_LABEL" addfieldpath="/libraries/astroid/framework/fields" articleData="false">
                <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);
$statement  = $params->get('statement', 'Hello World!');
echo '<h2>'. $statement .'</h2>';

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.