Getting started with a FOF component

A basic, step by step tutorial

Community member Walt Sorensen has written a basic, step-by-step tutorial for FOF 3. Once you're gone through the concepts below you should follow his tutorial for a practical walk through building a FOF 3 component.

Filesystem layout

Even though the layout of a component powered by FOF 3.x is very similar to a typical Joomla! component there are a few key differences which you need to keep in mind.

Consider a component com_example. The directory layout goes like this:

<root>/administrator/components/com_example
    +-- Container/
    |     +-- Container.php
    +-- Dispatcher/
    |     +-- Dispatcher.php
    +-- Controller/
    |     +-- Item.php
    +-- Helper/
    |     +-- DoSomethingOrAnother.php
    +-- Model/
    |     +-- Item.php
    +-- Toolbar/
    |     +-- Toolbar.php
    +-- View/
    |     +-- Items
    |           +-- Html.php
    |           +-- tmpl/
    |                 +-- default.php
    +-- access.xml
    +-- config.xml
    +-- fof.xml
    +-- example.php

The first important thing to remember is that all directories containing classes are written with their first letter in uppercase and their name in singular. For example, it's Controller not controllers. This is a major and mandatory change over regular Joomla! naming conventions.

For class files it first looks for the exactly named Controller, Model and View (the same as the exact view name you're accessing) and if it's not found it will look for the canonical, (usually this means: singularized) name.

The Joomla! XML files (access.xml and config.xml) are still written in lowercase because this is what Joomla! expects.

The fof.xml file is also written in lowercase.

Your entry point file –in our example it's example.php– is also written in lowercase because this is what Joomla! expects. The entry point file always needs to be named the same as your component, without the com_ prefix. If your component is com_something then your entry point file is something.php.

Although not strictly necessary, it is highly advised to have a media directory named after your component. In our example it would be <root>/media/com_example. This makes it easier for users, front-end developers and site integrators to figure out which files belong to your component.

Do I really have to create all these directories and files?

No, you don't have to. At the bare minimum a component consists of an entry point file and a view template.

It really all depends on which factory you set up in your DI container. The BasicFactory really does require you to create every single directory and class file. On the other hand the MagicSwitchFactory will create classes based on conventions. There are other factories available with varying degrees of "magic" applied to your component. You can even create your own factories for even more customised behaviour. FOF is very flexible!

Your entry point file

Your entry point file is responsible for loading FOF, instantiating the Container and dispatching your component. A typical entry point file looks like this:

<?php

if (!defined('FOF30_INCLUDED') && !@include_once(JPATH_LIBRARIES . '/fof30/include.php'))
{
	throw new RuntimeException('FOF 3.0 is not installed', 500);
}

FOF30\Container\Container::getInstance('com_example')->dispatcher->dispatch();

Please note that

• there is no closing PHP tag (?>) in the file. Including a closing tag may cause session issues if you inadvertently put any character including whitespace and line endings after it.
• the entry point file always goes through FOF30\Container\Container::getInstance to get an instance of the Dependency Injection Container of your component, it must never try to instantiate the container directly.

Your classes

Your classes are namespaced. The namespaces for the frontend and backend parts of your application are by default ComponentName\Site and ComponentName\Admin respectively, where ComponentName is the name of your component without the com_ prefix and with its first character set in uppercase. For instance, if your component is called com_example the default namespaces are Example\Site for the frontend and Example\Admin for the backend.

It is advisable to configure more unique namespaces using the componentNamespace option of your component's fof.xml file. Our recommendation is using something like CompanyName\ComponentName. For example, if you set this option to AcmeCorp\Example the namespaces for your component become AcmeCorp\Example\Site for the frontend and AcmeCorp\Example\Admin for the backend.

The class names are simple to figure out since we're using the PSR-4 convention. The file in the directory <root>/administrator/components/com_example/Controller/Item.php will belong to the namespace AcmeCorp\Example\Admin\Controller and the class it contains will be called Item. In other words, for the namespace of the class you take the namespace of your component's back-end/front-end and append the path to the directory under your component's root, changing all path separators to backslashes. The name of the class is the name of the file. Simple!

Scaffolding

Note: Scaffolding has been depreciated since FOF v3.6

Scaffolding is a neat feature that you have to know about before starting with your FOF component. FOF can use .xml files to render your edit form or list item view. The downside of this method is that you'll have to create those .xml files in the first place, which is a boring process. To the rescue comes scaffolding. When you enable this feature FOF will generate the necessary .xml view files by reading your database structure. For more information on scaffolding check this section.