Every package has a configuration file located at /etc/PACKAGE_ALIAS/package.php, which includes a
|area||Yes||The area where the menu will be placed, and is basically always "admin", "members" or "public", although can be expanded on by other developers.|
|type||No||The type of menu. This can be "header" for a header / seperator, "parent" for a parent drop-down menu with sub-menus, "internal" for a standard menu, or "external" for a menu that links to an outside URL. Defaults to "internal".|
|parent||No||Only required for type "internal" menus, and when there is an existing parent menu you'd like to place the sub-menu into. As shown in the above example, we added the 'BLog Settings' sub-menu into the existing Settings parent menu.|
|position||No||The position of the menu, defaults to "bottom". Please see the below section for details on this variable.|
|icon||No||Generally only used for parent menus, and is the icon to display for the menu. Generally from FontAwesome icons, and is generally included within a
|alias||Yes||The alias of the menu, should be alpha-numeric and all lowercase. This is used as the URI to the menu and template within the /views/tpl/ directory.|
|name||Yes||The name of the menu that is displayed within the web browser.|
|menus||No||Only used for parent menus, and is an array containing key-value pairs of sub-menus to create within the parent drop down menu. In our above example, we added three sub-menus to our parent menu.|
|require_login||no||Only useful for the public site, and is a 1 or 0 defining whether or not the user must be authenticated for this menu to be visible. Used for menus such as "my Account" or "logout" within the public site.|
|require_nologin||No||Only useful for the public site, and is a 1 or 0 defining whether the user must NOT be authenticated for this menu to be visible. For example, you would use this to hide the "Login" and "Register" menus if the user is already logged in.|
This variable defines the position of the menu, and is relative to the "parent" variable. If no "parent" is defined, then relative to the top-level menus of the area (admin, members, public). It can be any of the following:
||Will become the first menu displayed, so if "parent" is defined will be the first sub-menu within the parent drop-down menu, and otherwise will be the first top-level menu displayed.|
||Only useful for menus of the type "parent", and lets you specify the menu should be displayed at the top or bottom just after a menu of the type "header".|
||Will place the menu just before / above the menu with the alias
||Will place the menu just after / below the menu with the alias
Description: Allows you to place
<a:placeholder> tags anywhere within the TPL template files, and have
them replaced with any value defined by the administrator via the CMS->Placeholders menu of the admin panel.
This is done to help allow administrators to add additional text / contents to the templates without manually
modifying the TPL code. Many times when upgrades are released, they will include some of the public / member
area TPL templates, so upon installing them, any manual changes made to the TPL are overwritten.
This array is simply a key-value pair, the keys being any URI )eg/ public/login, members/account/update_profile, etc.), and the value is an array containg all placeholder aliases you would like to create. The aliases can be anything you wish. For example:
$this->placeholders = array( 'public/login' => array('above_form', 'below_form'), 'public/register' => array('above_form', 'below_form') );
When this package is installed, the administrator can then define the values they desire for those four placeholders via the CMS->Placeholders menu of the admin panel. To add the placeholders into the templates, simply use tags such as:
<a:placeholder alias="above_form> <a:placeholder alias="below_form>
Simple as that. Now when viewing the template, all placeholder tags will be replaced with whatever value the administrator has defined for that placeholder.
Rarely used, but useful if you have a large number of settings for the package that need to be split into multiple pages. For an example of box lists, visit the Settings->Users and Settings->Financial menus of the administration panel. This allows you to easily place an expandable list of items on a page that link to other pages, and also allows you to easily add an item into an existing box list from another package.
For example, to add an existing item to the Settings->Users page, you would use:
$this->boxlists = array(); $this->boxlists = array( 'alias' => 'users:settings', 'href' => 'admin/settings/users_someapi', 'title' => 'Some API Settings', 'description' => 'Configure the API so your users can take advantage of all the cool features.' );
When the package is installed, it will add the above item to the
users:settings box list, which is displayed
within the Settings->Users menu. Creating new box lists is just as simple, and for example:
$this->boxlists = array( array( 'alias' => 'myblog:settings', 'href' => 'admin/settings/myblog_general', 'title' => 'General Settings', 'description' => 'Configure the general settings for the blog package.' ), array( 'alias' => 'myblog:settings', 'href' => 'admin/settings/myblog_deleteall', 'title' => 'Delete All Posts', 'description' => 'Go here if you wish to delete all blog posts, and start your blog fresh.' ) );
That's it. Now within any template, you can display the box list with the two above items (and any other items future packages add) by placing the HTML tag:
An array of associatve arrays, and allows you to define default e-mail notifications that are created upon installation of the package. For example, upon installing the "users" package, default e-mail notifications are created that are sent upon registration, reset password request, e-mail verification, and so on. Each element of this array is an associative array with the following key-value pairs:
|controller||The controller alias of the e-mail notification (ie. filename within /src/core/controller/notifications/ directory without the .php extension).|
|sender||The sender of the e-mail (eg. admin:1, user, etc.)|
|recipient||The recipient of the e-mail (eg. admin:1, user, etc.)|
|content_type||Either "text/plain" or "text/html".|
|subject||the subject of the e-mail notification|
|contents||A BASE64 encoded string of the contents of the e-mail message.|
|cond_XXX||Any condition values needed for the e-mail controller. Check the
For example, the below code will add a e-mail notification that is sent to the user upon registration.
$this->notifications = array(); $this->notifications = array( 'controller' => 'users', 'sender' => 'admin:1', 'recipient' => 'user', 'content_type' => 'text/plain', 'subject' => "Thank you for registering, ~username~', 'contents' => 'BASE64 STRING', 'cond_action' => 'create', 'cond_status' => '', 'cond_group_id' => '' );
A simple linear array that lists the package aliases of all dependencies for this package. For example, if the "users" package is required for this package to run correctly, you would put:
$this->dependencies = array( 'users' );
An associative array that allows you to define additional composer dependencies that are required for tihs package. Same as the composer.json file, the keys are the package name, and the values are the version requirement. Upon installation of the package, the composer.json file will be updated accordingly, although you will need to manually run "composer update". For example:
$this->composer_dependencies = array( 'some/package' => '>=2.5.0', 'another/package' => '*' );
Need a Professional?
Need development work by the creator of Apex? E-mail [email protected] for a free consultation.
Subscribe to the low traffic mailing list to stay updated on Apex.