Objectives

By the end of this unit you will be able to modify the webtop tabs, sub-sections and menus.

Custom Admin

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.

Object Admin

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:

Sample Object Admin Scaffold

<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.

Walkthrough: Object Admin Customisation

Open all the projectName/customlists templates created by the scaffold utility for editing
Update the attributes to provide more appropriate column lists, and filterable fields

Webtop XML

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.

Multiple Webtop Configs

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.

Webtop XML Nodes

The root node is 'webtop'
Webtop has 'section' nodes as children
Section has 'subsection' nodes as children
Subsection has 'menu' nodes as children
Menu has 'menuitem' nodes as children

Sample Webtop XML Config File

<?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 id="codebase" label="Code Base" link="/admin/customadmin.cfm?module=customlists/coreCodeBase.cfm&amp;plugin=daeBase" />
        <menuitem id="codebranch" label="Code Branch" link="/admin/customadmin.cfm?module=customlists/coreCodeBranch.cfm&amp;plugin=daeBase" />
        <menuitem id="release" label="Code Release" link="/admin/customadmin.cfm?module=customlists/coreRelease.cfm&amp;plugin=daeBase" />
      </menu>
    </subsection>
  </section>
</webtop>

Webtop

<webtop> has no attributes, except an optional mergeType (see Modifying Core Admin section below).

Common Node Attributes

(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`)
labelType	Possible values are 'text' (default), 'expression', and 'evaluate'; if set to 'expression' or 'evaluate' the value of the `label` attribute is passed to the ColdFusion Evaluate function, and the result is displayed
mergeType	See Modifying Core Admin below

Attributes of the <subsection> Node

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=....")

Attributes of the <menuitem> Node

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=....")

Custom Admin

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).

Config File Names

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.

To Add a Custom Admin Section:

Add a <section> node to your customadmin.xml with all the appropriate <subsection>, <menu>, <menuitem> nodes within.

Modifying Core Admin

The existing core admin sections, subsections, menus, and/or menuitems can be modified, extended, or replaced.

Replacing a Core Admin Section

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:

Replacing A 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:

Replacing A Menu

<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>

Replacing Config

When you do a replace, you must supply all of the normally required attributes (such as sidebar, content, label) of the node you are replacing.

Merging with a Core Admin Section

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.

Walkthrough: Webtop Configuration

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.

Open the all the *.xml files under projectName/myproject/customadmin for editing
Merge all the XML files into a single file called customadmin.xml
Tidy up the XML by removing all the extraneous webtop, section and subsection elements

Place all menus under a single section called "Super"

<webtop>
  <section id="super" label="Super">
    <subsection id="SuperSubSection" label="Super Section">
      <!-- your menus go here! -->
    </subsection>
  </section>
</webtop>