Joomla Template Development with Astroid Framework

This document is an introduction to creating Astroid based Joomla! template. Although Astroid based Joomla! template is just like a normal Joomla! template, but after a few changes, it turns out to be a very powerful, interesting and super flexible one so that you can make everything possible that was difficult to do in any other Joomla template framework. The Framework has been specially made for UI/UX developers very carefully so that template can be override at it's deepest level. Let's look into template's folder structure.

Folder Structure

As we know, A Joomla template structure is quite flexible and can be made in any custom way. In the same way, Astroid compatible template is also exactly the same like Joomla template with a small expansion.

A Joomla template has a pre-defined folder structure, and Astroid is an idea to expand it slightly to make a Joomla template more flexible with manageable capabilities. Let’s have a look at how a template folder structure looks.

💡Tip: See how to create a basic Joomla template

A typical Joomla Template contains following subdirectories:

• 📁css - Template Stylesheets
• 📁html - Joomla Overrides
• 📁images - Template Images
• 📁js - Template Javascripts
• 📁language - Template Languages
• 📄component.php - Component View
• 📄error.php - Error View
• 📄index.php - Template index file
• 📄offline.php - Site Offline View
• 📄templateDetails.xml - Template Manifest
• 📄template_preview.png - Template Preview
• 📄template_thumbnail.png - Template Thumbnail

And after expanding with Astroid capabilities:

• 📁astroid - Astroid Configurations
  • 📁elements - Custom/Override Elements
  • 📁options - Custom/Override Options
  • 📁presets - Template Presets
  • 📄default.json - Default Template Settings
• 📁css - Template Stylesheets
• 📁html - Joomla Overrides
• 📁images - Template Images
• 📁js - Template Javascripts
• 📁language - Template Languages
• 📁scss - Template SCSS
• 📄README.md - Template documentation (Optional)
• 📄component.php - Component View
• 📄error.php - Error View
• 📄helper.php - Template Helper File (Optional)
• 📄index.php - Template index file
• 📄offline.php - Site Offline View
• 📄templateDetails.xml - Template Manifest
• 📄template_preview.png - Template Preview
• 📄template_thumbnail.png - Template Thumbnail

Creating the Manifest File

The example code for templateDetails.xml is as follows:

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="template" client="site" method="upgrade">
   <name>TPL_TEMPLATE</name>
   <creationDate>Dec 2019</creationDate>
   <author>JoomDev</author>
   <authorEmail>[email protected]</authorEmail>
   <authorUrl>https://www.joomdev.com</authorUrl>
   <copyright>Copyright (C) 2019 Joomdev, Inc. All rights reserved.</copyright>
   <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
   <version>1.0</version>
   <description>TPL_TEMPLATE_XML_DESCRIPTION</description>
   <files>
      <folder>css</folder>
      <folder>scss</folder>
      <folder>html</folder>
      <folder>astroid</folder>
      <folder>images</folder>
      <folder>js</folder>
      <folder>language</folder>
      <filename>index.php</filename>
      <filename>helper.php</filename>
      <filename>templateDetails.xml</filename>
      <filename>template_preview.png</filename>
      <filename>template_thumbnail.png</filename>
      <filename>component.php</filename>
      <filename>error.php</filename>
      <filename>offline.php</filename>
   </files>
   <positions>
     ...
   </positions>
   <languages folder="language/en-GB">
      <language tag="en-GB">en-GB.TPL_TEMPLATE.ini</language>
      <language tag="en-GB">en-GB.TPL_TEMPLATE.sys.ini</language>
   </languages>
   <config>
      <fields name="params">
         <fieldset name="basic" addfieldpath="/libraries/astroid/framework/fields">
            <field name="astroid" type="astroidmanagerlink"></field>
         </fieldset>
      </fields>
   </config>
</extension>

In the above code TPL_TEMPLATE is the name of template. The <config> must have field <field name="astroid" type="astroidmanagerlink"></field> with addfieldpath="/libraries/astroid/framework/fields"to make it identifiable for Framework that it is an Astroid based template.

Note: Template id will be store in astroid param.

Creating the index file

Here is the index.php for core of every page.

<?php

/**
 * @package   Astroid Framework
 * @author    JoomDev https://www.joomdev.com
 * @copyright Copyright (C) 2009 - 2020 JoomDev.
 * @license https://www.gnu.org/licenses/gpl-2.0.html GNU/GPLv2 or Later
 */
// No direct access.
defined('_JEXEC') or die;
defined('_ASTROID') or die('Please install and activate <a href="https://www.astroidframework.com/" target="_blank">Astroid Framework</a> in order to use this template.');

if (file_exists(__DIR__ . "/helper.php")) {
   require_once __DIR__ . "/helper.php"; // Template's Helper
}

$document = Astroid\Framework::getDocument(); // Astroid Document
// Output as HTML5
$this->setHtml5(true);
?>
<!DOCTYPE html>
<html lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>">

<head>
   <astroid:include type="head-meta" /> <!-- document meta -->
   <jdoc:include type="head" /> <!-- joomla head -->
   <astroid:include type="head-styles" /> <!-- head styles -->
   <astroid:include type="head-scripts" /> <!-- head scripts -->
</head> <!-- document head -->

<body class="<?php echo $document->getBodyClass(); ?>">
   <?php $document->include('document.body'); ?>
   <!-- body and layout -->
   <astroid:include type="body-scripts" /> <!-- body scripts -->
</body> <!-- document body -->

</html> <!-- document end -->

Understanding index.php

defined('_ASTROID') or die('Please install and activate <a href="https://www.astroidframework.com/" target="_blank">Astroid Framework</a> in order to use this template.');

This line of code prevents template to be deliver page if no Astroid plugin installed.

$document = Astroid\Framework::getDocument();

Calling Astroid document, provides access to the current Astroid Template/Document, with it you can add styles and scripts and more related to the template and document..

💡Tip: See How to use Astroid\Framework

<astroid:include type="head-meta" />
<astroid:include type="head-styles" />

These lines load meta and styles generated by Astroid Framework.

<astroid:include type="head-scripts" />
<astroid:include type="body-scripts" />

Astroid template provides the ability to load Javascript files both in head and body. So you load any javascript code or file to any position (Head/Body) from any extension by just calling addScriptDeclaration or addScript. See Adding JS/CSS in Astroid for more info. Example:

$document = Astroid\Framework::getDocument();
$document->addScript('FILE_PATH/FILE.js', 'head'); // loads in the head
$document->addScript('FILE_PATH/FILE.js', 'body'); // loads in the body

Here comes the Magic, See the below line of code:

<?php $document->include('document.body'); ?>

Astroid is so flexible to override, You can override almost every single line of code that Framework deliver, See Overriding in Astroid. In the above example Template loads all body contents from libraries/astroid/framework/frontend/document/body.php which you can simply override by copying this file to templates/YOUR_TEMPLATE/html/frontend/document/body.php and modify as you want.

**Note: ** See link for the template packaging and installation.