Skip to content

Introduction

imperia allows simple navigation, but also Site Maps or Breadcrumbs.

The navigation files are transferred as Virtual Includes (SSI) to the target systems. The navigation generation takes place by using the configuration files. Based on Template-like possibibilities you can adapt the navigation to your needs.

Configuration#

The navigation is controlled by a configuration file. The example config/navigation_generator.conf.sample can be used as a basis. This file should be renamed then(e.g. config/navigation_generator.conf).

Under the main node <root>, the general configuration item <common> must be available in the configuration. After this point, you can set the controls on how files are called and how they are transferred to a live system.

The name of the generated files is controlled by the following:

filename = "/ssi/nav/intra/<!--nav_element-->/<!--node_id-->/<!--lingua-->.ssi"

The available values are:

  • <!--directory-->, e.g. /cms01/intra
  • <!--node_id-->, e.g. /10/17/29
  • <!--cat_id-->, e.g. 17
  • <!--lingua-->, e.g. de
  • <!--nav_element-->, e.g. h_nav

In addition to creating the navigation elements, an XML file for the importer is written in which all newly created files are listed in the form of IBlocks.

Transfer Category transfer_cat_id#

The transfer category is defined in the config files of the navigation generation (by default site/config/navigation_generator.conf) by the key transfer_cat_id (z.B. transfer_cat_id = "/6/7/8") in the space common. A NodeID is given to a category, through transfer_cat_id, which lies on a non-interactive workflow. The category's template consists of one entry.

<!--IMPERIABLOCK-->
<!--
<IMG SRC="<!--XX-IBLOCK-file-->" />
-->
<!--/IMPERIABLOCK-->

It is important to note that the commented-out section ensures that files specified in IBlock are not displayed, but are transferred.

Counting documents count_documents#

You can set count_documents to a valid value (count_documents = 1) in order to activate the counting of documents from the longLiveLog.
Set the language pattern in count_documents_lingua_pattern in order to get the language tag of the first element.

    count_documents_lingua_pattern = "^/([a-z]{2})/"

    count_documents_lingua_pattern = "\.([a-z]{2})$"

Creating Navigation Files#

The navigation generation is initiated via a menu item in the administrative menu. All navigation elements can be produced with this menu item.

This menu item is entered in the menu configuration by a “Link”, e.g.:

NEWWIN:/cgi-bin/site_navgen.pl?
    conf=/config/navigation_generator.conf&
    rootNodeId=/13
  • This script generates code snippets that are included in the HTML pages. For each level of navigation, a code snippet is generated. The names of the created SSI files are defined in the configuration file.
  • conf=/config/navigation_generator.conf describes the file that will be used to create the navigation.
  • rootNodeId=/13 describes the NodeID at which to start the navigation generation, see also section Configuration.

When creating multilingual navigation, the metavariables need to be set in the categories' properties.
For each language a SSI is generated, which then has to be set in the template accordingly (via lingua).

In addition to the general block (common) any number of navigation elements can be produced. Typically, a horizontal navigation (here, h_nav), a vertical navigation (here, v_nav) and a site map (here, sitemap).

The names of navigation elements are freely chosen as long as they do not violate the XML naming convention.

An example of a horizontal navigation shows the working methods of the elements:

        (Code wrapped for display purposes!)

<h_nav>
 file_startlevel = "0"
 file_maxlevel = "5"
 content_startlevel = "0"
 content_maxlevel = "7"

 li_snippet <<EOF
    #IF ("<!--XX-current-->")
        <strong><!--XX-name--></strong>
    #ELSIF ("<!--XX-active-->")
        <a href="<!--XX-link-->" title="<!--XX-description-->">
                 <!--XX-name--></a> - <!--XX-ul_content-->
    #ENDIF
EOF

 ul_snippet <<EOF
  <!--XX-li_content-->
EOF

</h_nav>

  • file_startlevel and file_maxlevel control on which levels files will be generated. In the example above files can be generated only to level 5.

  • The variables content_startlevel and content_maxlevel control which levels of a category tree should be displayed within files.

  • The ul_snippet and li_snippet variables control how each entry in the category will be structured.
    This means that for the projection of the tree in the navigation, these variables are created for each element and are locked within each other via the <!--XX-li_content--> and <!--XX-ul_content--> variables.
    The following variables are available:

    !!!tip "Note"
    In the recursion, for e.g. li or ul snippets, you can also refer to page variables - as in a template too - e.g. `<!--XX-PAGEVARIABEL-->`.
    Variable Description
    <!--XX-name--> Category's name (language dependent)
    <!--XX-description--> Category's description (language dependent)
    <!--XX-directory--> Directory
    <!--XX-cat_skip--> true, if the category contains __ip_skip_nav = 1
    or an entry in __nav_gen_skip_linguas : [de, en] for the current language
    <!--XX-doc_count--> Document count in the current category of the language
    <!--XX-filename--> File name
    <!--XX-link--> A special link (__ip_link)
    <!--XX-linktarget--> Link target
    <!--XX-level--> Editing Level
    <!--XX-levelindex--> Level index
    <!--XX-current--> Current menu item (Bool)
    <!--XX-active--> Active menu item (Bool)
    <!--XX-catid--> Category ID
    <!--XX-nodeid--> the nodeid
    <!--XX-has_children--> true if there are subentries
    <!--XX-current_nodeid--> Node ID of the category whose navigation is currently processed

Process description in the development-/target system#

  1. The navigation generation is performed by authorized imperia users. The entire navigation is first created on the development system.
  2. After a navigation is generated, the include files only exist on the develop system.
  3. To transfer them to the live server an imperia document is imported. The necessary data is created by the script and written in the form of an XML file in the import directory (/site/import).
  4. The XML document is imported in imperia as a new document in a category provided for this purpose. Whether the navigation files are unlocked directly on a live server (auto publish) or are unlocked only after an approval step (approval), can be controlled via the category's workflow.

Example "Main_Nav"#

In the following we show you an exmaple for the configuration/generation of a horizontal navigation named main_nav.

The following configuration of the navigation is processed for each page; only in case of the currently opened page, i.e. "active", a different CSS class is chosen in order to highlight the opend level.

The navigation is generated on basis of the following category tree:

-Root-Node (0)
    -City Topics (1)    
        -Hot Topics (2)
            -News (3)
            -'Events (3)
        -Education (2)
            -Schools (3)
            -Child care (3)
    -Citizen Service (1)
    -Tourism Office (1)


0. Navigation as a HTML Code

The HTML Code of the navigation is as follows:

In the following example the level 2 "Eductation" is opened in the navigation:

"Level" is indicated regarding the configuration that is explained in the next step.

     <ul class="level_1 clearfix">                          "Level 1 ul"
       <li>

         <a href="/index.html.de">City Topics</a>           "Level 1 li"
        <ul class="level_2">                                "Level 2 ul"
       <li>
         <a href="/aktuelles/index.html.de">
             <span class="nav_label">Hot Topics</span>      "Level 2 li"
     </a>
             <ul class="level_3">                           "Level 3 ul"
         <li>

     <a href="/aktuelles/news/index.html.de">               "Level 3 li"
            <span class="nav_description">News</span>
    </a>

</li> 
<li>

     <a href="/aktuelles/veranstaltungen/index.html.de">    "Level 3 li"
        <span class="nav_description">Events</span>
    </a>

    </li>
    </ul>
    </li>
    <li class="active">                                     "Level 2
    <a href="/schauen/bildung/index.html.de">                currently
        <span class="nav_label">Education</span>             opend"
    </a>
    </li>

</ul>
</li>
</ul>

Description of the HTML Code regarding the configuration filetionsdatei (siehe unten):

  • For each ul snippet there is a li snippet.
  • The "ul line" in the li snippet (see configuration file below) initiates the recursion until it reaches the content_maxlevel.
  • Due to content_startlevel and content_maxlevel in the configuration file the navigation recognizes from which category to start and until which category to generate it.
  • Due to category node in the category tree the config file recognizes which level to select for displaying in the HTML Code.
  • The class "active" is applied in case the category is currently opened so that it will be highlighted, see Level 2 "Education".


1. Implementing the configuration file

In the configuration file (e.g. navigation_generator.conf) the navigation is by "nesting" <!--XX-li_content--> and <!--XX-ul_content-->.

In the following file the numbered lines show the steps of the recursion which is responsible for the structure of the navigation.

 Steps
[        ]  <main_nav>
[        ]       file_startlevel = "0"
[        ]       file_maxlevel = "10"
[        ]       content_startlevel = "1"
[        ]       content_maxlevel = "3"
[        ]       fulltree = 1
[        ]
[        ]        li_snippet <<EOF
[        ]         #IF (("<!--XX-current-->" EQ "1") OR ("<!--XX-nodeid-->" EQ "<!--XX-current_nodeid-->")
[  14    ]           <li class="active">
[        ]        #ELSE
[2,5,8,11]     <li>
[        ]        #ENDIF 
[        ]
[        ]            #IF ("<!--XX-level-->" EQ "1")
[   3    ]               <a href="<!--XX-link-->"><!--XX-name--></a>
[        ]            #ELSIF ("<!--XX-level-->" EQ "2")
[  6,15  ]               <a href="<!--XX-link-->"><span class="nav_label"><!--XX-name--></span></a>
[        ]
[        ]            #ELSE 
[  9,12  ]             <a href="<!--XX-link-->"><span class="nav_description"><!--XX-name--></span></a>
[        ]            #ENDIF
[ul line ]               <!--XX-ul_content-->
[        ]           </li>
[        ]       EOF
[        ]        ul_snippet <<EOF
[        ]        #IF ("<!--XX-level-->" EQ "0")
[   1    ]           <ul class="level_1 clearfix">
[        ]        #ELSIF ("<!--XX-level-->" EQ "1")
[  4,13  ]           <ul class="level_2">
[        ]        #ELSE
[  7,10  ]           <ul class="level_3">
[        ]        #ENDIF 
[        ]              <!--XX-li_content-->
[        ]           </ul> 
[        ]       EOF
[        ]    </main_nav>

Description of the recursion:

  1. The recursion starts with the ul snippet in Level 1.
  2. It then jumps to the li content.
  3. The first level is applied for the navigation, i.e. the level 1 is displayed in the HTML Code as a href / link with a name — navigation level "City Topics".
  4. Again, it starts with ul snippet, but in Level 2.
    As it was mentioned before, the "ul line" in the li snippet initiates the recursion until it reaches the content_maxlevel.
  5. It jumps to the li content.
  6. Level 2 is applied so that the second link nav_label is displayed — navigation level "Hot topics".
  7. The new ul snippet starts, but in Level 3.
  8. It jumps to the li content
  9. In Level 3 the link nav_description is displayed — navigation level "News".
  10. to step 12.: The navigation level "Events" has the same level as "News" so that again a link nav_description is displayed.

13.to step 14.: As the navigation is currently opened in level 2 "Education", additionally class="active" applies.


2. Integrating SSI in Codeincludes

The navigation files (SSI) are applied for every page; this is done by using Codeincludes. Thereby, you can also use different kinds of navigation to be applied, e.g. mobile und Desktop versions.

SSI in Codeincludes

Proceed as follows:

  1. Create a new Codeinclude, e.g. navigation.htms.

  2. Enter following code snippet to the Codeinclude, e.g.:

    <!--#include virtual="/ssi/navigation<!--SECTION:DIRECTORY-->/main_nav.<!--SECTION:__CAT_ID-->.<!--XX-lingua-->.ssi" -->

    • DIRECTORY: shows correspodning directory.
    • "main_nav": ist the name of the navigation in the config file.
    • CAT_ID: the category to be started with.
    • XX-lingua: describes the language, e.g. de.

3. Generating SSI (Creating menu)

Then, the navigation is generated. For this case a controller can be set via the GUI of imperia:

  1. Open Menu -> System -> Configure Menus.
  2. Create a new Menu Entry (for more information see chapter Menu Configuration):
    SSI in Codeincludes
  3. Choose the controller /navigation.

  4. Enter the controller's parameters (as for any menu entry by indicating the category ID and the config file), e.g.:

    ?rootNodeId=/28&conf=/config/navigation_generator.conf .

  5. Save your settings.

The navigation can now generated by simply clicking on the menu entry.

Other navigation types#

You can generate other kinds of navigation by using the following configuration files.

As mentioned above, you can have more than one navigation type in a config file (besides the <common> block).

The following codes are wrapped for display purposes.

A bread crumb navigation can be generated using following code:

<breadcrumb>
      file_startlevel = "0"
      file_maxlevel = "10"
      content_startlevel = "1"
      content_maxlevel = "10"
      filename = /ssi/breadcrumb<!--directory-->/<!--nav_element-->.<!--cat_id-->.<!--lingua-->.ssi

      li_snippet <<EOF
          #IF (("<!--XX-current-->" EQ "1") OR ("<!--XX-has_children-->" EQ "1"))
                / <a href="<!--XX-link-->" title="<!--XX-description-->"><!--XX-name--></a>
                <!--XX-ul_content-->
          #ENDIF    
      EOF

      ul_snippet <<EOF
          <!--XX-li_content-->
      EOF

</breadcrumb>

Displayed in the HTML Code:

/ <a href="/index.html.de" title="">City Topics</a>
    / <a href="/aktuelles/index.html.de" title="">Hot Topics</a>
         / <a href="/aktuelles/news/index.html.de" title="News, Traffic, Announcements">News</a>

Here also recursion takes place:

  • ul_snippet refers to li_content.

  • If the li element has a link, title and name, it will be displayed in the HTML Code.

    • The first elements has a link and the name "Hot Topics", but no title (description).
    • The second element has a link and has the name as well the title/description "News".

Anpther code example for a Breadcrumb navigation:

<breadcrumb>
    file_startlevel = "0"
    file_maxlevel = "10"
    content_startlevel = "0"
    content_maxlevel = "10"
    fulltree = "1"

    li_snippet <<EOF

    #IF ("<!--XX-current-->")
        #IF ("<!--XX-level-->" EQ "4")
            #ELSE
                    <li><a href="/<!--XX-project_lang--><!--XX-directory-->" title="<!--XX-description-->" class="active"><!--XX-name--></a></li>
        #ENDIF
    #ELSIF ("<!--XX-current_nodeid-->" REQ "<!--XX-nodeid-->")
            <li><a href="/<!--XX-project_lang--><!--XX-directory-->" title="<!--XX-description-->"><!--XX-name--></a></li>
        #IF ("<!--XX-has_children-->")
            <span class="hasChildren">/</span>
        #ENDIF
    #ENDIF

    <!--XX-ul_content-->

       EOF

       ul_snippet <<EOF
        <!--XX-li_content-->
       EOF
</breadcrumb>

Simple navigation#

Horizontal navigation

A simple, horizontal (⬇) navigation can be generated using following code (from navigation_generator.conf.sample):

<hnav>
    file_startlevel = "0"
    file_maxlevel = "0"
    content_maxlevel = "1"

    li_snippet <<EOF
        <li class="hnav">
            <a href="<!--XX-link-->" title="<!--XX-description-->" target="<!--XX-linktarget-->"><!--XX-name--></a>
            <!--XX-ul_content-->
        </li>
    EOF

    ul_snippet <<EOF
        <ul class="hnav">
           <!--XX-li_content-->
        </ul>
    EOF

    </hnav>

Vertical navigation

A simple, vertical (⬇) navigation can be generated using following code (from navigation_generator.conf.sample):

<vnav>
    file_startlevel = "0"
    file_maxlevel = "10"

    content_maxlevel = "10"

    li_snippet <<EOF
        <li class="vnav">
            <a href="<!--XX-link-->" title="<!--XX-description-->" target="<!--XX-linktarget-->"><!--XX-name--></a>
            <!--XX-ul_content-->
        </li>
    EOF

    ul_snippet <<EOF
        <ul class="vnav">
           <!--XX-li_content-->
        </ul>
    EOF

    </vnav>

Sub navigation 

    <subnav>
    file_startlevel = "0"
    file_maxlevel = "10"
    content_startlevel = "3"
    content_maxlevel = "3"
    fulltree = 0

    li_snippet <<EOF
     #IF (("<!--XX-current-->" EQ "1") OR ("<!--XX-nodeid-->" EQ "<!--XX-current_nodeid-->")
        <li class="active">
     #ELSE
        <li>
     #ENDIF
            <a href="<!--XX-link-->" class="btn btn-lg btn-primary btn-block">
                <span><!--XX-name--></span>
            </a>
            <!--XX-ul_content-->
        </li>
    EOF

    ul_snippet <<EOF
        #IF ("<!--XX-level-->" EQ "2")
        <ul class="subnav_list">
        #ENDIF
           <!--XX-li_content-->
        #IF ("<!--XX-level-->" EQ "2")
        </ul>
        #ENDIF
    EOF

    </subnav>

Horizontal navigation with Drop-Down

<navigationmenu>
    file_startlevel = "0"
    file_maxlevel = "3"
    content_startlevel ="1"
    content_maxlevel = "2"
        fulltree = "1"

    ul_snippet <<EOF
    #IF ("<!--XX-level-->" EQ "0")
            <ul class="nav navbar-nav uppercase topnavigation">
            <!--XX-li_content-->
        </ul>
    #ELSIF ("<!--XX-level-->" EQ "1")
    <a href="#" class="dropdown-toggle customCollapseCaret" data-toggle="dropdown" role="button" >
        <span class="caret"></span>
    </a>
    <ul class="dropdown-menu" role="menu">
        <!--XX-li_content-->
    </ul>
    #ELSIF ("<!--XX-level-->" EQ "2")
    <ul class="dropdown-menu" role="menu">
        <!--XX-li_content-->
    </ul>
    #ENDIF
    EOF


    li_snippet <<EOF
    #IF ("<!--XX-level-->" EQ "1")
    <li class="dropdown"> 
        <a href="/<!--XX-project_lang--><!--XX-directory-->" title="<!--XX-description-->" target="<!--XX-linktarget-->"><!--XX-name--></a>
<!--XX-ul_content-->
    </li>
    #ELSIF ("<!--XX-level-->" EQ "2")
        <li class="dropdown"> 
        <a href="/<!--XX-project_lang--><!--XX-directory-->" title="<!--XX-description-->" target="<!--XX-linktarget-->"><!--XX-name--></a>
        </li>
    #ENDIF
    EOF



    </navigationmenu>

Mobile navigation with Drop-Down

   <mobile_nav>
    file_startlevel = "0"
    file_maxlevel = "10"
    content_startlevel = "1"
    content_maxlevel = "10"
    # include all category entries
    fulltree = 1

    li_snippet <<EOF
    #IF (("<!--XX-level-->" EQ "1") AND ("<!--XX-has_children-->" EQ "1"))
        #IF ("<!--XX-current-->" EQ "1")
        <li class="dropdown open">
        #ELSE
        <li class="dropdown">
        #ENDIF
        <a href="<!--XX-link-->" class="dropdown-toggle" data-toggle="dropdown" title="<!--XX-description-->"><!--XX-name--> <b class="caret"></b></a>
     #ELSE
        #IF ("<!--XX-current-->" EQ "1")
        <li class="active">
        #ELSE
        <li>
        #ENDIF
        <a href="<!--XX-link-->" title="<!--XX-description-->"><!--XX-name--></a>
     #ENDIF
            <!--XX-ul_content-->
        </li>
    EOF

    ul_snippet <<EOF
     #IF ("<!--XX-level-->" EQ "0")
        <ul class="nav nav_mobile">
     #ELSE
        <ul class="dropdown-menu">
     #ENDIF
           <!--XX-li_content-->
        </ul> 
    EOF

    </mobile_nav>

Site Map#

A Site Menu navigation can be generated using following code (from navigation_generator.conf.sample):

Example 1:

<sitemap>
    file_startlevel = "0"
    file_maxlevel = "0"

    content_maxlevel = "1"

    # include all category entries
    fulltree = 1

    li_snippet <<EOF
        <li class="hnav">
            <a href="<!--XX-link-->" title="<!--XX-description-->" target="<!--XX-linktarget-->"><!--XX-name--></a>
            <!--XX-ul_content-->
        </li>
    EOF

    ul_snippet <<EOF
        <ul class="hnav">
           <!--XX-li_content-->
        </ul>
    EOF

    </sitemap>

Example 2 (table):

<sitemap>
    file_startlevel = "0"
    file_maxlevel = "0"

    content_maxlevel = "0"
    content_maxlevel = "10"

    # include all category entries
    fulltree = 1

    li_snippet <<EOF
        <hr />
        <table border="0" style="border:thin solid silver" >
        <tr><td width="200px">name            </td><td width="350px"><!--XX-name--></td></tr>
        <tr><td>description     </td><td><!--XX-description--></td></tr>

        <tr><td>cat-directory   </td><td><!--XX-directory--></td></tr>
        <tr><td>cat-filename    </td><td><!--XX-filename--></td></tr>

        <tr><td>link            </td><td><!--XX-link--></td></tr>
        <tr><td>linktarget      </td><td><!--XX-linktarget--></td></tr>

        <tr><td>current         </td><td><!--XX-current--></td></tr>
        <tr><td>has_children    </td><td><!--XX-has_children--></td></tr>
        <tr><td>active          </td><td><!--XX-active--></td></tr>

        <tr><td>cat_skip        </td><td><!--XX-cat_skip--></td></tr>
        <tr><td>doc_count       </td><td><!--XX-doc_count--></td></tr>

        <tr><td>level           </td><td><!--XX-level--></td></tr>
        <tr><td>levelindex      </td><td><!--XX-levelindex--></td></tr>

        <tr><td>catid           </td><td><!--XX-catid--></td></tr>
        <tr><td>nodeid          </td><td><!--XX-nodeid--></td></tr>
        <tr><td>current_nodeid  </td><td><!--XX-current_nodeid--></td></tr>

        </table>
        <!--XX-ul_content-->
    EOF

    ul_snippet <<EOF
        <!--XX-li_content-->
    EOF
</sitemap>

<fnav>
        file_startlevel = "0"
        file_maxlevel = "0"
        content_startlevel = "1"
        content_maxlevel = "2"
        fulltree = "1"

        li_snippet <<EOF
        #IF NOT ("<!--XX-description-->" REQ "PAGEFOOTER")
                #IF ("<!--XX-level-->" EQ "1")
                <div class="subLinkBox">
                    <h2><!--XX-name--></h2>
                    <!--XX-ul_content-->
                </div>
                #ELSE
                    #IF ("<!--XX-level-->" EQ "2")
                            <!--XX-ul_content-->
                            <li><a href="<!--XX-link-->"><!--XX-name--></a></li>
                    #ELSE
                        <!--XX-ul_content-->
                    #ENDIF
                #ENDIF
        #ENDIF
        EOF

        ul_snippet <<EOF
        #IF NOT ("<!--XX-description-->" REQ "PAGEFOOTER")
                #IF ("<!--XX-level-->" EQ "1")
                    <ul class="subLinkList">
                #ENDIF
                    <!--XX-li_content-->
                #IF ("<!--XX-level-->" EQ "1")
                    </ul>
                #ENDIF
        #ENDIF
        EOF

    </fnav>

escaper-Plug-in CATMETA.pm - under development#

This plug-in is to be used in the navigation_generator.conf to access all relevant meta-data of the categories.

NAME
       Dynamic::Escape::CATMETA

DESCRIPTION
       The Dynamic::Escape::CATMETA module can be used for accessing Category-Metafields when the node_id is given.

SYNTAX
       In templates:

       <!--XX-CATMETA(__imperia_ac_enabled):cat_nodeid-->

       This will return the value of the field __imperia_ac_enabled from the category specified by the node_id <!--XX-cat_nodeid--> of the element
       rendered.

       Data will automatically be HTML-escaped.

       You can specify another escaper by passing it seperated by a comma.

       <!--XX-CATMETA(__imperia_ac_enabled,HTML):cat_nodeid-->

       Would return the Field unescaped.