ALPFrame menu definition compiler
=================================

This is a simple compiler written in ASP (JScript) that allows you
to use easy-to write definitions of menus and include them in your page(s)

Usage in pages
~~~~~~~~~~~~~~

Compiler is implemented in the menucompiler.asp file. In the pages where the
menu will be used you should use the compiler as follows:

<SCRIPT SRC="menucompiler.asp?menufile=x&menuname=y&frame=n&createvariables=c"
        Language=Javascript>
        
Compiler generates text file containing the Javascript that creates the menu
and assigns it (and some of the parts of the menu - optional) to variables.

Parameters:
    menufile (required)
        virtual path to the menu file to be compiled. Can be relative path too.
        In the SCRIPT tag above x should be replaced with the file path.
        Example 1: menufile=mymenudefinition.txt
        Example 2: menufile=/menus/mymenudefinition1.txt
    menuname (required)
        Name foir the menu. A variable will be automatically defined and 
        assigned to the menu - parameter value will be used as variable name.
        Example: menuname=MyMenu
        Thus in the page you are able to use this variable to access the menu
        for example to set the window main menu:
        external.MainMenu = MyMenu;
    frame (optional)
        Only one frame for all the items in the menu is supported by the compiler.
        This is the browser frame where the handler functions will be executed.
        See the menu definition file syntax for details.
        If missing top most frame is used or if the page has no frames - the page.
        Example: frame=main
    createvariables (optional)
        If set to 1 Javascript variables will be created for the Items with names
        specified (see the menu definition file syntax for details). This is useful
        if you want to access some of the menu items or branches. For example if 
        you want to check/uncheck or enable/disable some items you should enable
        this option and then acces those items through the defined variables.
        Example: createvariables=1

Before using the menu you should test if it compiles ok. Open the compiler as a page
with the parameters you are going to use in your page in the browser. Fore example:

alp://C:/somedir/menucompiler.asp?menufile=x&menuname=y&frame=n&createvariables=c

Set the parameters to appropriate values.

Text file will be generated. It contains the resulting script. Look at the last line
for errors. If error is occured you will see something like:

*** Error on line 26: Illegal in a radio group.
        POPUP, Err popup
// ERRORS - compilation failed.
    
If the compilation is successful output will end with:

// SUCCESS - compilation ok.

Menu definition file syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every command in the file must be placed on a separate line. Commands consist of
KEYWORD and parameters. General syntax is:

KEYWORD, param1, param2,...[,optionalname]

Number of parameters depends on the KEYWORD. Parameter in [] brackets is optional

Commands (keywords):
^^^^^^^^^^^^^^^^^^^^
    POPUP, Caption [, name]
        Begins a menu popup/branch.
        Parameters:
            Caption - caption of the pop up menu.
            name    - internal name of the pop up menu
        Short form: 
            P, Caption [, name]
                   
    POPUP END
        Ends the current pop up
        Short form: 
            PE
        
    ITEM, Caption, Handler, Info [, name]
        Defines a menu item in the current pop up or radio group
        Parameters:
            Caption - caption of the menu item.
            Handler - name of the handler function.
                      Without () brackets. Frame parameter of the compiler
                      defines which browser frame contains the function
            Info    - Custom information string of your choice.
                      To leave it empty leave one space after the comma.
            name    - internal name of the menu item
        Short form:
            I, Caption, Handler, Info [, name]
            
    ACCELERATED ITEM, Accel, Caption, Handler, Info [, name]
        Defines a menu item with associated accelerator key combination
        in the current pop up or radio group
        Parameters:
            Accel   - Accelerator key for the menu item
                Syntax: modifier1[-modifier2[-modifier3]]-Key
                modifier - is one of these keywords:
                    Ctrl    - Control key
                    Alt     - Alt key
                    Shift   - Shift key
                Key      - is a character or special keyword for non character
                           keyboard keys
                Examples:   Ctrl-Shift-A
                            Ctrl-Alt-X
                            Ctrl-Shift-F2
                            F3
            Caption - caption of the menu item.
            Handler - name of the handler function.
                      Without () brackets. Frame parameter of the compiler
                      defines which browser frame contains the function
            Info    - Custom information string of your choice.
                      To leave it empty leave one space after the comma.
            name    - internal name of the menu item
        Short form:
            A, Accel, Caption, Handler, Info [, name]            
            
    SEPARATOR
        Defines a menu separator.
        Shor form:
            S
            
    RADIOGROUP [, name]
        Begins a radio group.
        Parameters:
            name    - internal name of the radio group
        Short form:
            R
        Remarks: Radio groups can not be nested and pop up menus can not be defined
        inside a radio group.
            
    RADIOGROUP END
        Ends the radio group
        Short form:
            RE
            
    ' first non blanc characer means comment line
            
Remarks:
^^^^^^^^

    By using the optional "name" parmeters in combination with the compiler parameter
    createvariables=1 variables will be defined for all the items, popups, groups wich
    have this parameter specified. "name" specified will be used as variable name. 
    Thus "name" parameters must be unique.
    
    Pay attention to frame parameter of the compiler. It defines which browser frame
    contains the handlers specified for the menu items (2-d parameter of ITEM). You must
    define corresponsding functions in the page that opens in the pointed frame.
    Functions look like:
    function myHandler(sender) { ...
    Name of the function corresponds to the handler parameter of the items you want to handle 
    with it.
    Parameter of the function (sender) is the menu item clicked. By uding the Info parameter
    of the ITEM command you can specify information that allows you to recognize different
    items or their purpose. For example Info can contain URL and your handler function navigates
    to that URL. For example:
    function OnMenu(sender) {
        window.location = sender.Info;
    }
    
    If you do not expect changes in your menu you can choose to copy the compiler output,
    paste it in a javascript file and include that file in the SCRIPT's SRC attribute instead
    of refering the compiler. This will run faster but will not allow fast changes in the menu
    definition.
        
        
Sample menu definition:
~~~~~~~~~~~~~~~~~~~~~~~

POPUP, File
    ITEM, Open, OnMenu, Something
    ITEM, Save, OnMenu, MyInfo
POPUP END
POPUP, Edit, EditMenu
    ITEM, Copy, OnMenu, Something
    SEPARATOR
    ITEM, Paste, OnMenu, blah blah, PasteItemName
    SEPARATOR
    RADIOGROUP
        ITEM, Radio1, OnMenu, info
        ITEM, Radio2, OnMenu, info
        ITEM, Radio3, OnMenu, info
    RADIOGROUP END
    SEPARATOR
    POPUP, A &popup
        ITEM, Some item, OnMenu, info
        ITEM, Some item2, OnMenu, info
        SEPARATOR
        ITEM, Some item3, OnMenu, info
    POPUP END
    SEPARATOR
    RADIOGROUP
        ITEM, Radio1, OnMenu, info
        ITEM, Radio2, OnMenu, info
        ITEM, Radio3, OnMenu, info
    RADIOGROUP END
POPUP END        


