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.
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
export.php. If you're using a different route for the action, it's
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
$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.
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
default.php to the name of your layout file, which in this case is
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
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:
- Images stored in
- CSS stored in
- AJAX stored in
- "Pages" (non-routed content) stored in
- "Modules" (routed content) stored in
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.
/custom/ being outside the DocumentRoot for most installations. CSS will automatically run
static_root/ to the maximum PHP file upload size,
/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
_footer.php to prepend/append code to the routed file.
/pages/ are routed via
whatever.php is loaded from the
~/custom/admin/pages/ directory. The
/pages/ directory does not support additional commands or sub-directories.
/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
_footer.php described below.
_header.php and _footer.php
_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
/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
_footer.php file in each directory, this is BigTree's process when running your code:
$bigtree["config"]["admin_js"]arrays in your config with relative paths (i.e.
test.cssif the file is in
~/custom/admin/css/test.css) to use this method.
$bigtree["js"]arrays, respectively. These arrays are pre-filled with the styles/scripts from
$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.