Joomla 4.x Tutorial - Extension Development - Preface

Modify this post

If you are new to Joomla, please read Absolute basics of how a component worksdocs.joomla.org/special:mylanguage/absolute_basics_of_how_a_component_functions.

This tutorial is intended for Joomla 4. For information on creating a component for Joomla 3, see Developing a Model View Controller Component / 3.xdocs.joomla.org/j3.x:developing_an_mvc_component.

You need Joomla 4.x for this tutorial. You can find Joomla 4 on GitHubgithub.com/joomla/joomla-cms on the Developer Websitedeveloper.joomla.org/nightly-builds.html or create a free website at launch.joomla.org.

Aim of this tutorial?

This tutorial does not create a practical example. I have intentionally kept everything general. My main goal is to show you how Joomla works - and to help you understand it better yourself. In the end, you replace the name 'foo' in all files with the name of your component and extend it with your special requirements. If you like, you can use the script github.com/astridx/boilerplate/blob/t43/duplicate.sh for this.

Therefore, this tutorial is primarily intended for programmers who want to create a new component and do not know Joomla yet. The tutorial is also a help for programmers of a Joomla 3 component, if they extend their component for Joomla 4. For example, if you want to work on the validation of your Joomla 3 component, you will find in chapter 11 what you need - no more and no less.

The structure of this tutorial

Each chapter builds on the previous builds. However, if you are interested in a specific topic, feel free to look at a separate chapter.

There are many examples of components in the standard Joomla. For example

  • com_content
  • com_banner
  • com_tags oder
  • com_contact

In each component you see implementation details in context. Each is complex and finding and separating certain elements, such as page numbering or custom fields, is a hassle. This tutorial focuses on one detail in one chapter.

You create a component for Joomla 4, using the many built-in Joomla implementations. You are not reinventing the wheel. Joomla offers a whole range of standard functions.

If you want to get started immediately, scroll to The first view in the backend. Below you will find some things about Joomla 4 that you do not necessarily need for editing. However, some of them are good to know.

Basics

Never change the core files

The purpose of Joomla extensions is to have a system that can be extended. It is possible that your code and Joomla Core code can be provided with new functions independently of each other.

If make changes to Joomla itself, these will be overwritten with the next update.

You have the feeling that your function can only be implemented with a core hack? Your feeling is wrong! There is always a solution that leaves the system files untouched.

Learn from the core files

That you should not change the system files does not mean that you do not even look at them. Quite the opposite! By reading you will come across lots of code that is not documented anywhere. If you are not sure how to best implement a function, just rummage around in the Joomla code. The solution is usually be found in the heart of Joomla.

Joomla 4 offers five types of extensions

  • Components: A component is the main part of the site. A component handles data manipulation and input and storage in the database. A component on most websites is the centre of the page.
  • Modules: A module is an add-on to the site that extends its functionality. It occupies a secondary part of the web page and is not considered the primary focus of a page. It is displayed in different positions and it is selectable on which active menu items it is output. Modules are lightweight and flexible extensions. They are used for small parts of the page that are generally less complex and are displayed across different components.
  • Plugins: A plugin handles output generated by the system. It is not usually called as a separate part of the site. It takes data from other sources and processes it before displaying it. A plugin usually works behind the scenes.
  • Languages: The most basic extensions are languages. Essentially, language package files consist of key/value pairs that allow the translation of static text strings in the Joomla source code.
  • Templates: A template is the design of your Joomla website.

Joomla 4 consists of five different applications

  • Installation (used to install Joomla and must be deleted after installation);
  • Administrator (backend - to manage content);
  • Public or Website (frontend - used to display content);
  • CLI (used to access Joomla from the command line and for cron jobs);
  • API (Web Services - used to create APIs for machine-accessible content);

Basic knowledge

The autoload_psr4.php file

During the installation, entries are made in /library/autoload_psr4.php. This is new in Joomla 4. If you encounter strange problems, delete this file. It will be recreated the next time you load. Sometimes this solves a problem.

Namespace

Note the namespace tag at the top of each file

Namespace FooNamespace\Component\Foos\Administrator\View\Foos;

and as a tag in the manifest file

<Namespace>FooNamespace\Component\Foos</ Namespace>.

Why use namespaces?

  • Classes are organised in a defined structure and are automatically
  • automatically loaded via the Classloader.
  • Example ContentModelArticles becomes Joomla\Component\Content\Administrator\Model\ArticlesModel.
  • JLoader can handle the namespaces automatically.
  • We can distinguish between front-end and back-end classes
  • Files with namespaces can be found at /src

Capitalisation of folder names

You may notice that some of the Joomla 4.x folder and file names start with upper case letters and others with lower case letters. At first glance this seems chaotic. At second glance, it makes sense.

The folders in upper case contain PHP classes with namespace. Those in lower case contain XML files, template files, etc. . There are some lower case folders that contain PHP files (due to backwards compatibility) like the helper files.

For more information, see: https://github.com/joomla/joomla-cms/issues/22990

The classes get more meaningful names

The component MVC classes have more meaningful names in Joomla 4. For example, the controllers now have controller as a suffix for their class name. Thus, FooNamespace\Component\Foos\Administrator\Controller\Foos becomes FooNamespace\Component\Foos\Administrator\Controller\FoosController.

Additionally, the default controller, which in Joomla 3 is just called Controller, gets the name DisplayController to better reflect what the class does.

See: https://github.com/joomla/joomla-cms/pull/17624

Do you need an empty file index.html in each folder of your component?

The index.html is no longer needed, as that is directory listings not allowed in the default configuration. If you are further interested: Here is the discussion on the topic in a Google Group.

Technical requirements

Do you know how those responsible at Joomla decide which functions are supported and what is not pursued further? That's what the statistics plugin is for. Thanks to the users who activate this extension, important information flows into the development.

Alternative syntax for control structures

PHP offers an additional notation for control structures. This is especially handy when outputting larger blocks of HTML directly - without using echo. Use them in template files. This way they remain clear.

Use

<?php foreach ($this->items as $i => $item) : ?>
<?php echo $item->name; ?>
</br>
<?php endforeach; ?>

instead of y

foreach ($this->items as $i => $item) {
	echo $item->name;
	echo '</br>';
}

In this way, a single line is self-contained and HTML code is still clearly structured.

Database table prefix

Extension developers who use the database develop the extension so that the prefix is variable. They use the string '##__' to always reflect the correct string. This is replaced by the appropriate string at runtime by Joomla.

Where do I store JavaScript, CSS and image files that belong to my component?

Store these data in the directory 'media' in the Joomla root directory. This way it is possible to overwrite them. This is particularly advantageous for CSS files. To make the design consistent. The Best Practice Guidelines also recommend this.

Fontawesome Icons

You want to use icons but don't want to add your own library.

Use the free icons from fontawesome.com/icons in the frontend and backend. At least if you use the standard templates Cassiopeia and Atum, this will work. If your template does not support FontAwesome, you can load the icons yourself via the WebassetManager. In Joomla they are delivered with the template. Marking them as dependency is sufficient.

Attention: In Joomla Core files, you cannot simply copy them, because Joomla puts an icon- in front of them. This is then converted heregithub.com/joomla/joomla-cms/blob/4.0-dev/build/media_source/system/scss/_icomoon.scss for Fontawesome. In this way, only the icons intended for mapping in this file will work.

The HTML code

<i class="fas fa-align-left"></i>

displays the left-aligned character, for example.

Modify this post

Comments