The XML configuration file

The fof.xml file

FOF allows you to configure various aspects of your component without writing any code, through the fof.xml file. This file is located in the backend directory of your component. For example, if your component is called com_example you will put the XML configuration in the file administrator/components/com_example/fof.xml under your site's root.

A fof.xml file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<fof>
    <!-- Common settings -->
    <common>
        <!-- Container configuration -->
        <container>
            <option name="componentNamespace"><![CDATA[MyCompany\MyApplication]]></option>
        </container>

        <!-- Dispatcher configuration -->
        <dispatcher>
            <option name="defaultView">items</option>
        </dispatcher>
        
        <!-- Transparent authentication configuration -->
        <authentication>
            <option name="totpKey">ABCD123456</option>
            <option name="authenticationMethods">HTTPBasicAuth_TOTP,QueryString_TOTP</option>
        </authentication>

        <!-- Model configuration. One tag for each Model. -->
        <model name="orders">
            <!-- Model configuration -->
            <config>
                <option name="tbl"><![CDATA[#__fakeapp_orders]]></option>
            </config>
        
            <!-- Field aliasing. One tag per aliased field -->
            <field name="enabled">published</field>

            <!-- Relation setup. One tag per relation -->
            <relation type="hasMany" name="items" />
            <relation type="belongsToMany"
                      name="transactions"
                      localKey="foobar_order_id"
                      foreignKey="foobar_transaction_id"
                      pivotLocalKey="foobar_order_id"
                      pivotForeignKey="foobar_transaction_id"
                      pivotTable="#__foobar_orders_transactions" />
            <relation type="belongsTo" name="client" foreignModelClass="Users@com_fakeapp" />

            <!-- Behaviour setup. Use merge="1" to merge with already defined behaviours. -->
            <behaviors merge="1">foo,bar,baz</behaviors>
        </model>

        <!-- Controller, View and Toolbar setup. One tag per view. -->
        <view name="item">
            <!-- Controller task aliasing -->
            <taskmap>
                <task name="list">browse</task>
            </taskmap>
            
            <!-- Controller ACL mapping -->
            <acl>
                <task name="dosomething" />
                <task name="somethingelse">core.manage</task>
            </acl>
            
            <!-- Controller and View options -->
            <config>
                <option name="autoRouting">3</option>
            </config>
            
            <!-- Toolbar configuration -->
            <toolbar title="COM_FOOBAR_TOOLBAR_ITEM" task="edit">
                <button type="save" />
                <button type="saveclose" />
                <button type="savenew" />
                <button type="cancel" />
            </toolbar>
        </view>
    </common>
    
    <!-- Component backend options -->
    <backend>
        <!-- The same options as Common Settings apply here, too -->
    </backend>
    
    <!-- Component frontend options -->
    <frontend>
        <!-- The same options as Common Settings apply here, too -->
    </frontend>
</fof>

User overrides

The fof.xml file is distributed with your component. This means that every change made by end users to it will be overwritten when they update your component. This is a major problem for power users who want to modify the way your component behaves in a standarised manner, without core hacks. This is why in FOF 3 we introduced the user overrides feature.

Your users can create a file named fof.user.xml next to your regular fof.xml file. The directives in that user overrides file will be merged with your fof.xml file's contents. Please remember that you MUST NOT include the fof.user.xml file in your component packages!

Effect of the fof.xml file

Please note that not all tags have an effect at all times. The <container> tag is the only one which is always taken into account. For everything else it depends on which Factory you're using:

• BasicFactory and SwitchFactory: the <dispatcher>, <model> and <view> tags are ignored
• MagicFactory and MagicSwitchFactory: the <dispatcher>, <model> and <view> tags are taken into account when the class is created automatically

Container configuration

The options supported by the <container> tag are:

• componentNamespace The root namespace of the component's classes without a leading or trailing backslash, e.g. Acme\Example. Please note that \Site and \Admin will be appended automatically to this to get the frontend and backend classes' namespaces.
• frontEndPath The absolute filesystem path to your component's frontend. You can use the strings %ROOT%, %PUBLIC%, %ADMIN%, %TMP%, %LOG% and they'll be replaced with the relevant filesystem path. For example %PUBLIC%/components/com_example will be expanded to something like /var/www/html/mysite/components/com_example. Please remember to use forward slashes to retain compatibility with all operating systems.
• backEndPath Like frontEndPath, this is the absolute filesystem path to your component's backend.
• rendererClass The fully qualified class name of the view renderer we'll be using. The class must implement FOF30\Render\RenderInterface. The class should be able to be autoloaded.
• factoryClass The fully qualified class name of the MVC Factory object; default is FOF30\Factory\BasicFactory. You can use your own factory class if it's in your component's namespace or otherwise autoloaded.
• platformClass The fully qualified class name of the Platform abstraction object; default is FOF30\Platform\Joomla\Platform. You can use your own platform class if it's in your component's namespace or otherwise autoloaded.
• scaffolding Set to 1 to enable Scaffolding. Set to 0 (default) to disable it.
• saveScaffolding Set to 1 to enable saving scaffolding-generated XML forms and language strings. Set to 0 (default) to disable it.
• mediaVersion A version query string parameter added to the URL of all media (CSS, JS, LESS) files loaded through the View. This includes media files included by XML forms.
• encrypt_key_file The path to the key file used by the encryption service, relative to the component's backend root and WITHOUT the .php extension. The default value is 'encrypt_service_key' thus saving the key into the file <root>/administrator/components/com_YOURCOMPONENT/encrypt_service_key.php
• encrypt_key_const The name of the PHP constant used for storing the key in the key file. The default is something like COMPONENTNAME_FOF_ENCRYPT_SERVICE_SECRETKEY where COMPONENTNAME is the name of your component, without the com_ prefix, in all uppercase.

Dispatcher configuration

Note: These options only apply when using the Magic or MagicSwitch factories.

The options supported by the <dispatcher> tag are:

• defaultView The view to render when no view is specified in the input

Transparent Authentication configuration

Note: These options only apply when using the Magic or MagicSwitch factories.

You can configure your component's transparent authentication using the <authentication> tag of the fof.xml file. The <config> tag of the Transparent Authentication configuration can have one or more <option> tags. Each one defines a Model option used when creating it. The available options are the same as those in the transparent authentication configuration.

Model configuration

Note: These options only apply when using the Magic or MagicSwitch factories.

The configuration of each data-aware model (DataModel or TreeModel) of your application can be modified through the fof.xml file by using a <model> tag.

The name attribute of the tag tells FOF which Model the settings apply to. You can have a common configuration for all of your models by using the special name="*" attribute value. You can override any of the attribute values in specific models.

Model options

The <config> tag of the model configuration can have one or more <option> tags. Each one defines a Model option used when creating it. The available options are:

• use_populate When true the model will set its state from populateState() instead of the request.
• ignore_request When true getState will not automatically load state data from the request.
• tbl The name of the table this model will talk to. Remember to use #__ as your prefix to automatically use Joomla!'s table name prefix.
• tbl_key The name of the primary key field.
• knownFields A comma-separated list of fields which are known to the model.
• autoChecks Should I turn on automatic data validation checks?
• fieldsSkipChecks A comma-separated list of fields which will be ignored when autoChecks is enabled.
• contentType The UCM content type, e.g. "com_foobar.items", used by the ContentHistory behaviour.
• fillable_fields A comma-separated list of fields which will ALWAYS be automatically filled from the request.
• guarded_fields A comma-separated list of fields which will NEVER be automatically filled from the request. When this is set the fillable_fields are ignored.
• hash (since 3.1.2) The prefix used to store model state variables, e.g. com_example.modelName. (note the trailing dot). This value must conform to the 'cmd' input filtering (a-Z, A-Z, numbers, dashes and underscores only) and end with a dot. If a dot is not provided it will be added. It cannot be empty. Overrides hash_view if both are set.
• hash_view (since 3.1.2) Modifies the way the model state prefix ("hash") is automatically calculated when none is provided. Normally it's set to com_example.modelName where com_example is your component's name and modelName the name of your Model. When hash_view is provided it will be set to com_example.viewName.modelName instead where viewName is the value of hash_view. This is used to prevent state bleedover between mulitple views using the same Model as their default model.

Field aliases

Field aliases are assigned with the <field> tag. The syntax is:

<field name="alias">realField</field>

where:

• realField is the name of the field in your database table, e.g. "published"
• alias is the name of the alias you want to create for this field, e.g. "enabled"

Behaviors

You can supply a comma separated list of behaviors in the <behaviors> tag.

If you have set up default behaviors in a <model name="*"> entry and you want to add to (not replace) them in another model please set the attribute merge="1" in the <behaviors> tag.

Some common behaviors:

• Access
• Enabled
• Filters
• Language
• Ordered
• Own
• PageParametersToState
• Tags

Read more about model behaviors

Relations

The <relation> tags allow you to define the model relations used by the ORM-like features of FOF. You can have one or more <relation> tags, placed inside the <model> tag itself. The attributes of each tag are:

• type The type of the relation. One of hasOne, hasMany, belongsTo, belongsToMany
• name How this relation will be known to your model
• foreignModelClass The foreign model in the form modelName@com_something where modelName is the name of the Model class and com_something is the name of the FOF component the foreign model belongs to
• localKey The key in our table which holds the foreign key value. For the belongsToMany (n:n) relation this is the value of the pivotLocalKey field in the pivotTable. For other relations it is the value held by the foreign table's foreignKey field.
• foreignKey The key in the foreign table which holds the foreign key value. For the belongsToMany (n:n) relation this is the value of the pivotForeignKey field in the pivotTable. For other relations it is the foreign table's foreignKey field which must match the value of our localKey to satisfy the relationship.
• pivotTable Only valid for belongsToMany (n:n) relations. The name of the pivot (a.k.a. "glue" or "map") database table which maps our table's records with the foreign table's records, e.g. #__foobar_articles_comments
• pivotLocalKey Only valid for belongsToMany (n:n) relations. The field name in the pivotTable which must have the same value as our localKey to satisfy the relation.
• pivotForeignKey Only valid for belongsToMany (n:n) relations. The field name in the pivotTable which must have the same value as the foreign table's foreignKey to satisfy the relation.

You can set up as many relations as you want per Model. In fact you are encouraged to do so instead of using JOIN queries. Together with relation eager loading it's a couple of orders of magnitude faster than using JOIN queries under most circumstances.

Controller, View and Toolbar configuration

Note: These options only apply when using the Magic or MagicSwitch factories.

The configuration of each data-aware Controller and View of your application can be modified through the fof.xml file by using a <view> tag.

The name attribute of the tag tells FOF which Controller/View the settings apply to. You can have a common configuration for all of your views by using the special name="*" attribute value. You can override any of the attribute values in specific models.

Controller and View options

The <config> tag of the view configuration can have one or more <option> tags. Each one defines a Controller or View option used when creating it. The available options are listed below.

Controller options

The <config> tag of the view configuration can have one or more <option> tags. Each one can define a Controller option, used when creating it. The available options are listed below.

• default_task The task to execute if none is defined. The default value is display.
• viewName The name of the namespaced view class to load. Automatically defined based on the component and view names.
• modelName The name of the Model class to load. Automatically defined based on the component and view names.
• autoRouting When should FOF route non-SEF URLs through JRoute::_() automatically? The possible values are: 0 = never; 1 = only when NOT in backend; 2 = only when in backend; 3 = always. Default: 0.
• csrfProtection When should FOF perform automatic token checks to prevent CSRF attacks? 0 = never; 1 = always; 2 = when in the backend or when format=html; 3 = only when in the backend
• cacheableTasks A comma separated list of tasks which support Joomla!’s caching.
• preventStateBleedover (since 3.1.2) If you are using a default Model which has a different name than your controller AND that Model is also used as the default model in another Controller set this to 1 to prevent the user state set in one view from bleeding over to the other views. Open the FOF30\Controller\Controller class and look for protected $preventStateBleedover to read more about how it works and why it's necessary in the situation described above.

View options

The <config> tag of the view configuration can have one or more <option> tags. Each one can define a Controller option, used when creating it. The available options are listed below.

• template_path The path where the View will be looking for view template (.php, .blade.php) or form (.xml) files. By default it's the tmpl directory inside the current view's directory.
• layout The default layout to use for this view. This is normally determined automatically based on the task currently being executed.
• viewEngineMap Map view template extension to view engine classes, i.e. classes implementing the FOF30\View\View\EngineInterface interface. This is something like .php => Acme\Example\View\Engine\PhpEngine, .foo.bar => Acme\Example\View\Engine\FooBarEngine

Controller task mapping

The task map settings allow you to map specific tasks to specific Controller methods. It works the same way as adding running registerTask in your specialized Controller class.

The task map is enclosed inside a single <taskmap> tag. You can have exactly zero or one <taskmap> tags inside each <view> tag.

Inside the <taskmap> tag you can have one or more <task> tags. The name attribute defines the name of the task to map, whereas the content of the tag defines the controller’s method which will be called for this task.

Controller ACL setup

The ACL settings can be used to override or fine-tune the access control for each task of the particular view. Even though FOF comes with default ACL mappings for its basic tasks, these are not always sufficient or appropriate for all situations. Normally this is achieved by overriding the onBefore methods in the Controller, e.g. onBeforeSave to set up the ACL checks for the save task. You can use the ACL mappings in the fof.xml instead of such checks. You can even use the ACL mapping in fof.xml for custom tasks for which no onBefore method exists.

The ACL settings are enclosed inside a single <acl> tag. You can have exactly zero or one <acl> tags inside each view tag.

Inside the <acl> tag you can have one or more <task> tags. The name attribute defines the name of the task to apply the access control, whereas the content of the tag defines the Joomla! ACL privilege required to access this task. You can use any core ACL privilege or any custom ACL privilege defined in your component's access.xml file. If you leave the content blank then no ACL check is performed (the task is always accessible by all users). If you use the special value false then the ACL privilege is always going to fail, i.e. the task will not be accessible by any user. Moreover you can use @something to tell FOF to use the same ACL mapping as the something task. If your at-tags result in a circular reference (task A references task B which references task A) FOF will allow access without any further checks.

Toolbar configuration

The toolbar settings allow you to modify the default toolbar buttons for each task.

The toolbar is enclosed inside a single <toolbar> tag. You can have exactly zero or many <toolbar> tags inside each view tag.

Inside the <toolbar> tag you can have one or more <button> tags. The type attribute defines the type of the button to add. The type has to be one of those values: title, divider, custom, preview, help, back, media_manager, assign, new, publish, publishList, unpublish, unpublishList, archiveList, unarchiveList, editList, editHtml, editCss, deleteList, trash, apply, save, save2new, save2copy, checkin, cancel, preferences.

The view name is always pluralised. For example:

    <view name="items">
        <toolbar title="Todos" task="*">
            <button type="preferences" component="com_todo" />
        </toolbar>
        <toolbar title="Edit todo" task="edit">
            <button type="apply" alt="Apply" />
            <button type="cancel" />
        </toolbar>
    </view>