Skip to content

Latest commit

 

History

History
134 lines (100 loc) · 5.68 KB

creating_an_admin_module.md

File metadata and controls

134 lines (100 loc) · 5.68 KB

Module Structure

The bulk of your work in the admin area will likely be done creating new modules of code. Modules are groups of code centered around a single task or resource, like Users, Photos, etc. For the most part, admin modules are like any other bit of module CodeIgniter code, except for a new Module.php file that helps the module integrate into the admin area. Other than that you will be able to take advantage of solutions that allow your code to integrate directly into settings pages, be part of the global search results, automatically display and manage filtering of a resource list, or show up in the Recycler.

A good module to look at when creating your own is the Bonfire's own Users module (src/Users). You can also look at an example module Pages, which is an implementation of a module of Bonfire 2 admin panel for administration of pages on a website.

Configuring Module Locations

In order for Bonfire to discover your modules, you need to specify one or more locations that you plan on storing the modules. No location is set by default: the app/Modules entry in Config\Bonfire ships commented out, so uncomment it (or add your own, see below) before Bonfire will find your modules. As an example, we could create a Blog folder to store our new blog package. You would then need to create the standard directories, Config, Controllers, Models and Views at the very least. A Module.php file is also expected to live here, which we will look at in more detail a little later. The directory structure would look like:

app/
    Modules/
        Blog/
            Config/
            Controllers/
            Models/
            Views/
            Module.php

All files within the Blog directory would be expected to live within the App\Modules\{ModuleName} namespace, i.e. App\Modules\Blog\Config\Routes. To enable discovery, uncomment the entry in the $appModules setting of Config\Bonfire. You can customize the namespace by changing its key.

public $appModules = [
    'App\Modules' => APPPATH .'Modules',
];

For example, if I would prefer the modules to simply live within my company's namespace, Acme, I could edit the key to reflect that:

public $appModules = [
    'Acme' => APPPATH .'Modules',
];

If you have multiple locations you need to keep modules, you can add multiple entries here and they will all be automatically discovered and registered within Bonfire.

Bonfire caches the modules it finds in these locations for a minute. To pick up a new module folder straight away, run php spark cache:clear.

Modules in Composer packages

$appModules treats every folder in a location as a module, so it doesn't fit a Composer package that is a single module. List such a module in $packageModules instead. Each entry maps the module's own namespace to the directory that holds its Module.php:

public array $packageModules = [
    'Acme\Blog' => ROOTPATH . 'vendor/acme/blog/src',
];

Composer already autoloads the package's classes, so Bonfire only needs to find its Module.php. An entry whose directory or Module.php is missing is skipped.

A package can register itself, so the app using it changes nothing. Add a Config\Registrar class to the package with a Bonfire() method, and CodeIgniter merges what it returns into Config\Bonfire, including an app's published copy:

namespace Acme\Blog\Config;

class Registrar
{
    public static function Bonfire(): array
    {
        return [
            'packageModules' => ['Acme\Blog' => realpath(__DIR__ . '/..')],
        ];
    }
}

CodeIgniter only finds registrars in Composer packages while Config\Modules::$discoverInComposer is true, its default.

The Module File

The Module file handles initialization functions when the admin is loaded. It allows the module to create new menus, insert itself into the existing sidebar menus, etc. The initAdmin method is where all of the setup for displaying and admin page should be done.

Bonfire boots once per web request and calls one of two methods on every module:

  • initAdmin() on a request inside the admin area (ADMIN_AREA). The sidebar menus and dashboard widgets exist only then, so add menu items and widgets here.
  • initFront() on every other routed web request. Use it for setup your module needs on public pages.

Bonfire boots from the bonfire filter, so neither runs where filters don't: 404 pages, pages served from CodeIgniter's page cache, and CLI commands that don't boot Bonfire themselves. How Bonfire Fits Into a Request explains where booting sits among Bonfire's filters.

namespace Acme\Blog;

use Bonfire\Core\BaseModule;

class Module extends BaseModule
{
    public function initAdmin()
    {
        //
    }
}

To add your module's pages to the sidebar from initAdmin(), see Menus.

Naming a page in the breadcrumb

A page below a menu item, like a single record's edit form, can add itself to the breadcrumb with a crumb view section. The breadcrumb then reads "active menu item › crumb". When the page's URL doesn't sit under any menu item, name the parent too with crumbParent:

<?php $this->extend('master') ?>

<?php $this->section('crumbParent') ?><?= lang('Tools.logsModTitle') ?><?php $this->endSection() ?>
<?php $this->section('crumb') ?><?= esc($logFilePretty) ?><?php $this->endSection() ?>

Controllers and views

Your module's pages are ordinary CodeIgniter controllers and views, rendered inside the Admin theme. See Admin Controllers, Views and Themes for AdminController, the master layout and its sections, and changing the theme's own files.