Extensions

Extensions differ from Packages in that they are restricted to their namespaced directories, are upgradeable, and must follow a set of guidelines. If you're developing a simple set of modules, templates, or field types to be easily imported into your own projects (but won't be updated), Packages are most likely a better option.

Guidelines

In all the examples below, {id} refers to the ID of your extension (for example, com.fastspot.news would be an ID indicating a News extension programmed by Fastspot).

• All files for an extension must live in either /extensions/{id}/ or /site/extensions/{id}/
• Feeds will have their URL changed from /feeds/route/ to /feeds/{id}/route/
• Settings will have their ID changed internally to {id}*{setting}. Your extension can still get/set them via their regular ID but they will need to be called by their new ID if used outside your extension. Read More
• Field Types will have their files moved into a different directory format. You will see your included field types laid out in this manner with 3 files per field type:
  

  /extensions/com.fastspot.news/field-types/
  /extensions/com.fastspot.news/field-types/{field-type-id}/
  /extensions/com.fastspot.news/field-types/{field-type-id}/draw.php
  /extensions/com.fastspot.news/field-types/{field-type-id}/process.php
  /extensions/com.fastspot.news/field-types/{field-type-id}/options.php

• When including CSS or JavaScript in the admin area, extensions must use the $bigtree["css"] and $bigtree["js"] arrays to include the files. Treat the /extensions/{id}/css/ and /extensions/{id}/js/ folders as your roots, respectively. For example:

  $bigtree["js"][] = "news.js";
  $bigtree["css"][] = "news.css";
  

• When including CSS or JavaScript from a front end template, code should be stored in /site/extensions/{id}/css/ and /site/extensions/{id}/js/. You should include this manually in link/script tags as there is no direct knowledge of the end user's markup. For example:

  <script src="<?=WWW_ROOT?>extensions/com.fastspot.news/js/news.js"></script>
  <link rel="stylesheet" type="text/css" media="screen"
        href="<?=WWW_ROOT?>extensions/com.fastspot.news/css/news.css" />			

• When calling AJAX requests from your front end templates or admin side modules you must append /*/{id}/ before the AJAX path. Examples:
  

  $.ajax("<?=WWW_ROOT?>*/com.fastspot.news/ajax/get-more-news/"); // Front End Templates
  $.ajax("<?=ADMIN_ROOT?>*/com.fastspot.news/ajax/load-news-page/"); // Back End Modules			

• To use a Layout included in an extension in a Template you must set $bigtree["extension_layout"] = "{id}" in addition to $bigtree["layout"] = "layout_file". For example:

  $bigtree["extension_layout"] = "com.fastspot.news";
  $bigtree["layout"] = "news-layout";				

• You can not rely on including anything in /custom/inc/required/. Additional files must be manually loaded from your /extensions/{id}/ folder — only module class files will be added to PHP's autoloader.
• Files stored in /extensions/{id}/public/ will be moved to /site/extensions/{id}/ when an extension is installed / updated. The /public/ directory is used to keep everything under a single /extensions/{id}/ directory for version control. When packaging an extension, files stored in /site/extensions/{id}/ will automatically be copied into /extensions/{id}/public/.

Extension Creation Behavior

• After creating an extension with BigTree components (modules, templates, field types, etc) they will be automatically moved into your extension directory.
• Your /site/extensions/{id}/ and /extensions/{id}/ folders will be automatically included when creating your extension.
• Your included components (modules, templates, field types, callouts) will be automatically moved to your /extensions/{id}/ directory on extension creation. After initial creation they should be maintained there.
• You will be given the opportunity to include additional files required by your callouts/templates from your /templates/ajax/ and /templates/layouts/ folders during the extension creation process. These files will be moved into your /extensions/{id}/ directory upon creation.
• Files located in /site/extensions/{id}/ will be copied into /extensions/{id}/public/, overwriting any existing copies located in /extensions/{id}/public/.

Required Files

BigTree 4.3 introduces support for extensions to include their own required files (for use in module-less extensions that only add plugins, for instance). These behave exactly the same as files included in /custom/inc/required/ with the exception that the file list is cached when $bigtree["debug"] is set to false. The most common use case for this is going to be extensions that add a cron plugin but do not have a module class (as cron plugins require a function call to be defined somewhere without the ability to pre-load a class file).

To include files at run-time automatically, place any needed files in /extensions/{id}/required/, where {id} is the ID of your extension.