Stitch 1.1 For Mach-II

download 1.1 [.zip] (recommended)
download 1.0 [.zip]

What is it?

Stitch is a plugin that utilizes an XML configuration file and cfc utility that enables Mach-II developers to create event groupings that effectively remove dependencies to event naming conventions.

Why is it?

There are numerous event naming conventions used by developers to assist in the management of things like navigation and security; often this leads to excessively lengthy or complicated event names that introduce dependencies to the architecture of the first version of the application. Stitch was developed to reduce the frustration that came with managing event names in relation to navigation which led to the discovery of other clever uses such as: security, CSS management, and changing the way errors are handled in different sections of an application.

Events should have structured names that represent what they do and should not be forced to contain logic to control views that change over time. Use Stitch to organize your cleanly named events into "sections" and then utilize two methods available on the Stitch utility cfc to check what event your view is in or what section your view is in.

Installation

There are two components that come with the Stitch plugin: stitch.cfc and stitchManager.cfc. The stitch.cfc is the actual plugin that handles the interpretation of the Stitch configuration file and event monitoring. The stitchManager.cfc is a utility component that is introduced into every event as an event argument. The utility is named based on the stitchManagerName parameter passed in to the plugin via the Stitch plugin configuration element in the Mach-II configuration file (see below). Put both files in your plugins directory.

Also included is a helpful utility, stitchAid.cfm, that auto-generates all of your event keys to be used in the stitch configuration xml. Put this file in the plugins directory and access via your browser like this: http://mydomain.com/plugins/stitchAid.cfm.

Configuration

Mach-II Property Element

  1. <property name="stitchConfig" value="config/stitch.xml" />

Mach-II Plugin Element

  1. <plugin name="stitch" type="plugins.stitch">
  2. <parameters>
  3. <parameter name="stitchManagerName" value="stitch" />
  4. </parameters>
  5. </plugin>

You may also omit the stitchManagerName parameter and the plugin will default the name of the Stitch Manager in the event args to "stitch". The element then would like this:

  1. <plugin name="stitch" type="plugins.stitch" />

Stitch Configuration XML

The configuration supports an infinite hierarchy. The root node must be present in order for the plugin to properly parse the XML. Two nodes are used to help you organize the events: section and key. The section node has one attribute "name" which allows you to associate an identifier to that group of events and all sections within it (NOTE: using a duplicate section name on the same level will simply overwrite the registration of the previous section with that name).

You may also list the same events in multiple sections; Stitch simply continues to add the section mappings to the event if they do not already exist (see last section called "SSL" in configuration example).

  1. <?xml version="1.0" encoding="UTF-8"?>
  3. <keys>
  4. <key event="login" />
  5. <section name="admin">
  6. <section name="project">
  7. <key event="project.list" />
  8. <key event="project.create" />
  9. <key event="projectRoleType.list" />
  10. <key event="projectRoleType.create" />
  11. </section>
  12. <section name="useCase">
  13. <key event="useCase.list" />
  14. <section name="editUseCase">
  15. <key event="useCase.create" />
  16. <key event="useCase.detail" />
  17. <key event="step.list" />
  18. <key event="step.create" />
  19. <key event="requirement.list" />
  20. <key event="requirement.create" />
  21. <key event="change.list" />
  22. <key event="change.create" />
  23. </section>
  24. </section>
  25. </section>
  26. <section name="public">
  27. <section name="project">
  28. <section name="survey">
  29. <key event="survey.list" />
  30. <key event="survey.create" />
  31. </section>
  32. <section name="interview">
  33. <key event="interview.list" />
  34. <key event="interview.create" />
  35. </section>
  36. </section>
  37. </section>
  38. <section name="ssl">
  39. <key event="login" />
  40. <key event="survey.create" />
  41. <key event="interview.create" />
  42. </section>
  43. </keys>

Or, you may opt to use the wildcard syntax * to make your configuration much smaller. Here is the same example above using the wildcard.

  1. <?xml version="1.0" encoding="UTF-8"?>
  3. <keys>
  4. <key event="login" />
  5. <section name="admin">
  6. <section name="project">
  7. <key event="project.*" />
  8. <key event="projectRoleType.*"/>
  9. </section>
  10. <section name="useCase">
  11. <key event="useCase.*" />
  12. <section name="editUseCase">
  13. <key event="useCase.create" />
  14. <key event="step.*" />
  15. <key event="requirement.*" />
  16. <key event="change.*" />
  17. </section>
  18. </section>
  19. </section>
  20. <section name="public">
  21. <section name="project">
  22. <section name="survey">
  23. <key event="survey.*" />
  24. </section>
  25. <section name="interview">
  26. <key event="interview.*" />
  27. </section>
  28. </section>
  29. </section>
  30. <section name="ssl">
  31. <key event="login" />
  32. <key event="survey.*" />
  33. </section>
  34. </keys>

Usage

As said previously, the Stitch plugin injects the Stitch Manager component into the event arguments for every event. The default name for this argument is "stitch" but can be changed to what ever you like in the Mach-II plugin configuration. Here is how you access the component:

  1. <cfset stitch = event.getArg("stitch")>

There are five methods available on the component; three are for debugging and three are for use in determining what event or section you are in.

isSection(string):Boolean

Checks to see if current event is in said section.

  1. <cfset showMenu = stitch.isSection("admin")>

Depending on how you organize your views and what you are trying to accomplish with Stitch, you can check the status of multiple sections in one line like this:

  1. <cfset showMenu = stitch.isSection("admin") and stitch.isSection("project")>

isEvent(String):Boolean

Validates current event name with argument.

  1. <cfset isActive = stitch.isEvent("requirement.create")>

Useful for setting individual button states for pages within a section.

isEventIn(List):Boolean

Returns a Boolean indicating whether or not the current event is contained in the list.

sectionDump(void):List

Returns a comma delimited list of sections the current event is in.

eventDump(void):List

Returns a comma delimited list of events that were fired leading up to the currently displayed event.

hiveDump(void):Struct

Returns a structure containing the keys and sections.

Mach II
FuseboxReactorColdSpring