BreadCrumb

Your website is made up of Web forms. Each page depends on a form to determine much of its appearance. Forms and pages have a parent > child relationship. That is, a form can be associated with any number of pages. When you define breadcrumb properties, you define them for a form. All pages that use a form inherit its breadcrumb properties.

Assume, for example, that a Web form is used for the Human Resources section of your website. You might use the title Human Resources to identify the form in the BreadCrumb server control. Whenever a page is visited that uses that form, Human Resources appears on the breadcrumb trail -- that is, the form title appears, not the individual page.

Inserting the Breadcrumb 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 Breadcrumb 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:Breadcrumb ID="Breadcrumb1" runat="server" />
  4. Click on Breadcrumb 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.

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

  • CurrentPageIndicator (String)

    If desired, enter one or more symbols or characters that identify the current page in the breadcrumb trail. See example below.

    These characters appear after the image or title that identifies the current page in the breadcrumb trail.

  • DefaultContentID (Long)

    Gets or Sets the ContentID for the BreadCrumb display title.

  • DisplayStyle (String)

    Indicate how to display the breadcrumb trail: horizontally or vertically. The default is Horizontal.

  • DisplayTitle (String)

    IMPORTANT: This property is for code-behind only and does not show up in the Visual Studio Properties window. It cannot be set in design time.

    Enter text to describe this Web form in the breadcrumb trail. For example, if the Web form’s properties you are defining is used for all Human Resources pages on your site, enter Human Resources.

    If you define an image in the IconPath property below, the image appears in the trail, followed by this text.

  • 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 content ID dynamically.

  • Hide (Boolean)

    Used to hide the breadcrumb trail in design time and run time.

    • True. Hide breadcrumb trail
    • False. Show breadcrumb trail
  • IconAlt (String)

    If you define an image in the IconPath property, enter “Alt” text to appear if a site visitor hovers the cursor over that image. Here is an example.

  • IconPath (String)

    If you want the breadcrumb trail to display an image to identify this Web form, enter the path to the image. For example: siteroot\Workarea\Images\bc_meta_icon.gif

    IMPORTANT: The image location must be relative to the Web root.

    On the breadcrumb trail, the image precedes any text defined in the DisplayTitle property.

    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.

  • Language (Integer)

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

  • LinkLastItem (Boolean)

    Use this property to determine whether the last breadcrumb item appears as a hyperlink on this Web form. If this property is set to True, and a user clicks the item, the current page reappears.

    • True. Last item is a hyperlink
    • False. Last item is an image or text only; the user cannot click on it
  • LinkTarget (String)

    Determines the type of window that appears when you click a link in the server control.

    • _Self (default). Opens in same window.
    • _Top. Opens in parent window.
    • _Blank. Opens in new window.
    • _Parent. Opens in the parent frame.
  • MaxItems (Integer)

    Enter the maximum number of items in the breadcrumb trail on this Web form. The default is 5. If you set a value of 1 or greater and the user navigates beyond that number of pages, only the most recent pages appear. The older pages disappear from the trail. 0 (zero) = unlimited.

  • MetadataName (String)

    Specify the name of a Metadata Type that you want to associate with the page.

    BreadCrumb metadata type

    To associate a metadata type with the BreadCrumb server control:

    1. In the properties window for the BreadCrumb server control, click on the MetadataName property.
    2. Click Ellipses ().
    3. If you are not logged in, log in using the CMS Explorer window.
    4. The Browsing Metadata screen appears.

    5. Select a Metadata Type to apply to the BreadCrumb server control.
    6. Set the DynamicParameter to ID. This allows the metadata to reflect the content block on the page.
  • Mode (String)

    Lets you display the breadcrumb trail as non-hyperlinked, plain text. The default is Normal.

    • Normal. Breadcrumb trail is hyperlinked

    • DisplayOnly. Breadcrumb trail is plain text

  • Separator (String)

    Enter one or more characters to separate breadcrumb trail items on this Web form. The default character is the greater than sign (>).

  • SuppressWrapperTags (Boolean)

    Suppresses the output of the span/div tags around the control.

    • True. Suppress wrap tags.
    • False (default). Allow wrap tags.
  • 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.

Determining a breadcrumb trail’s appearance

For each Web form, you can customize the breadcrumb trail. For example, you might want the breadcrumb trail to appear horizontally on one Web form and vertically on another. The following property list determines the breadcrumb trail's appearance.

  • CurrentPageIndicator. Symbols or characters to identify the current page.
  • DisplayStyle. Whether it appears horizontally or vertically.
  • LinkLastItem. Whether the last item is a hyperlink.
  • LinkTarget. The type of window that appears when a user clicks an item.
  • MaxItems. The maximum number of items.
  • Mode. Whether the breadcrumb trail appears as linked text or plain text.
  • Separator. Symbols or characters that separate items.

Determining how form pages appear on breadcrumb trail

Use these properties define how any page that uses this form appears within a breadcrumb trail. It does not matter where the trail appears.

Note that you can use text, an image, or both to describe the form within the breadcrumb trail. If you use both, the image appears first, followed by the text. The following property list determines how the Web form appears on a breadcrumb trail.

  • DisplayTitle. Text to describe it.
  • IconAlt. “Alt” text associated with image specified in IconPath property.
  • IconPath. Image to define it.

Creating a horizontal or vertical breadcrumb trail

You can display a breadcrumb trail vertically or horizontally on a Web page with the DisplayStyle parameter. In addition, you can define how many breadcrumbs (MaxItems) are left for site visitors to navigate back. You can also use an image and Alt text instead of, or in addition to, text to display the breadcrumb trail. The foillowing examples show the variations and are described in BreadCrumb properties.

NOTE: If a site visitor revisits a page that is in the breadcrumb trail already, the breadcrumb trail reverts back to that point in the trail. For example, if you visit the following pages Dev > FAQ > WebForm > PR, and then return to FAQ, the breadcrumb trail looks like this: Dev > FAQ.

  • Horizontal; text only

  • Horizontal with images

  • Horizontal with images and Alt text

  • Vertical; text only

  • Vertical with images

  • Vertical with images and Alt text

To implement sitemap breadcrumb navigation, add a BreadCrumb server control to every Web form in your site. Doing this ensures that a breadcrumb trail may appear on each Web page.

Using the BreadCrumb server control

NOTE: Do not add a BreadCrumb server control to a Web form that contains a Calendar server control. When both controls appear on a page and a site visitor clicks on different months, the BreadCrumb trail could look like this: Calendar > Calendar > Calendar > Calendar > Calendar. This happens because each time a site visitor clicks on a month, you are in effect opening a new Web form.

Add a BreadCrumb server control to each Web form for which you want to create a breadcrumb trail. To use the BreadCrumb server control:

  1. Open a Web form for which you want to create a breadcrumb trail.
  2. Drag and drop the BreadCrumb server control onto the Web form.
  3. Set the DisplayTitle property.
  4. Save the Web form.
  5. Repeat steps 1 through 4 for all Web forms in the breadcrumb trail.
  6. Open a browser.
  7. View a Web page with a BreadCrumb server control in it.
  8. Navigate to the rest of the Web pages that contain BreadCrumb server controls.
  9. As you move around, the pages are added to the breadcrumb trail.

Displaying a content block’s title in the breadcrumb trail

By adding a line or 2 of code, the breadcrumb trail can display a content block's title. You can add a line of code to each Web form. Or, if your content is dynamic, add the code once and, each time a new piece of content is called dynamically, a new breadcrumb is created.

You can only use one content block per Web form with the breadcrumb. If a page has multiple content blocks, select one that best describes the page.

  1. Drag and drop a ContentBlock server control on a Web form.
  2. Choose a DefaultContentID for the content block.
  3. Drag and drop a BreadCrumb server control on the same form.
  4. Remove the word Title from the DisplayTitle property.
  5. Add the following line of code to the pageload event code-behind:
    BreadCrumb1.DisplayTitle = ContentBlock1.EkItem.Title
  6. Build the project.
  7. View the Web form in a Web browser.

The following example content block shows titles used as breadcrumbs.

The word Title appears in the breadcrumb trail when the DisplayTitle property is left empty. Even with the added code, if the breadcrumb loads before the content block, the breadcrumb has no information in the DisplayTitle property and therefore displays the word title by default.

If the word Title appears in the breadcrumb trail, check to make sure the word Title does not appear in the DisplayTitle property. Next, if Title still appears, add the following line of code to the page load event of the code-behind:

ContentBlock1.Fill()

The code in the page load event should now look like this:

ContentBlock1.Fill()
BreadCrumb1.DisplayTitle = ContentBlock1.EkItem.Title

This ensures that the content block information is loaded first.