FlexMenu

Inserting the FlewMenu server control onto a page

Prerequisite

You must have installed the server controls. See Installing server controls into Visual Studio Toolbox.

1. In Visual Studio, choose View > Toolbox.
2. Click the Ektron server control tab to display the server controls.
3. Drag the FlewMenu server control and drop it into the desired location on the page.

   NOTE: You also can place the cursor on the page where you want the server control, then double click the server control that you want.

   <CMS:FlewMenu ID="FlewMenu1" runat="server" />

4. Click on FlewMenu in the code to display and modify the control’s properties using the Properties window of Visual Studio. The page is updated as you modify the property values.
   —Image—

   

FlexMenu properties

The following are Ektron-specific server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified. properties. For information about native .NET properties such as font, height, width and border style, use Visual Studio^® help.

• AutoCollapseBranches (Boolean)
  • True. Whenever a new submenu opens, all other submenus close.
  • False. Other submenus remain open when a new one opens.
• CacheInterval (Double)

  The number of seconds that a server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified.’s data is cached. The default is 0 (zero). For example, if you want to cache the data for 5 minutes, set to 300. See also: Caching with server controls.

• DefaultMenuID (Long)

  The ID of a menu that appears where you insert this server control if no other menu is identified or available. If you don’t know the ID number of the menu, use the CMS Explorer to browse to it.See also: Browsing your Ektron site using CMS Explorer

  NOTE: If you want to change the Default menu's Starting menu, use the StartMenuID property.

• DisplayXslt (String)

  If desired, enter a relative or absolute path to an Xslt that determines the display of the page. If nothing is specified, the menu is output as raw XML. FlexMenus use an .xsl file to control the menu’s behavior, and a .css file to control its display. Ektron provides several sample menus, and each has an xslt file. If this is a new menu, you may find it easier to copy and edit an xslt file provided with a sample menu. See also: SampleMenu.

  WARNING! Files stored in the siteroot\Workarea folder are overwritten (or deleted) when you upgrade Ektron. To avoid problems, copy the default file to a folder outside the siteroot\workarea folder then edit it. If there is no default file, create the file outside the siteroot\workarea folder. Next, in this property, enter the path to that file relative to the site root folder.

• DoInitFill (Boolean)

  By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.

• DynamicParameter (String)

  Gets or sets the QueryString parameter to read a FlexMenu ID dynamically. Set to None. Use Default if you want to always display the default menu.

  • None. Use Default. Use the default FlexMenu ID list.
  • ekfrm. Reads a form block’s ID dynamically.
  • You may display FlexMenus dynamically by entering any value other than id. id is the default parameter for PostParameter.
• EnableAjax (Boolean)

  Set to True to enable Ajax, which only downloads sub-menus as needed.

• EnableMouseOverPopup (Boolean)
  • True. Submenus appear as soon as the cursor moves over them.
  • False. Submenus only appear if a site visitor clicks them or a keyboard equivalent.
• EnableSmartOpen (Boolean)

  Lets you prevent submenus from opening by default. Under some circumstances, such submenus look cluttered.

  • True. Submenu can open automatically. To learn how to do this, see Assigning a Folder or Template to a Menu.
  • False. Even if all required conditions are present, submenus on a FlexMenu do not automatically open.
• Hide (Boolean)

  Hides or displays the output of the control in design time and run time.

  • True. Hide the control output.
  • False. Display the control output.
• IncludeCSS (Boolean)
  • True. Load the menu's cascading stylesheet (CSSCascading Style Sheet; sets the look and formatting of a markup language document.).
  • False. Ignore the menu's CSS.
• IncludeJS (Boolean)
  • True. Load the menu's JavaScript.
  • False. Ignore the menu's JavaScript. This would be useful if you redefine the menu's output with an XSLTExtensible Stylesheet Language Transformations.
• Language (Integer)

  Set a language for viewing content; shows results in design-time (in Visual Studio) and at run-time (in a browser).

• MenuDepth (Integer)

  To let site visitors browse through all menu levels, enter zero (0). To restrict site visitors to a menu level, enter the number of the lowest level. In the following example, if you set this property to 1, a site visitor can browse through the About Us menu options but would not see the level 2 options (Company Profile and Careers).

  —Image—

  

• StartCollapsed (Boolean)

  If you set to True, when the menu first appears, all submenus are closed.

• StartLevel (Integer)

  Enter a number to indicate the level at which you want this menu to display when it first appears. To begin the menu display at the root level, enter zero (0). In the following example, the Home folder is level 0. The others are level 1.

  —Image—

  

  A site visitor can click a menu option to navigate to folders below the displayed level.

  NOTE: If you set a StartMenuID, the StartLevel property is ignored.

• StartMenuId (Integer)

  Use this property to have the default menu begin somewhere other than its root. That is, at any submenu under the default menu. For example, menu ID 46 (Products) is the default menu. However when that menu displays, you only want to show its submenus, beginning with Products Support (ID 58). In this case, enter 46 into the DefaultMenuID property and 58 into the StartMenuID property.

  NOTE: If you set a StartMenuID, the StartLevel property is ignored.

• Stylesheet (String)

  Enter the style sheet that will determine the appearance of the menus. FlexMenus use an .xsl file to control their behavior, and a .css file to control their display. Ektron provides several sample menus, and each has a .css file. If this is a new menu, you may find it easier to copy and edit a .css file provided with a sample menu. See also: SampleMenu.

  WARNING! Files stored in the siteroot\Workarea folder are overwritten (or deleted) when you upgrade Ektron. To avoid problems, copy the default file to a folder outside the siteroot\workarea folder then edit it. If there is no default file, create the file outside the siteroot\workarea folder. Next, in this property, enter the path to that file relative to the site root folder.

• SuppressAddEdit (Boolean)

  When set to True, suppress the Add and Edit buttons on the menu when a user is logged in to Ektron. The default is False.

  • True. Suppress the Add and Edit button when a user is logged in to Ektron.
  • False. Show the Add and Edit buttons when a user is logged in to Ektron.
• SuppressWrapperTags (Boolean)

  This property is set to false because Ajax uses <div> tags to rewrite the region around the tag. You cannot change the value to true.

• WrapTag (String)

  Lets a developer specify a server control’s tag.

  • Span (default). Designate an inline portion of an HTML document as a span element.
  • Div. Apply attributes to a block of code.
  • Custom. Lets you use a custom tag.

Working with the FlexMenu Xslt file

This section explains some non-intuitive elements of the *.xslt file.

• MenuFragment

  <xsl:when test="/MenuDataResult/Info/menuFragment='false'">

  A flag that indicates the XML data is not complete. Instead, it’s a fragment that begins deeper than the top level (for example, a submenu fragment).

  Because the data is incomplete, the XSLT processes the fragment differently. For example, don’t generate JavaScript startup code.

• menuConst

  <xsl:attributename="id"><xsl:value-ofselect="$menuConst"/>0_ekflexmenu</xsl:attribute>

  Each menu generates several elements, which the client code (JavaScript) accesses via a unique ID. For example, JavaScript needs to identify the selected submenu or item when a user clicks on an element.

  menuConst is only used is when creating elements without a corresponding XML block, such as when creating a structure to hold the menu.

• #NoScroll

  <xsl:attribute name="href">#NoScroll </xsl:attribute>

  NoScroll is sent to the href portion of a link when there is nothing to put there (for example, when the link is supposed to run JavaScript).

  NoScroll prevents the page from refreshing, going to another page, or scrolling when it should not.

• event

  <xsl:attribute name="onkeydown">returnekFlexMenu.menuBtnKeyHdlr
(event);</xsl:attribute>

  To make the xslt cross-browser compatible, it must support different methods of obtaining/passing the event object. In this example, the global event object is passed to the handling function.

  NOTE: event corresponds to window.event. window; is implied.

How FlexMenu determines which item is selected

The FlexMenu server control can select (highlight) options in a FlexMenu as site visitors navigate around the website. For example, a site visitor arrives at a Web page through a link in an email. If the QueryString matches the an item in a FlexMenu, the item is shown as selected.

Below is the logic the FlexMenu uses to decide when a menu item should show as selected. The list is presented in the order in which the code checks to see if an item should be highlighted.

If any menu item is selected, its parent menu is marked selected. If any menu is selected, all ancestor menus are selected. When all tests have been performed and no matches are found, the FlexMenu is rendered with no items selected.

NOTE: As soon as one condition is satisfied, the item is shown as selected and the testing stops.

NOTE: Steps 2 through 8 are each repeated recursively throughout the menu data hierarchy until either a match is found or the end is reached. If there are no matches for a test, the control continues with the next one.

1. Inspects the QueryString to see if the ekxmensel parameter is present with a matching menu node ID. This parameter is used to specify the exact node a user clicked. The node, its parent, and ancestor menus are all marked as selected.
2. Inspects the QueryString to see if a Content ID parameter value matches a menu item. If the Content ID in the QueryString matches a menu item, it is highlighted. For example, the QueryString includes ExamplePage.aspx?id=123, and a menu item links to Content ID 123.
3. Inspects the QueryString to see if a Form ID parameter value matches a menu item. If the Form ID passed in the QueryString matches a FlexMenu item, it is highlighted. For example, the QueryString includes ExamplePage.aspx?ekfrm=456, and a menu item links to Form ID of 456.
4. Inspects the QueryString for a direct match with a menu item link. If there is a match, the menu item is selected. For example, if the QueryString has ExamplePage.aspx and there is an item on the menu that matches, the menu item is shown as selected.
5. Inspects the QueryString for a id, ekfrm or pageid parameter. If one is found, the control looks for a folder association between submenus and the folder that contains the object with the given ID. If the association exists, the menu item is shown as selected.
6. Inspects the QueryString to see if there is a direct match with a menu button link. If there is a match, the menu button is selected. For example, the QueryString has ExamplePage.aspx and there is a button on the menu that matches.
7. Inspects the QueryString to see if there’s a template association with the filename. If there’s a match, the menu item is shown as selected.
8. Inspects the QueryString for the id or ekfrm parameter and whether a value greater than zero is associated with it. If so, the control checks menu buttons for use of LinkIt.aspx. If a button is using LinkIt.aspx and either id or ekfrm parameter matches, the menu button is selected.

Analyzing FlexMenu's selection of menu items

The FlexMenu server control performs a complex sequence of tasks to determine which menu option to select. If you are unsure of a FlexMenu's behavior, you can view a log that lists the reasons for a menu selection. Use the log to troubleshoot issues with a FlexMenu.

—Image—

Setting up log of FlexMenu information

Follow these steps to set up the ability to view a log of FlexMenu display information.

1. Open your site root/web.config file.
2. Under system.diagnostics, set LogLevel to 4. Save and close web.config.
   —Image—

   

3. Edit the .aspx or .ascx page that hosts the FlexMenu control.
4. Set the control's LogInfo property to true and save the page.

   <CMS:FlexMenu ID="FlexMenu1" LogInfo="True" runat="server" /> 

   NOTE: It may be helpful to temporarily disable the menu's cache by setting CacheInterval="0".

5. Refresh the browser that contains the FlexMenu you edited in the Step 4.
   —Image—

   

6. Using the Windows Event Viewer, look for the newest information-level event that contains Message: FlexMenu (under the timestamp line).
   —Image—

   

The event message identifies the reason the menu node was selected. Or, if no matches were found, the message indicates that nothing is selected.