home / documentation / setup / Using HierMenus with a Database

Using HierMenus with a Database

You can setup HierMenus to work in conjunction with a database. In order to do so, you must provide your own server side tool that translates the information you have stored in your DB into HierMenus' own configuration file format. You can then provide your dynamically generated configuration file to the page via whatever delivery method you prefer. As far as HierMenus is concerned, the only changes you need to make are in regards to HM's own loading of its execution scripts and configuration file. A basic understanding of the HierMenus loading process should help you to understand this point.

When we load HierMenus into a page, two main files are loaded: the menu execution scripts (represented in the HierMenus script directory as HM_ScriptDOM.js, HM_ScriptOPR.js, etc) and a configuration file that contains the menu definitions for the page. The Menu definition file is the one that would be of interest to you. Most often this file is defined as a static file by the site developer and remains in a fixed location on the server to be retrieved along with the Web page request from the site visitor. However, in some situations developers have opted to provide the configuration file dynamically using a server-side tool when specific pages are requested. This requires a small amount of editing to the HierMenus loading mechanism from you but is quite doable.

In other words, HierMenus builds all of the menus it needs for a page from the information within this menu configuration file; information that can simply exist in a single static location (file) or can be generated automatically within a specified page via some type of server control that you provide. While we definitely encourage them, we do not directly support such dynamic server-side HM deployments; i.e., we provide the menu configuration file documentation itself (see step 2 of the setup instructions, as well as the parameter reference) and leave it to individual developers (i.e., you) to create the menu definitions in a way that HM can utilize them in the same manner as it would the static files.

There are two main methods you can employ to get HierMenus to recognize your generated configuration file.

1. Call it directly from HM_Loader.js
   This is the simplest of the options, but does require that your server side tool--the one that will generate the HierMenus configuration file from your DB information--must be independently executable; i.e., you must be able to access it directly via URL. Additionally, the tool must be able to directly provide the file's appropriate mime-type in the information that it sends to the browser. For JavaScript files, you can use a mime-type of application/x-javascript (more technically correct) or text/javascript. Either should work fine.

   To instruct HierMenus to "call" your dynamically generated file, simply include the appropriate URL in the HM_ConfigDir and/or HM_ConfigFiles parameters. HierMenus will then instruct the browser to retrieve your file in the same manner that it would retrieve a static configuration file from the server.

2. Include it within the page
   This is the least desirable option, as it will require that all browsers download your configuration file, even if they won't actually be using HierMenus at all (such as older browsers, or browsers with JavaScript specifically disabled). But it may be the only option if you are unable to create a more directly accessible tool as in the first option above.

   When including the configuration file within the page, you must first instruct HierMenus to not retrieve a configuration file of its own, which you can do by setting HM_ConfigFiles and HM_ConfigDir to the empty string.

   Once you've cleared HierMenus' own configuration file load, you can then include your own generated content into your HTML page. As the information you generate relies on the execution scripts (also loaded from HM_Loader.js) you must include your server side command to generate your configuration file after the command to call HM_Loader.js.

   The configuration "file" you dynamically generate via your own server side tool must exactly match the configuration file format as specified in step 2 of our setup instructions. Additionally, since you are generating the file outside of HierMenus, you must be sure to enclose your results within valid HTML script tags. For example, your HTML page might look something like this:

   <script type="text/javascript"
           language="JavaScript1.2"
           src="/hm/scripts/HM_Loader.js">
   </script>
   <script type="text/javascript" language="JavaScript1.2">
   <?php 
      // insert php code to generate menu configuration file here
   ?>
   </script>

The deprecated language="JavaScript1.2" attribute is optional here, but we recommend it for best support of the oldest browsers.

For more information:

HM_ConfigFiles
HM_ConfigDir
Setup Instructions, Step 2