Extending the Admin

BigTree's admin area is incredibly flexible. Though most of your everyday needs are met with BigTree's module views, forms, and reports, there may be times when you need to roll your own code.

For the examples below, we're going to assume that /donations/ is the route to the module you're going to be adding custom functionality to.

Module Actions

You can add custom module actions to your module that appear in the module's navigation bar, or are hidden. To do this, edit your module and scroll down to the table of Module Actions; click the add button. You're given the choice of a name for your action, a route for your action, access level, icon, whether it's in navigation or not, and finally what form/view to provide it. For this section, we'll generally be ignoring the form/view since we're creating custom PHP code so leave those as —. For our example we're going to use export as the route for creating a CSV export.

Once you've created your module action, you will want to create a PHP file in ~/custom/admin/modules/donations/ named export.php. If you're using a different route for the action, it's {your-route}.php. donations in this example is the route of the module for this action.

Beginning in BigTree 4.0RC2 you do not have to draw any of your module's headers or navigation; you may simply begin writing your PHP code in that file. You're already in a bootstrapped BigTree admin environment so you have access to $cms and $admin as well as $bigtree for your environment setup. Just like the front end of the site, your content is processed first and then loaded into the layout of the admin. In this particular example, however, we do want to write CSV headers at the top of our export.php file and die() at the end of the script to prevent the CSV from being loaded into the HTML layout of the admin.

Custom Modules

You can create custom modules without any views or forms. You may add a new module with just a name and begin by creating a default.php file in the module's custom directory. Suppose we wanted to create an eCommerce system inside the admin with the route ecommerce. We would create the directory ~/custom/admin/modules/ecommerce/ and place a default.php file in the directory. BigTree by default will load the content from default.php into the admin's main layout. You can create your own custom layout by creating one in ~/custom/admin/layouts/ and echoing $bigtree["content"] where you'd like the content for default.php to load. To use this layout you would set $bigtree["layout"] in default.php to the name of your layout file, which in this case is ecommerce.

You can create custom modules without actually making BigTree aware of the module through Developer, they will simply not draw the breadcrumb / title / navigation in this case. You can still go to http://yoursite.com/admin/ecommerce/ to load the default.php file in your /custom/admin/modules/ecommerce/ folder.

AJAX

You can run non-layout-loaded content through the /custom/admin/ajax/ folder. For example, if you created export.php in that directory you could access it via http://yoursite.com/admin/ajax/export/.

Routing in Admin

Routing in BigTree's admin area works similarly to routed templates on the front end, but with a few differences. There are 6 main routing categories:

  1. Images stored in ~/core/admin/images/ and ~/custom/admin/images/
  2. CSS stored in ~/core/admin/css/ and ~/custom/admin/css/
  3. JavaScript stored in ~/core/admin/js/ and ~/custom/admin/js/
  4. AJAX stored in ~/core/admin/ajax/ and ~/custom/admin/ajax/
  5. "Pages" (non-routed content) stored in ~/core/admin/pages/ and ~/custom/admin/pages/
  6. "Modules" (routed content) stored in ~/core/admin/modules/ and ~/custom/admin/modules/

The pages and modules directories can be somewhat confusing. The actual "Pages" feature of BigTree is stored in ~/core/admin/modules/pages/ and NOT in ~/core/admin/pages/ because it is a routed section of the admin. pages refers to pages of the admin section, not pages of your site and modules refers to the admin's modules, not the modules of your site.

Images, CSS, JavaScript

Images, CSS, and JavaScript are all routed just as you'd expect by directory/filename. The only reason they need routing at all is due to /core/ and /custom/ being outside the DocumentRoot for most installations. CSS will automatically run BigTree::formatCSS3 to auto-vendor-prefix among other things. JavaScript automatically converts {maxfilesize}, www_root/, admin_root/, and static_root/ to the maximum PHP file upload size, WWW_ROOT, ADMIN_ROOT, and STATIC_ROOT, respectively.

/ajax/

The /ajax/ directory routes like a routed template directory. This means you can use sub-directories, throw additional commands as routes (which are returned in $bigtree["commands"]), and use _header.php and _footer.php to prepend/append code to the routed file.

/pages/

Files in /pages/ are routed via http://yoursite.com/admin/whatever/.whatever.php is loaded from the ~/core/admin/pages/ or ~/custom/admin/pages/ directory. The /pages/ directory does not support additional commands or sub-directories.

/modules/

The /modules/ directory routes just like front end routed templates and /ajax/. You can use sub-directories and throw additional commands as routes as well as _header.php and _footer.php described below.

_header.php and _footer.php

All _header.php and _footer.php files in the directory will be routed in the order they appear. For example, let's say we're hitting http://yoursite.com/admin/ajax/export/donations/weekly/ and being routed to ~/custom/admin/ajax/export/donations/weekly.php. BigTree crawls each directory in the order it's hit (excluding the top level /ajax/ and /modules/ directories), so if there's a _header.php in the /export/ directory it will be the first to be included, followed by any header in /export/donations/, and then /export/donations/weekly/ (if weekly is a directory and we're routing to /weekly/default.php). The same is true for ~/custom/admin/modules/my-module-name/ directories. Let's show an example below for the AJAX file ~/custom/admin/ajax/export/donations/weekly.php:

Let's assume that we have a _header.php and _footer.php file in each directory, this is BigTree's process when running your code:

  • Include ~/custom/ajax/export/_header.php
  • Include ~/custom/ajax/export/donations/_header.php
  • Include ~/custom/ajax/export/donations/weekly.php
  • Include ~/custom/ajax/export/donations/_footer.php
  • Include ~/custom/ajax/export/_footer.php

Custom CSS and JavaScript

You can include custom CSS and JavaScript in the admin in two ways:

  1. Your ~/templates/config.php file can setup CSS and JavaScript that you want included on every page of the admin. This is the required method if you setup custom button classes for your Module Views since you can not use the following method in auto-generated views. Edit $bigtree["config"]["admin_css"] and $bigtree["config"]["admin_js"] arrays in your config with relative paths (i.e. test.css if the file is in ~/custom/admin/css/test.css) to use this method.
  2. In custom PHP code you can add your CSS or JavaScript file to the $bigtree["css"] and $bigtree["js"] arrays, respectively. These arrays are pre-filled with the styles/scripts from $bigtree["config"]["admin_css"] and $bigtree["config"]["admin_js"] so you could theoretically remove them in your PHP script before they are loaded by the layout if you want them to not exist on your custom PHP pages.