Small fixes

[heelc29]

First of all I want to thank you for this great documentation. Many Thanks :)

Here are some small corrections, I hope they are right.

And a small question: Do you only mean Joomla 5 here? (Line 6499 and 6771) https://github.com/nikosdion/joomla_extensions_development/blob/23cdbe0031d927723d67e7da01933e985bc59070/joomla_extensions_development.xml#L6499

[nikosdion]

Thank you forfeiting these typos!

As for your question, yes, I really do mean Joomla 5.3. This will work throughout the Joomla 4 and 5 life. Another way to phrase it would've been “will work up to but not including Joomla 6.0” which is harder to parse because of the “not including” phrasing.

[Irata]

Nicholas,

not a typo this time but more a suggestion for some extra chapters or section that I think are important and would be of interest to probably more than just me.

'Adding Libraries' which I have a particular issue with at the moment that I don't seem to find even the basics to understand what I should be doing. I have asked my question here,
https://joomla.stackexchange.com/questions/32451/joola4-how-to-add-own- classes-to-libraries-vendor, and I am not expecting you to answer it, but the only documentation that I think should be relevant but isn't is this offical doc, https://docs.joomla.org/J4.x:Namespace_Conventions_In_Joomla which I suspect should have another section on what namespace Libraries should have.

So once again I can't help myself because the people that coded these changes haven't provide enough or any documentation to explain it, at least not that I can find.

On one hand it is good that Joomla resolves names 'automagically' to make things easier to work with, but it does make things harder to debug when they don't work, and it is not just these Libraries. End of whinge!

Another potential chapter on the black art of 'Autoloading' that I think programmers should really understand, and at least I don't because I can read about Composer and how things should work with PSR-4 but then Joomla seems to have its slightly different way of doing things. Something that covers the default autoloading and introduces us to the process and leads us to when we should be writing our autoloader.

I like that you have auto generated your documentation into HTML pages, much more convenient for the reader, however I still refer to the raw XML when I am searching for something I have read.

Still I am enjoying your writings and learning more and looking forward to getting into the new style of plugins with event listners, I have lots of them to convert.

And on your blog plage, any attempt to go to Page 2 results in a HTML 500

https://www.dionysopoulos.me/component/tags/tag/how-to.html

Regards, Terry

On 4 Oct 2022 at 22:13, Nicholas K. Dionysopoulos wrote:

Date sent: Tue, 04 Oct 2022 22:13:36 -0700 From: "Nicholas K. Dionysopoulos" @.> Send reply to: nikosdion/joomla_extensions_development @.> To: nikosdion/joomla_extensions_development @.> Copies to: Subscribed @.> Subject: Re: [nikosdion/joomla_extensions_development] Small fixes (PR #2)

Thank you forfeiting these typos! As for your question, yes, I really do mean Joomla 5.3. This will work throughout the Joomla 4 and 5 life. Another way to phrase it would've been "will work up to but not including Joomla 6.0" which is harder to parse because of the "not including" phrasing.

Reply to this email directly, view it on GitHub, or unsubscribe . You are receiving this because you are subscribed to this thread.Message ID: <nikosdion/joomla_extensions_development/pull/2/c1267951934 @github.com>

---

Terry Pollard www.irataweb.com.au 0409 942 896 Irata Pty Ltd ABN 29 069 253 292

The following section of this message contains a file attachment prepared for transmission using the Internet MIME message format. If you are using Pegasus Mail, or any other MIME-compliant system, you should be able to save it or view it from within your mailer. If you cannot, please ask your system administrator for assistance.

---- File information ----------- File: hts_1.PNG Date: 7 Oct 2022, 13:33 Size: 27478 bytes. Type: Unknown

The following section of this message contains a file attachment prepared for transmission using the Internet MIME message format. If you are using Pegasus Mail, or any other MIME-compliant system, you should be able to save it or view it from within your mailer. If you cannot, please ask your system administrator for assistance.

---- File information ----------- File: DEFAULT.BMP Date: 24 Aug 2004, 12:58 Size: 358 bytes. Type: Unknown

[nikosdion]

Regarding adding libraries: very good point! I see that you have been grossly misled by some articles to do what you must absolutely never do when the solution is dead simple and pretty obvious (at least to me). I will add that.

BTW, nobody documented Joomla's Composer dependencies because you must never touch them!

Regarding Joomla's autoloader, I will document the simple solution: delete administrator/cache/autoload_psr4.php. Really, that's all there is to it. You do not and MUST NOT write your own autoloader. I have a reason to write my own autoloader for Akeeba Engine (it's used in Akeeba Solo and Akeeba Backup for WordPress, therefore I can't use Joomla's PSR-4 autoloader). For people writing Joomla software only they don't need to do that. But yeah, I'll document what you need to do.

Regarding the documentation format, the normative format is the DocBook 5 XML file in this repo. The HTML version is to help people read it more easily. Once we get to a good point I'll start making ePub releases. I have ultimately decided against PDF because XML-FO (used as the intermediate format converting to PDF) is EOL since 2017 and the DocBook XSL stylesheets for XSLT 1.0 used to convert to PDF are no longer developed. Plus, if someone wanted to print the book in physical form they can easily do so from ePub, whereas trying to fit a PDF to a tablet screen for reading is far more difficult.

[Ruud68]

Hi, just love this documentation @nikosdion as IMO it is making us all better Joomla PHP developers. I find myself sometimes in situations where things in the end work, but where I wonder if that is the best way to do it. Describing best-practises help a lot in these cases. Looking at how Joomla core does things is not always a guarantee, like some core extension handle data in the table bind function, some in the model save function and some in the table store function: all work but which one is preferred? That kind of questions.

As for autoloading: templates do not autoload. For these you need to write yourself an autoloader. I have asked around but the only response I got from one of the core developers was 'I guess you are right'...

[nikosdion]

@Ruud68 Thank you :) Yes, templates do NOT have an autoloader BUT you do not need to write your own autoloader. I will cover that once I get to writing about templates.

Until then, here's how to do it.

• Create a src folder in your template.
• Create the file src/autoload.php in it. See below for the contents.
• In your index.php, error.php, and component.php files the first line should be require_once __DIR__ . '/src/autoload.php';

Contents of the src/autoload.php file:

<?php
defined('_JEXEC') || die;
$autoloader = include JPATH_LIBRARIES . '/vendor/autoload.php';
$autoloader->addPsr4('My\\Template\\Namespace', __DIR__);

That's really all there is to it! This trick even works on Joomla 3.

Regarding how MVC is supposed to be used... sigh. It depends on the context, really. I recommend reading "The Joomla MVC: an introduction" to understand how MVC is supposed to be used and how Joomla kinda-sorta corrupts "pure" MVC.

My general rules inferred from what I already wrote are:

• If your code applies to all data being written to / read from the database: put it in the Table class
• If it has to do with stuff that touches the UCM (tags, versioning, workflows): put it in the Table class
• If your code applies to item listings OR is reusable business logic: put it in the Model
• If it has to do with Form management (including custom fields): put it in the Model
• If it reads request data: put in the Controller. If this will change how the Model works, push the Model state (you will need to override the Controller's display method OR the Model's populateState method)
• If it's presentation-only: it belongs to the View
• If it produces HTML: it's either a view template (one-off) or a layout (reusable blocks)
• Anything else: it belongs in its own subdirectory in your src folder. Ideally, try to make it a service so you can push it to your MVC objects through your DI container. Because of the DI container's limitations in Joomla 4 I even tell you how to get access to the DI container if you need to pull it instead, even though it's not as clean an architecture.

Knowing where code belongs is something you eventually get a "feel" for. The more you maintain your components the more you'll get a good feel of where stuff goes.

Also, don't be afraid to refactor your code often. You WILL make mistakes writing code. You WILL hate the code you wrote 6 months ago. If you cannot find any mistakes and don't hate your code from 6 months ago you are misunderstanding something fundamental or you were not paying enough attention. This is not defeatism, it's the immediate result of the fundamental fact in a developer's life: we learn and evolve every single day. It's like being a pilot or a race car driver. The more you practice the more you understand your craft, the better you become, the more you diverge from the person you were a few months ago. As I've said time and again, when there's a week I've been working full time and have not learned a single new thing I will retire for I will no longer be a good developer. But I digress.

Refactor often. You will spot your mistakes, go ahead and fix them. You have something that works but the code isn't as good as you'd like it to be? Set aside some time to shape it up. This is my secret. That's how I ended up being able to adapt to Joomla 4. My code was constantly changing and evolving. One more big change wasn't a big deal, it was just a slightly longer than usual refactoring project.

[Ruud68]

Thanks @nikosdion just to follow up on the template autoloader. the /src/autoload.php should be loaded (potentially) in more files. e.g. it turns out that ./html/layouts/joomla/content/info_block.php where I use a helper class that is in ./src/Helper gives an error that this class is not found with the hint "did you forget a "use" statement

So as it turns out, the info_block (in this particular view) is rendered before index.php and should also have the require_once ./src/autoload.php set.

For me this is the issue with templates not having an autoloader, everywhere you use your helper classes you need to (potentially) autoload them yourself, which IMO is not autoloading :)

Anyway, I think this should be part of Joomla core, just like the plugin manifest namespace entry, template manifest should also have this to avoid doing it in plugins, components, modules one way and in templates another way.

But that is a discussion for another repo :)

[Irata]

Nicholas,

Regarding adding libraries: very good point! I see that you have been grossly misled by some articles to do what you must absolutely never do when the solution is dead simple and pretty obvious (at least to me).

I haven't been misled by any articles, I never found any articles to be misled by. :)

I looked at Joomla DatabaseAwareTrait and tried to mimic what I saw there, but as it is core there was no manifest file to follow. I look forward to reading any explanation of the dead simple solution that is not obvious to me. )

In Chapter 4. Plugins around the explanation of Namespace for Plugins I found it difficult to understand I think because you say that I can call it 'My\Namespace\Prefix' and then you recommend and use 'Joomla\Plugin\folder\Name\'. However using Joomla\Plugin\Folder\Name suggests it has to be called that for the files to be correctly located in the \plugins\system\name directory.

Some of the confusion for me maybe around that you have used what looks like a Joomla core plugin called example for your explanation which is probably not what many of us would be writing, we would be writing something for our own extension(s).

For example if I have Bricks\Fred as my prefix is the element then to be written as Bricks\Myextension\Plugin\Folder\Name or is it written as Bricks\Myextension

Perhaps a 'real world' example of what a 3rd party extension manifest, directory structure and files would look like would be useful. And looking ahead in the next two sections they two would be enhanced I think if there was a near complete sample of the 'example' plugin. I noticed for example that I can't see if I have to put the namespace statement in the example.php.

I would be prepared to attempt to put together a sample of what I think that section needs as way of contributing to your document for you to use but I expect you will need to change it to make it correct, however it might highlight where my understanding is lacking.

Terry

[nikosdion]

@Ruud68 Correct. If you have layout or template overrides which use your custom code they need to load the autoloader. Another approach to that is creating a library extension since it will be autoloaded anyway (and it's pretty hard for the user to disable unless they absolutely know how to look for it!).

I do agree that templates should have namespaces.

@Irata I was writing how to add Composer dependencies today :)

Regarding plugins, I do say that you can have any namespace prefix you want BUT the convention is to use the prefix Joomla\Plugin\FolderName\PluginName. Remember that only one plugin can be in a specific directory. A plugin in the folder plugins/system/whatever is necessarily the plg_system_whatever extension and it makes sense to give it the namespace prefix Joomla\Plugin\System\Whatever as it guarantees that no other plugin installed on the site will have the same namespace. If you use a more generic namespace, such as Plugin\Whatever it's possible that another developer creates a plg_content_whatever and chooses to use the same namespace. Having both of your plugins installed at the same time would break a site. This is why I tell you to use the Joomla\Plugin\FolderName\PluginName namespace prefix.

You can totally use the Bricks\Myextension\Plugin\Folder\Name namespace prefix instead! This is a pretty good prefix. It has a company name, the name of the package it belongs to, an indication that it's a plugin of a certain type (folder) and the plugin's name. It is extremely unlikely that anyone else will use the same namespace prefix as that plugin. Therefore it passes my litmus test of uniqueness.

If you were to use the more generic prefix Bricks\MyExtension you are shooting your own two feet, mate. The next plugin you write for the same extension would be sharing the same namespace as the first plugin and you'd end up with one plugin breaking the other.

Keep in mind that the goal of namespaces is to have them be unique and descriptive. Any two extensions installing in different folders on the same site cannot have the same namespace. Every namespace must be obvious as to which extension it refers to. Give crumbs to the user and any developer debugging a site as to what they should be looking for and who they should bother if something does not work.