WARNING: The information on this documentation will change as the development on this version of DHTML Menu Builder progresses.
It is VERY important that you always refer to the information provided in this document prior to testing new versions of the DynAPI code.

This tutorial will guide you through the most basic steps in creating your first dynamic menu using DHTML Menu Builder <developers' edition> and the DynAPI.

There are two main scenarios in the process of creating dynamic menus:

• All your menus will be dynamic
• You will have static menus created with DHTML Menu Builder and you will then add some more menus using the DynAPI

Although this tutorial will not address any of these scenarios exclusively, the process is exactly the same for both and can be summarized by these steps:

• Implement a menus project into your the HTML documents of your web site using the standard instructions provided in DHTML Menu Builder's documentation (Click Help->Tutorials->Using Toolbars)
• Enable the DynAPI on your project
• Re-compile the project
• Add DynAPI code to your HTML documents

Each one of these steps will be covered in this tutorial.

If you have already implemented a static menu into your web site you can skip this section.

The first thing you must know is that before you can use the DynAPI you need to have a working and fully implemented project running on your web site.
So, if you have not yet created a project, please follow these steps:

• Start DHTML Menu Builder
• Click File->New->Empty Project
• Click the "Configurations" tab
• Fill-in the three paths
• Click OK
• Click Tools->Compile
• Click Tools->Install Menus
• Install the project into all the HTML documents on your web site

This is the basic procedure to get a project implemented on your web site; of course, more detailed instructions can be found on DHTML Menu Builder's documentation:

• Start DHTML Menu Builder
• Click Help->Tutorials->Using Toolbars

Note that it is not the intention of this tutorial to cover the implementation of a menu project. This is very well covered in DHTML Menu Builder's main documentation. So follow the previous steps in case that you need to get a project implemented in your web site.

DHTML Menu Builder <developers' edition> is exactly the same product as the Standard Edition with the only exception that can embed the DynAPI into the javascript files it generates. As you can imagine, we need this DynAPI in order to be able to use it, so here's how to prepare a project so that when compiled, the DynAPI is included in the generated javascript files:

• Start DHTML Menu Builder and open your .dmb menus' project
• Click Tools->DynAPI
  You will see that several new items are added to your project. This is perfectly fine. For now, you can ignore those new items.
• Click Tools->Compile to update the javascript code for your menus.
  If you receive an error about the DynAPI not being compatible with the "max" Code Optimization setting you will need to lower this setting to the "normal" position:
  • Click File->Project Properties->Advanced
  • Change the Code Optimization setting to "normal"
  • Click OK
  • Click Tools->Compile again

The final step of the process is to add DynAPI code to your HTML documents. This code will contain calls to the DynAPI set of functions that will allow you to add new items to your menus.
The DynAPI not only contains functions to add new items, but contains functions to perform many different operations (such as modifying existing items, removing items, etc...) but in this tutorial we will concentrate on the most common use of the DynAPI which is the addition of new items.

To add new items the DynAPI provides two set of functions:

• Low level functions
• High level (array-based) function

The low level functions provide much more control over the way new items are added but they are also considerably harder to use and understand so, for this tutorial, we will use the high level function dmbAPI_parseArray.
You will notice that throughout this section of the tutorial, DynAPI functions will be hyperlinks and clicking on them will take you to the documentation for that specific function.

DynAPI code is nothing more than a set of javascript instructions so the first thing you need to do is:

• Using your preferred HTML authoring tool, open one of the documents in your web site were you want to display dynamically generated menus.
• Switch to Code View so that you can see the HTML code for the page.
• Locate the closing body tag (which looks like this </body>)
• Now, right before this closing tag, add the following code:

Now that we have our basic DynAPI code block we can begin to perform calls to the dmbAPI_parseArray function to add new menu items.

The dmbAPI_parseArray function is extremely easy to use and the only thing that you need to master is the way menu items are identified. Nothing better than to create a sample and then we'll analyze the code line-by-line.

Let's suppose that we want to create this menu structure:

• Home
• Products
  • DHTML Menu Builder
    • Standard Edition
    • Developers' Edition
    • LITE
  • KeyLaunch
  • SoftLeds
• Contact Us

Although this menu looks simple it will allow you to fully understand how the dmbAPI_parseArray function works.

Here's the first portion of the code, which will create the main menu items, that is, the items that will appear on the toolbar:

As you may have noticed, a call to the dmbAPI_parseArray function involves passing a series of parameters:

• The first parameter indicates the menu item's ID
  The ID is nothing more than an identifier for that particular menu item and the DynAPI requires that each item have its own unique ID
  
• The second parameter is the parent's menu item ID
  In this case, since all menu items will be top-level items (that is, items that appear inside a toolbar), their parent ID will be 0. This simply indicates that these items are not sub-items of some other menu item.
  
• The third parameter, as you may have already guessed is the item's caption (or text).
  
• And, finally, the fourth parameter is an optional parameter but, when specified, it indicates the menu item's link.

Let's now add the remaining menu items:

Don't worry if, all of a sudden, everything looks too complicated -- it is not. Let's analyze each new line:

In this line of code you can see that the item ID is "21" and the parent ID is "2".
The items IDs can be anything you like (as long as they are unique) so you can be creative with them so that they not only server as unique identifiers but they also help you recognize the menu items' hierarchy in the menus' structure.

Setting the ID to "21" allows us to easily identify that this is a subitem: a subitem of the item "2" and this is the first subitem in the list "1" thus "2" and "1" gives us "21".
The second parameter is easier to understand and we are simply saying that the "DHTML Menu Builder" item should be a subitem of "Products" simply because the "Products" item's ID is "2".

The next item:

Again, here we can identify that this is a third-level sub item (its ID has three digits) and it's obviously the first subitem. The first two digits of the ID ididicate to which item it belongs "21", the last one its place in the hierarchy.

If all this numbering technique confuses you, here's an alternate version of the code:

In this version, instead of using numbers we are using text for both the menu items' ID and, consequently, to identify their parents.
If you are completely new to the DynAPI this approach may look easier to understand but you should give the other approach a try -- although this method is completely valid you can imagine that with a rather large project you will end having extremely long lines of code which will become hard to maintain and will consume unnecessary extra bandwidth when your web site is visited.

I hope this introduction to the DynAPI has been helpful and, as always, don't hesitate to contact me if you have to have a question or encounter any problems.