UNIT 09 - The Webtop

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:

<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

1. Open all the projectName/customlists templates created by the scaffold utility for editing
2. 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.

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

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

Attributes of the <subsection> Node

Attributes of the <menuitem> Node

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

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:

<webtop>
  <section id="security" mergeType="replace" permission="blah" ...>
    <!-- implement whatever subsections/menus/menuitems -->
    <!-- you would like to in here -->
  </section>
</webtop>

Replacing a Core Admin Subsection/Menu/Menuitem

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>

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.

1. Open the all the *.xml files under projectName/myproject/customadmin for editing
2. Merge all the XML files into a single file called customadmin.xml
3. Tidy up the XML by removing all the extraneous webtop, section and subsection elements
4. 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>