By the end of this unit you will be able to modify the webtop tabs, sub-sections and menus. |
The webtop administration area in FarCry is fully configurable. This includes the addition of your own functionality and the modification or removal of existing areas of the webtop. Within your project you will find a sub-directory called projectName/customadmin and all code pertaining to modifying the webtop for your application should be stored there.
The "object admin" is a sophisticated grid for listing and providing hooks for maintenance tasks on any content type. It is fully configurable, and is a workhorse for providing administration in the FarCry framework.
If you've used the scaffold utility to build an administration screen for your custom content type you will find a subdirectory called projectName/customadmin/customlists complete with a simple ColdFusion template referencing the object admin custom tag:
<cfsetting enablecfoutputonly="true"> <cfimport taglib="/farcry/core/tags/formtools" prefix="ft" /> <cfimport taglib="/farcry/core/tags/admin/" prefix="admin" /> <!--- set up page header ---> <admin:header title="Case Studies" /> <ft:objectAdmin title="Case Studies" typeName="dmCaseStudy" plugin="daeBase" columnList="title,urlWebSite,datetimelastupdated" sortableColumns="" lFilterFields="" sqlOrderBy="" /> <admin:footer /> <cfsetting enablecfoutputonly="no"> |
You can create as many Object Admin screens as needed with different attributes to easily provide different types of admin options for users.
FarCry webtop tabs (sections), drop downs (sub-sections) and menu items are managed through the webtop.xml document. You can supplement this XML file, or even override sections of the document simply by adding an appropriately formatted customadmin.xml document to your project's projectName/customadmin folder. FarCry merges webtop.xml and customadmin.xml and uses the resulting xml document object to build the UI for the webtop. The XML document is also used to nominate all the relevant permissions for access to areas of the webtop.
In fact the framework will automatically merge all suitable webtop configuration xml files it finds. So you can have multiple files in your projectName/customadmin folder if needed. The scaffold utility will produce multiple files by default. Configs will also be merged from active plugins. |
<?xml version="1.0" encoding="utf-8"?> <webtop> <section mergeType="merge" id="content"> <subsection mergeType="merge" id="farcrycmsSubSection"> <menu id="farcrycorecontent" label="Code Base Management"> <menuitem sequence="1" id="codebase" label="Code Base" link="/admin/customadmin.cfm?module=customlists/coreCodeBase.cfm&plugin=daeBase" /> <menuitem sequence="2" id="codebranch" label="Code Branch" link="/admin/customadmin.cfm?module=customlists/coreCodeBranch.cfm&plugin=daeBase" /> <menuitem sequence="3" id="release" label="Code Release" link="/admin/customadmin.cfm?module=customlists/coreRelease.cfm&plugin=daeBase" /> </menu> </subsection> </section> </webtop> |
<webtop> has no attributes, except an optional mergeType
(see Modifying Core Admin section below).
(Not including <webtop>; see Webtop above)
Attribute |
Purpose |
---|---|
id |
Uniquely identifies the node |
permission |
FarCry permission required for the user to be able to access the screen element that results from the node |
label |
Text to display on the resulting screen element; this can be either straight text, or it could be a ColdFusion expression/variable to evaluate (see |
labelType |
Possible values are 'text' (default), 'expression', and 'evaluate'; if set to 'expression' or 'evaluate' the value of the |
mergeType |
See Modifying Core Admin below |
Attribute |
Purpose |
---|---|
sidebar |
Path to a page to use as the left sidebar; the path is relative to the FarCry admin section root (e.g. sidebar="custom/sidebar.cfm"; sidebar="admin/customadmin.cfm?module=....") |
content |
Path to a page to use as the content pane (right side); the path is relative to the FarCry admin section root (e.g. content="inc/content.html"; content="admin/customadmin.cfm?module=....") |
Attribute |
Purpose |
---|---|
link |
Path the link carries the user to (in the content pane); the path is relative to the FarCry admin section root (e.g. link="content/dmimage.cfm"; link="admin/customadmin.cfm?module=....") |
sequence |
The order in which the menu items should be displayed. |
Creating custom admin sections is very easy. The customadmin.xml file in projectName/customadmin has the same format as the core's webtop.xml file (nodes and attributes described above).
You can give your webtop config file any name (must not include spaces and must have the .xml extension) and you can have multiple files. Essentially any file ending in .xml found in the projectName/customadmin folder will be processed; "customadmin.xml" is just a common name. |
Add a <section> node to your customadmin.xml with all the appropriate <subsection>, <menu>, <menuitem> nodes within.
The existing core admin sections, subsections, menus, and/or menuitems can be modified, extended, or replaced.
To replace an entire core admin section, implement the same node in your customadmin.xml. Be sure to include the id
attribute and make it the same as the existing section in the core. Add a mergeType="replace"
attribute to your section node.
For example, to replace the core's security section:
<webtop> <section id="security" mergeType="replace" permission="blah" ...> <!-- implement whatever subsections/menus/menuitems --> <!-- you would like to in here --> </section> </webtop> |
Replacing a subsection, menu, or menuitem is very similar. You will have to include all parent nodes of the node you are replacing, and their id
attributes must match the corresponding nodes in the core's webtop.xml file.
For example, to replace the core's 'User' menu of the 'User Management' subsection of the 'Security' section:
<webtop> <section id="security"> <subsection id="user"> <menu id="user" mergeType="replace" label="-"> <!-- implement whatever menuitems --> <!-- you would like to in here --> </menu> </subsection> </section> </webtop> |
When you do a replace, you must supply all of the normally required attributes (such as |
To merge a node means to supplement the existing core node(s) with your own.
A duplicate node is one that exists in the core and also exists in customadmin.xml, with the same value for the id
attribute (same goes for the parents of this node). This is no different than the case above where we had to include the parents with correct id
's to replace a certain child node.
When a duplicate node is encountered while merging the webtops, mergeType="merge"
is assumed, if no mergeType
attribute is present.
mergeType="merge"
Any attributes in the core's node that are also implemented in the customadmin duplicate will be overwritten by the values in the customadmin duplicate. Attributes of the customadmin duplicate that are NOT in the corresponding core's node are added.
The children of a customadmin duplicate are appended to the corresponding core node's array of children. If a child of a customadmin duplicate does NOT have a corresponding duplicate in the core, it is added as it is. Otherwise, it is merged with the corresponding duplicate in the core following the normal merge rules (based on their mergeType
attributes).
mergeType="mergeNoReplace"
This will behave mostly the same as "merge", except existing core attributes will NOT be overwritten. New attributes will still be appended.
So far we've generated webtop links by relying on the automatically generated scaffold code. In this walkthrough we will merge these files together into a single configuration file, placing all our administration menus under a single section or tab.
<webtop> <section id="super" label="Super"> <subsection id="SuperSubSection" label="Super Section"> <!-- your menus go here! --> </subsection> </section> </webtop> |
In addition to the tabs and menus, its also possible to build custom views for the webtop overview tabs and custom cell renderers and actions for the content grids.