Appendix B: XML Definitions

First, here are a few things to remember about XML: XML is case-sensitive. A tag with the name <menu> is not the same as a tag with the name <MENU> or <Menu>. In the CNS Menu XML Definitions, everything is lowercase except for the root <CNSMenu> tag. This includes attributes; all attributes are in lowercase. Attributes are of the form:

name="value"

name='value'

The "value" part must have quotes around it, although they can be single or double quotes.

You can put comments in your XML markup. Comments start with "", and cannot contain two sequential dashes anywhere in the comment.

Now on to the XML tags found in CNS Menu.

CNSMenu Tag

This is the Root Tag of the CNS Menu XML documents. It is the equivalent of the <HTML> tag in HTML documents. The only tags that can appear inside the root <CNSMenu> tag are the <menu>, <updatemenuitem>, <insertmenuitem>, and <deletemenuitem> tags. This tag has no attributes.

deletemenuitem Tag

This tag allows you to delete a menu item from any menu you have previously defined. This tag is used by itself and does not need to appear within <menu> or <submenu> tags. You need to at least define the name attribute to have a valid <deletemenuitem> tag. This is an empty tag, so you can either use a forward-slash before the closing angled bracket ("/>") or follow the tag immediately with a closing </deletemenuitem> tag. This tag has one attribute, which is required:

name Attribute: Defines the "path" to the menu item that you are deleteing. The "path" is made up of the menu name, followed by any submenu names, followed by the actual name of the menu item, all separated with the forward-slash, and looks like "menu name/submenu name/menu item name". This attribute is required.

Example

<deletemenuitem name="my menu/Click Me" />
Deletes the menu item named "Click Me" from the menu named "my menu".

<deletemenuitem name="my menu/See Also/Plants" />
Deletes the menu item named "Plants" from the sub menu named "See Also" of the menu named "my menu".

insertmenu Tag

This tag allows you to insert any menu into another menu when that menu is displayed. The menu you are inserting does not have to be defined when you define the parent menu (the one you are inserting into), but it does need to be defined by the first time you display the parent menu. The items from the inserted menu are inserted directly into the parent menu. If you want to insert the menu as a sub menu, you must wrap the <insertmenu> tag in <submenu> and </submenu> tags. If none of the menu items from the menu you are inserting have databases and/or scripts defined, then the parent menu's default database and default script will be used. You need to at least define the name attribute to have a valid <insertmenu> tag. This is an empty tag, so you can either use a forward-slash before the closing angled bracket ("/>") or follow the tag immediately with a closing </insertmenu> tag. This tag has three attributes, one of which is required:

name Attribute: Defines the name of the menu you want to insert. When you show the parent menu, this name must equal a name of another menu you have defined. This attribute is required.
groupid Attribute: Defines a user-supplied group identifier for this inserted menu. This is used in conjunction with the modifierkeys attribute to selectively show alternative menu items depending on which modifier keys are held down. See the Hidden Items Example in the CNS Menu example database for examples that use this attribute. This attribute is optional; default value is "".
modifierkeys Attribute: Defines the modifier keys that are required in order to insert this menu. Specify "none" or "shift", "ctrl", "opt", "cmd", or combinations using the plus sign ("shift+ctrl+cmd"). If the specified modifier keys are not held down when the parent menu is shown, this menu will not be inserted. If you are making a cross-platform solution, you will only want to use the "ctrl" and "shift" modifier keys because windows does not have the "opt" and "cmd" keys. This attribute is optional; default value is "none".

Example

<insertmenu name="Layouts" />
Inserts a menu named "Layouts" into the current menu.

<insertmenu name="Hidden" modifierkeys="shift+cmd" />
Inserts a menu named "Hidden" into the current menu if the Shift and Command keys are held down.

insertmenuitem Tag

This tag allows you to insert a new menu item into any menu you have previously defined. The <insertmenuitem> tag is useful for creating menus based on records in a portal. This tag is used by itself and does not need to appear within <menu> or <submenu> tags. This tag is an almost exact replica of the <menuitem> tag, except that you must specify the "path" to the menu item you want to insert before so that CNS Menu knows where to insert the new item. If you want to insert a menu item as the last item on the menu, use "__LAST__" as the item name. You need to at least define the name and before attributes to have a valid <insertmenuitem> tag. This is an empty tag, so you can either use a forward-slash before the closing angled bracket ("/>") or follow the tag immediately with a closing </insertmenuitem> tag. This tag has eleven attributes, two of which are required:

name Attribute: Defines the name of the menu item. This name appears on the menu. If the name is defined as "-", a separator will be placed at this location in the menu instead of a normal menu item. If you are defining a menu separator, only the groupid and modifierkeys attributes will be used; all others will be ignored. The name of the chosen menu item can be retrieved using the CNSMenu_GetMenuChoice function. This attribute is required.
before Attribute: Defines the "path" to the menu item that you are inserting before. The "path" is made up of the menu name, followed by any submenu names, followed by the actual name of the menu item, all separated with the forward-slash, and looks like "menu name/submenu name/menu item name". If inserting as the last item, use "__LAST__" as the menu item like "menu name/submenu name/__LAST__". This attribute is required.
autocreatemenu Attribute: Defines whether or not CNS Menu should auto create the menu or any submenus specified in the "path" from the before attribute if they do not already exist. In other words, if you specify "my menu/Layouts/__LAST__" as the before attribute, but the "Layouts" submenu does not exist, CNS Menu will create it. Specify either "yes" or "no". This attribute is optional; the default value is "no".
db Attribute: Defines the database that contains the script for this menu item. If this is not defined, the default database from the parent submenu or menu will be used. If the parent submenu or menu does not have a database defined, the current database will be used. This attribute is optional; the default value is "".
script Attribute: Defines the script to be called when the user selects this menu item. If this is not defined, the default script from the parent submenu or menu will be used. This attribute is optional; the default value is "".
value Attribute: Defines a user-supplied value for this menu item. This value can be retrieved using the CNSMenu_GetMenuValue function and is also set as the "Script Parameter" if a script is called. This attribute is optional; the default value is "".
enabled Attribute: Defines whether or not this menu item is enabled. Specify either "yes" or "no". If the menu item is disabled, it will appear greyed and the user will not be able to select it. This attribute is optional; the default value is "yes".
groupid Attribute: Defines a user-supplied group identifier for this menu item. This is used in conjunction with the modifierkeys attribute to selectively show alternative menu items depending on which modifier keys are held down. See the Hidden Items Example in the CNS Menu example database for examples that use this attribute. This attribute is optional; default value is "".
modifierkeys Attribute: Defines the modifier keys that are required in order to show this menu item. Specify "none" or "shift", "ctrl", "opt", "cmd", or combinations using the plus sign ("shift+ctrl+cmd"). If the specified modifier keys are not held down when this menu is shown, this menu item will not be shown. If you are making a cross-platform solution, you will only want to use the "ctrl" and "shift" modifier keys because windows does not have the "opt" and "cmd" keys. This attribute is optional; default value is "none".
style Attribute: Defines the font style of this menu item. Specify "none" or "bold", "italic", "underline", or combinations using the plus sign ("bold+italic"). This attribute is optional; default value is "none".
mark Attribute: Defines the mark for this menu item. Specify "none", "check", "bullet", or "diamond". The mark is displayed to the left of the menu item. This attribute is optional; default value is "none".

Example

<insertmenuitem name="Click Me" before="my menu/Testing" script="Menu Item Click" />
Inserts a new menu item named "Click Me" before the menu item named "Testing" on the menu named "my menu".

<insertmenuitem name="Plants" before="my menu/See Also/__LAST__" autocreatemenu="yes" />
Inserts a new menu item named "Plants" as the last item on the "See Also" submenu of the menu named "my menu". If the "See Also" submenu does not exist, CNS Menu will create it.

menu Tag

This tag is the main tag for all menu definitions. You need to define at least the name attribute to have a valid <menu> tag. This tag can contain <menuitem>, <submenu>, and <insertmenu> tags. This tag has eight attributes, one of which is required:

name Attribute: Defines the name of this menu. You use this name when telling CNS Menu to display the menu, when deleting the menu, or when inserting the menu into another menu. This attribute is required.
action Attribute: Defines whether or not this is a new menu or an update to an existing menu. Specify either "new" or "update". This attribute is optional; default value is "new".
defaultdb Attribute: Defines the default database for all the menu items contained in this menu. If you do not specify a database when defining a menu item, this default database will be used. This attribute is optional; default value is "".
defaultscript Attribute: Defines the default script for all the menu items contained in this menu. If you do not specify a script when defining a menu item, this default script will be used. This attribute is optional; default value is "".
defaultvalue Attribute: Defines the default value for all the menu items contained in this menu. If you do not specify a value when defining a menu item, this default value will be used. This attribute is optional; default value is "".
modifierkeys Attribute: Defines the modifier keys that are required in order to show the menu. Specify "none" or "shift", "ctrl", "opt", "cmd", or combinations using the plus sign ("shift+ctrl+cmd"). If the specified modifier keys are not held down when you call CNSMenu_ShowMenu, then the menu will not be shown. Instead, the default script will be called in the default database. If you are making a cross-platform solution, you will only want to use the "ctrl" and "shift" modifier keys because windows does not have the "opt" and "cmd" keys. This attribute is optional; default value is "none".
faildb Attribute: Defines the database that contains the fail script. If the failscript attribute is defined, but this attribute is not, the plug-in will use the current database. This attribute is optional; default value is "".
failscript Attribute: Defines the script the plug-in calls if the user clicks off the menu without selecting anything. This attribute is optional; default value is "".

Example

<menu name="test">
Defines a menu named "test".

<menu name="test" action="update">
Updates the menu named "test".

<menu name="my menu" defaultdb="mydb.fp7" defaultscript="menu click">
Defines a menu named "my menu", whose menu items will use the "menu click" script in the "mydb.fp7" database unless those menu items define their own script and/or database.

<menu name="menu" defaultdb="test.fp7" defaultscript="find all" modifierkeys="ctrl">
Defines a menu named "menu", whose menu items will use the "find all" script in the "test.fp7" database unless those menu items define their own script and/or database. If the Control key is not held down when the CNSMenu_ShowMenu function is called, the "find all" script in the "test.fp7" database will be called instead of showing the menu.

<menu name="menu" failscript="Clear field">
Defines a menu named "menu" which will call the script named "Clear field" in the current database if the user clicks off the menu without selecting anything.

menuitem Tag

This tag is used to define a single item on the menu or submenu. You need to at least define the name attribute to have a valid <menuitem> tag. This is an empty tag, so you can either use a forward-slash before the closing angled bracket ("/>") or follow the tag immediately with a closing </menuitem> tag. This tag has nine attributes, one of which is required:

name Attribute: Defines the name of the menu item. This name appears on the menu. If the name is defined as "-", a separator will be placed at this location in the menu instead of a normal menu item. If you are defining a menu separator, only the groupid and modifierkeys attributes will be used; all others will be ignored. The name of the chosen menu item can be retrieved using the CNSMenu_GetMenuChoice function. This attribute is required.
db Attribute: Defines the database that contains the script for this menu item. If this is not defined, the default database from the parent submenu or menu will be used. If the parent submenu or menu does not have a database defined, the current database will be used. This attribute is optional; the default value is "".
script Attribute: Defines the script to be called when the user selects this menu item. If this is not defined, the default script from the parent submenu or menu will be used. This attribute is optional; the default value is "".
value Attribute: Defines a user-supplied value for this menu item. This value can be retrieved using the CNSMenu_GetMenuValue function and will also be the "Script Parameter" if a script is called. This attribute is optional; the default value is "".
enabled Attribute: Defines whether or not this menu item is enabled. Specify either "yes" or "no". If the menu item is disabled, it will appear greyed and the user will not be able to select it. This attribute is optional; the default value is "yes".
groupid Attribute: Defines a user-supplied group identifier for this menu item. This is used in conjunction with the modifierkeys attribute to selectively show alternative menu items depending on which modifier keys are held down. See the Hidden Items Example in the CNS Menu example database for examples that use this attribute. This attribute is optional; default value is "".
modifierkeys Attribute: Defines the modifier keys that are required in order to show this menu item. Specify "none" or "shift", "ctrl", "opt", "cmd", or combinations using the plus sign ("shift+ctrl+cmd"). If the specified modifier keys are not held down when this menu is shown, this menu item will not be shown. If you are making a cross-platform solution, you will only want to use the "ctrl" and "shift" modifier keys because windows does not have the "opt" and "cmd" keys. This attribute is optional; default value is "none".
style Attribute: Defines the font style of this menu item. Specify "none" or "bold", "italic", "underline", or combinations using the plus sign ("bold+italic"). This attribute is optional; default value is "none".
mark Attribute: Defines the mark for this menu item. Specify "none", "check", "bullet", or "diamond". The mark is displayed to the left of the menu item. This attribute is optional; default value is "none".

Example

<menuitem name="Click Me" />
Defines a menu item with the caption "Click Me" that uses the default database and default script of the parent menu.

<menuitem name="Click Me" script="menu click" value="item4" />
Defines a menu item with the caption "Click Me" that runs the "menu click" script in the default database and returns "item4" when the CNSMenu_GetMenuValue or Get(ScriptParameter) functions are used.

<menuitem name="Hidden" style="bold" mark="bullet" modifierkeys="shift+opt+ctrl+cmd" db="test.fp7" script="hidden"/>
Defines a menu item with the caption "Hidden" that calls the "hidden" script in the "test.fp7" database. This item is displayed in the bold font with a bullet mark on the left, and is only displayed if the Shift, Option, Control, and Command keys are held down.

submenu Tag

This tag defines a submenu of the current menu. You can use this tag to create heiarchial menus. You need to define at least the name attribute to have a valid <submenu> tag. This tag can contain <menuitem>, <submenu>, and <insertmenu> tags. This tag has eight attributes, one of which is required:

name Attribute: Defines the name of this submenu. This name appears on the parent menu where the submenu cascades from the parent menu. This attribute is required.
defaultdb Attribute: Defines the default database for all the menu items contained in this submenu. If you do not specify a database when defining a sub menu item, this default database will be used. This attribute is optional; default value is "".
defaultscript Attribute: Defines the default script for all the menu items contained in this submenu. If you do not specify a script when defining a sub menu item, this default script will be used. This attribute is optional; default value is "".
defaultvalue Attribute: Defines the default value for all the menu items contained in this submenu. If you do not specify a value when defining a submenu item, this default value will be used. This attribute is optional; default value is "".
enabled Attribute: Defines whether or not this submenu is enabled. Specify either "yes" or "no". If the submenu is disabled, it will appear greyed and the submenu will not appear when the user places their cursor over it. This attribute is optional; default value is "yes".
groupid Attribute: Defines a user-supplied group identifier for this submenu. This is used in conjunction with the modifierkeys attribute to selectively show alternative menu items depending on which modifier keys are held down. See the Hidden Items Example in the CNS Menu example database for examples that use this attribute. This attribute is optional; default value is "".
modifierkeys Attribute: Defines the modifier keys that are required in order to show this submenu. Specify "none" or "shift", "ctrl", "opt", "cmd", or combinations using the plus sign ("shift+ctrl+cmd"). If the specified modifier keys are not held down when this menu is shown, this submenu will not be shown. If you are making a cross-platform solution, you will only want to use the "ctrl" and "shift" modifier keys because windows does not have the "opt" and "cmd" keys. This attribute is optional; default value is "none".
style Attribute: Defines the font style of this submenu. Specify "none" or "bold", "italic", "underline", or combinations using the plus sign ("bold+italic"). This attribute is optional; default value is "none".

Example

<submenu name="Go to Layout">
Defines a submenu named "Go to Layout".

<submenu name="Go to Layout" defaultdb="main.fp7" defaultscript="Change Layout">
Defines a submenu named "Go to Layout", whose menu items will use the "Change Layout" script in the "main.fp7" database unless those menu items define their own script and/or database.

<submenu name="Special" enabled="no" style="italic">
Defines a submenu named "Special" that is disabled and whose name is displayed using the italic font.

<submenu name="Hidden" modifierkeys="shift+ctrl" groupid="hidden">
Defines a submenu named "Hidden" that is only displayed if the Shift and Control keys are held down when showing the menu.

updatemenuitem Tag

This tag allows you to update the attributes of any menu item on any menu you have previously defined. The <updatemenuitem> tag is useful for enabling a previously disabled menu item (or vice versa), placing a mark next to an item, or changing any other attribute assocated with a menu item. This tag is used by itself and does not need to appear within <menu> or <submenu> tags. This tag is an almost exact replica of the <menuitem> tag, except that instead of specifying just the name of the menu item, you must specify the "path" to the menu item so that CNS Menu knows which item to update. Only those attributes that you define will replace the original menu item's attributes. You need to at least define the name attribute to have a valid <updatemenuitem> tag. This is an empty tag, so you can either use a forward-slash before the closing angled bracket ("/>") or follow the tag immediately with a closing </updatemenuitem> tag. This tag has nine attributes, one of which is required:

name Attribute: Defines the "path" to the menu item that you are updating. The "path" is made up of the menu name, followed by any submenu names, followed by the actual name of the menu item, all separated by the forward-slash, and looks like "menu name/submenu name/menu item name". This attribute is required.
db Attribute: Defines the database that contains the script for this menu item. If this is not defined, the default database from the parent submenu or menu will be used. If the parent submenu or menu does not have a default database, the current database will be used. This attribute is optional; if the attribute is missing, the original database attribute will be unchanged; if the attribute exists, but is set to "", the original database attribute will be cleared.
script Attribute: Defines the script to be called when the user selects this menu item. If this is not defined, the default script from the parent submenu or menu will be used. This attribute is optional; if the attribute is missing, the original script attribute will be unchanged; if the attribute exists, but is set to "", the original script attribute will be cleared.
value Attribute: Defines a user-supplied value for this menu item. This value can be retrieved using the CNSMenu_GetMenuValue function and is also the "Script Parameter" if a script is called. This attribute is optional; if the attribute is missing, the original value attribute will be unchanged; if the attribute exists, but is set to "", the original value attribute will be cleared.
enabled Attribute: Defines whether or not this menu item is enabled. Specify either "yes" or "no". If the menu item is disabled, it will appear greyed and the user will not be able to select it. This attribute is optional; if the attribute is missing, the original enabled attribute will be unchanged.
groupid Attribute: Defines a user-supplied group identifier for this menu item. This is used in conjunction with the modifierkeys attribute to selectively show alternative menu items depending on which modifier keys are held down. See the Hidden Items Example in the CNS Menu example database for examples that use this attribute. This attribute is optional; if the attribute is missing, the original groupid attribute will be unchanged; if the attribute exists, but is set to "", the original groupid attribute will be cleared.
modifierkeys Attribute: Defines the modifier keys that are required in order to show this menu item. Specify "none" or "shift", "ctrl", "opt", "cmd", or combinations using the plus sign ("shift+ctrl+cmd"). If the specified modifier keys are not held down when this menu is shown, this menu item will not be shown. If you are making a cross-platform solution, you will only want to use the "ctrl" and "shift" modifier keys because windows does not have the "opt" and "cmd" keys. This attribute is optional; if the attribute is missing, the original modifierkeys attribute will be unchanged; if the attribute is "none", the original modifierkeys attribute will be cleared.
style Attribute: Defines the font style of this menu item. Specify "none" or "bold", "italic", "underline", or combinations using the plus sign ("bold+italic"). This attribute is optional; if the attribute is missing, the original style attribute will be unchanged; if the attribute is "none", the original style attribute will be cleared.
mark Attribute: Defines the mark for this menu item. Specify "none", "check", "bullet", or "diamond". The mark is displayed to the left of the menu item. This attribute is optional; if the attribute is missing, the original mark attribute will be unchanged; if the attribute is "none", the original mark attribute will be cleared.

Example

<updatemenuitem name="my menu/Click Me" enabled="no" />
Updates the "Click Me" menu item in the menu named "my menu" to be disabled.

<updatemenuitem name="my menu/Go to Layout/Main" mark="check" />
Updates the "Main" menu item in the submenu "Go to Layout" of the menu named "my menu" to be checked.

<updatemenuitem name="test menu/Item4" db="" script="" />
Clears the database and script attributes of the "Item4" menu item in the menu named "test menu".