Creating a Module

You're asked to create a new module for managing company's location information. We will call this module the Locations module.

Step 1: Location of your module

There are two potential locations for your project. The sa module directory, and your application's module directory.

             ├───{AppModules}   <-- custom modules
             └───sa             <-- core modules

The general rule of thumb for identifying the home for your module is,

  1. Application specific modules go in a custom app modules directory

  2. Core SiteAdmin modules go in the sa modules directory.

Don't see a directory for custom modules?

If you're working with a fresh installation of SiteAdmin, you'll probably only see a sa directory in {project_root}/sitadmin/modules. For application specific modules, create a new directory. The directory name will be used for PSR-4 class autoloading, so it must be namespace friendly.

By convention, the application modules directory is named after your project, capital-cased. For example, if your project is called "Awesome Fishing Supplies", you might name the directory "AwesomeFishingSupplies." After naming your custom module directory, your directory structure should look like this:

             ├───AwesomeFishingSupplies <-- custom modules
             └───sa                     <-- core modules

Step 2: Module Directory Structure

             │     └───Locations
             │       └───src
             │       │   ├───classes
             │       │   │     ├───models
             │       │   ├───css
             │       │   ├───js
             │       │   └───views
             │       └───composer.json


The classes directory will contain all of your PHP classes. This will include controllers, repositories, configuration, and helpers.


The models directory will contain all of your doctrine entities.


The css directory will contain all CSS stylesheets.


The js directory will contain all JS scripts.


The views directory will contain all templates for views and subviews.

Step 3: Create Module Configuration File

All modules contain a configuration file. This file is located in the {module_root}/classes directory, and must match the case sensitive name of the module. For example, the configuration file for our Locations module configuration file will reside in {module_root}/classes/LocationsConfig.php.


namespace AwesomeFishingSupplies\Locations;

use sa\application\moduleConfig;

class LocationsConfig extends moduleConfig
     * Code executed before module is initialized.
     * Generally, modRequests and event listeners reside here.
    public static function init() {}
     * Module routes
    public static function getRoutes() {}
     * SiteAdmin dashboard navigation items
    public static function getNavigation() {}
     * Module settings
     * Will be editable from SiteAdmin's settings manager.
    public static function getSettings() {}

Step 4: Filling out the module's configuration


The init() method contains code that is executed before the module is fully initialized. This is where you would place modRequests, event listeners, or code that other parts of the module expect to be available.


The getRoutes() method returns an array of the module's application and administrative routes. View the routing documentation for more details.


The getNavigation() method specifies all the module's administrative navigation links. These links will appear in the admin dashboard's main menu.

public static function getNavigation() {
    return array(
        new navItem([
            "id"     => "awesomeFishingSupplies_locations",
            "name"   => "Locations",
            "icon"   => "fa fa-user",
            "parent" => "siteadmin_root"
        new navItem([
            "id"      => "awesomeFishingSupplies_locations_index",
            "name"    => "All Locations",
            "routeid" => "awesomeFishingSupplies_locations",
            "parent"  => "awesomeFishingSupplies_locations"




A unique ID for the nav item. Name should be structured as {vendor}_{module}_{action}. Parent nav items won't have an action.


The navigation item's label.


The route that the nav item is linked to.


The id of the parent nav item. If the current nav item is the parent, set this value to siteadmin_root.


The module's settings should be defined in the getSettings() method. This includes API keys, pagination options, test mode toggles, etc.

public static function getSettings() {
    return array(
        'enable_test_mode' => array(
            'module' => 'Locations',
            'default' => true,
            'type' => 'boolean'
       'api_secret_key' => array(
           'module' => 'Locations', 
           'default' => '', 
           'type' => 'text'




The name of the module associated with this setting. This name should be human readable (i.e instead of PageEditor, use Page Editor).


The setting's default value. Data type varies depending on the setting's type parameter.


The type of field. Text => text field. boolean => true/false radio buttons.

Last updated