ALPFrame uses one or more configuration files - alpframe.cfg. When started ALPFrame does the following:

• Loads the main configuration file (must be present) from the same directory where the ALPFrame.exe is.
• Checks if an alpframe.cfg file exists in the current working directory where ALPFrame is started (work directory can be specified in shell shortcuts or in ALPInstall or is assumed if the applications is started from the command prompt). If the file exists it is loaded and merged with the main configuration file - e.g. settings in the second file will replace the settings in the first file where the both files specify the same setting. If the file in the current directory lists some COM objects to be loaded they will be loaded too.
• If an ALP URL is passed or a physical or relative path - the directory corresponding to the URL is searched for alpframe.cfg file and it is loaded and merged with the previous files (the settings in it take precedence the same way).

This allows single copy of ALPFrame.exe to start with completely different settings depending on what URL is opened or where it has been started (working directory). You can use the ALP Settings shell extensions to edit the ALPFrame configuration in a specific directory and then create shortcut that points a file in that directory. The ALPFrame instance started this way will use that configuration.

Wherever the option in an alpframe.cfg file points a file (DLL lists in LIBRARIES and UILIBRARIES, Icon options) the paths specified are assumed relative to the alpframe.cfg file in which they are found. This allows the developer to start the ALPFrame with custom icon or even with custom additional set of COM libraries not registered with the OS.

Usually only the main alpframe.cfg file (in the same directory where the alpframe.exe is) contains LIBRARY and UILIBRARY sections. However it is allowed to use such sections in the other files and thus start different copies of ALPFrame with different components available for the ALP applications running in them without need to register these components with the system. If you do not have this in mind please make sure you remove these sections from the secondary files because they will cause errors if the listed DLLs are not in the specified relative directories.

Below all the configuration settings that are currently supported by ALPFrame are listed. To learn how and when to use them in different scenarios see the deployment related chapters in this help file.

The configuration file supplies settings of these types: Global settings, display/behavior settings, ActiveX list. and Browsing restrictions.

Global settings:

These settings are specified outside any other section.

• (string)APPID - optional name of the configuration. This is also referred as Configuration ID or Application ID. It allows the ALP Applications to be configured to require ALPFrame instance started with this configuration in order to run. See ALP Application  and ALP Application in ALP Settings shell extensions

• (string)ALPENGINE=iewebsrv.dll - see in the ActiveX list below

Display settings

Contain two sections:

• SETTINGS - General options:
  • (int)ContextMenuAllowed - possible values 0,1. 0 - disables the standard IE context menu, 1 - enables it. If you want to use context menus controlled by your pages - set it to 0.
  • (int)NewWindowsDenied - possible values 0,1. 0 - denies new windows (window.open, links with target attribute and so on), 1 - allows windows to be opened. In most cases 1 should be the better settings, but some applications may need to deny creation of new windows.
  • (int)DoNotExitWhenLastWindowClosed - possible values 0,1. Strongly recommended to set it to 0. This is emergency exit option that is often useful. There is no guarantee that all the hosted controls and scripts from different vendors are written properly thus unloading everything after closing the last window guarantees that the program will exit. In the other case wrong reference counting may cause the program to remain in memory.
  • (int)ShowStatusBarOnNavigate - possible values 0,1. 0 - disables the option, 1 - forces the status bar to show when the browser navigates no matter if the style is specified.
  •  
• WINDOWS - Settings for the the ALPFrame windows. ALPFrame recognizes two type of windows - initial and windows created later by the application. Although the DHTML pages have access to methods and properties giving them ability to manipulate all the settings listed here - this section allows you to set some of these options here. This feature can be useful for applications not aware of the ALPFrame features - therefore instead of writing initial page that applies some settings - you can set them here.
  Settings in the WINDOWS section are applied to all the windows opened after the initial window, settings from the FIRST section are applied to the initial window only (the window that opens with the application start). See also Window styles.
  • (int)width - Width of the window in screen pixels
  • (int)height - Height of the window in screen pixels
  • (int)centered - [0,1] Center the window on the screen
  • (int)Caption - [0,1] WS_CAPTION flag - window with caption.
  • (int)DlgFrame - [0,1] WS_DLGFRAME flag - window that has a border of a style typically used with dialog boxes.
  • (int)Minimized - [0,1] Start minimized.
  • (int)Maximized - [0,1] Start maximized.
  • (int)MaximizeBox - window that has a minimize button.The SysMenu style must also be specified
  • (int)MinimizeBox -  window that has a maximize button.The SysMenu style must also be specified
  • (int)Overlapped - overlapped window with a title bar and a border
  • (int)Sizeable - window with a sizing border (WS_THICKFRAME flag)
  • (int)SysMenu - window with a window menu on its title bar. The WS_CAPTION style must also be specified. Allows WS_MAXIMIZEBOX and WS_MINIMIZEBOX styles
  • (int)Border - window with a thin-line border  Sizeable overrides this setting.
  • (int)AppWindow - window will be shown onto the taskbar when visible
  • (int)ClientEdge - window with a sunken edge
  • (int)DlgModalFrame - window with a double border. not resizing.
  • (int)PalletteWindow - top most window with thin caption
  • (int)StaticEdge - window with a three-dimensional border
  • (int)ToolWindow - window with a thin caption. Does not appear in the taskbar or in the Alt-Tab palette. (requires Caption to take effect)
  • (int)TopMost - top most window, floats on top of the all other desktop windows
  • (int)WindowEdge - window with a raised edge border
  • (string)Icon - [version 1.1.0.5] Relative path to the custom icon file from which the normal (large) icon will be loaded . Path is relative to the alpframe.cfg file where it is specified.
  • (string)IconSmall - [version 1.1.0.5] Relative path to the custom icon file from which the small icon will be loaded . Path is relative to the alpframe.cfg file where it is specified. The small icons are used to show the ALPFrame windows (if they are configured to have system menu). The large icon is shown when the user switches between the applications using Alt-Tab. Usually the both icons are in the same file. It is most important to supply small icon because the large icon is shown only occasionally. However the applications typically use the same icons for their shortcuts in the start menu and the desktop - therefore to determine if the large icon deserves design efforts see if the user will be able to see it (for example if you are installing shortcuts on the desktop - see ALPInstall). 
  • Subsection FIRST - Contains the same settings as above and additionally one more setting. It applies to the initial window which is opened when the ALPFrame starts.
    • (string)HomePage - String that points the home directory/page. If the directory is pointed - then the default document in it is used as home page. Path entered here should be relative to the current directory. Samples:
      . - current directory
      pages/start.asp - page start.asp in subdirectory pages
      samples - samples subdirectory or default document in it if exist (usually default.asp or default.htm).

ActiveX lists

May contain one or two sections and one global entry. These settings are extremely important for the developers who want to create auto run applications and any other ALP application packages intended to run without installation. Here all the required libraries and COM objects from them must be listed. If you are going to build installable packages you do not need to change this section in the alpframe.cfg of the redistribution package. See at the end of the page a short explanation of the meaning of these settings.

(string)ALPENGINE=iewebsrv.dll

Global entry. Relative path to the ALP engine core file relative to the ALPFrame.exe. The above setting is default and represents the situation when the both files are in the same directory. This setting should appear only in the default alpframe.cfg which is in the same directory where the ALPFrame.exe resides. 

LIBRARIES and UILIBRARIES - sections contains one subsection per every ActiveX DLL registered with ALPFrame.

Subsections have the following format:

{ path/name.dll:
  (string)Class={ - CLASSID - }
  ...
  (string)Class={ - CLASSID - }
} path/name.dll; 

Where:

• path/name.dll is the path to the ActiveX DLL relative to the alpframe.cfg file. Fore example: Libraries/SomeActiveX.DLL
• Class record - one class record must be placed for every COM class that is used in the ALP applications. CLASSID is the COM class identifier (a GUID) of the COM class. Typically one DLL contains several classes thus enter here an entry per class - classes that are not used in the application can be omitted.

LIBRARIES section defines the libraries available for the ASP side of the applications. To use certain DLL in the DHTML part of the application you will need to include it in the UILIBRARIES section - e.g. a DLL used in the both sides may occur twice in the file - in the LIBRARIES and UILIBRARIES sections.

Note that listing the DLL and its classes here will not automatically enable the object creation by ProgID in autorun scenario. You will need also to create ClassID to ProgID mapping in the alp.application - see the ALP Settings shell extensions to see how to do this.

It is not recommended to include any LIBRARIES or UILIBRARIES sections in the application specific configuration files (This concerns the installed applications) which are loaded from the ALPFrame work directory or the directory that corresponds to the initial URL. When installed ALP installs all of its components and such registration is not needed. If you want to use another COM DLL it is recommended to include it in the installation configuration instead of using this feature. However, it can be reasonable to use the feature in some rare scenarios - but check first the requirements for dynamically used COM DLL and see if your DLL meets them.

See the Deployment page for more details about the requirements and limitations for the ActiveX components registered here.

Browsing restrictions

This is an optional section that allows you restrict the ALPFrame browser to certain protocols and sites so that the user would not be tempted to go to potentially dangerous locations. Note that the ALP Settings shell extension provides convenient way to edit these settings. 

• BROWSING - contains one global setting and two sections.
  • (int)DefaultPolicy - specifies the default policy which applies to all the URL and protocols not listed in a particular profile.
  • PROFILES section - contains one section for each profile (zone) you want to define. The section may contain one or more entries:
    • (string)<protocol_name>=<URL_base>
      where the:
      <protocol_name> - is http, ftp, alp and so on. It specifies the protocol for the URL-s referred by this profile
      <URL_base> - If set to * means all the URL over the specified protocol, if non-empty specifies the basic portion of the URL required in order to detect the URL as part of this profile. For example www.site.com 
  • POLICIES section - contains one entry for each profile:
    • (int)<profile_name>=<policy>
      where the:
      <profile_name> - is the section name of a profile specified in the PROFILES section
      <policy> is a number (see below) 

The polices:

0: Allowed - allow browsing
1: Ask first time - The user is asked if he/she really wants to navigate the first time an URL from that profile is used.
2: Ask always - Like before but the user is asked each time an URL from the profile is used. This includes images as well, therefore you should use this option in some rare cases only.
3: Forbidden (message) - the browsing is forbidden. A message informs the user about this.
4: Forbidden (silent) - the browsing is forbidden without message.

Notes about the dynamic COM DLL usage

If you do not have COM experience you can be puzzled why this is needed at all. The reason is that COM objects are created by the system and it needs to know where they are (in which DLL is the implementation) and what is their alias (ProgID). This information is extracted from the registry where it is written when the COM DLL is installed or manually registered by using the regsvr32 utility. A COM object can be created by its ProgID or ClassID. From the two ID values the ClassID is the most important one. It is a GUID (unique number) assigned to the COM class by the developer (or automatically - VB generates the GUIDs automatically) - example ClassID: {755ED87C-811F-11d5-A92B-E47BCB000000}. The ProgIDs (example: Scripting.FileSystemObject) are human readable aliases for the ClassID-s. Therefore it is quite possible that a single object is registered under several different names for example. And while IIS allows the ASP programmers to create COM objects only using their ProgID-s ALP allows this to be done by using ClassID as well.

When the application has to run as pure autorun - in other words without any component installation, evidently the system will have no information on how to create the COM objects used in the ASP pages. Here comes the ALPFrame ability to provide this feature for the ALP engine (and the ASP pages) running in it. But this is possible by default only through ClassID (ProgIDs cannot be used unless you create COM mapping). So the LIBRARIES section acts as local version of the registry which points where the COM classes are implemented. As you can see above, each section is named after the DLL described by it and lists the ClassID-s of the COM classes implemented in that DLL.

To avoid using the "ugly looking" ClassID values you can use the ALP engine COM aliasing feature introduced in the ALP 1.1. It allows you to assign your own custom ProgIDs for some COM objects and then use these aliases in the Server.CreateObject calls or in the <OBJECT RUNAT=SERVER> tags. They are saved in the ScriptGen's module settings in the alp.application file.

Will all the components work this way? The answer is unfortunately no. The components supplied with ALP are designed to conform the ALPFrame requirements, but most of the other components available from other vendors are not able to function correctly under these circumstances. This is caused by one other value written into the system registry during the installation of a certain DLL - the location of its type library. The type library is typically used to implement the standard which allows the COM class to interact with scripts - automation interface (IDispatch). Most development tools including VB, VC, Delphi etc. generate DLL-s that will check the registry to see where their type library is. Usually it is in the same DLL file (as a resource data) and even if it sounds to you a bit strange - the type info will not be loaded if there is no value in the registry pointing to the own DLL where the component is implemented. Therefore the ALPFrame requirement is that the component is able to load its type library not checking the registry. Such components can be built in VC++/ATL using the typeinfoex class (see the code snippets on our site), but we cannot guarantee that any other tool will produce components capable of working in pure autorun scenario.

The above facts concern much more projects - not just ALP. For example dynamic installation of components from the Internet. The worst is that such an installation will most likely require administrative rights. On the other hand the ALPFrame technique works with any user rights (even for quests) but it allows the component to be used without installation only in the ASP scripts running in this instance of the ALPFrame. I.e. the ALPFrame supplies a virtual environment with additional components available at run-time.

This is one of reasons to avoid support for Java  or .NET in ALP as integral part. These technologies are oriented to corporate environments and can't work if their virtual machines are not installed on the PC. Compare it with ALP - you may have independent ALP instances - an installed ALP, one or more ALP engines started from CD (completely separate set of binaries) and all they may have different set of base components configured. Contrary - with Java and .NET you have only one virtual machine - the installed one. It depends on registry settings, environment variables etc. - completely inappropriate for pure autorun scenarios. Of course we will try to fight this situation and do whatever is possible to bring additional WEB technologies to ALP but in any case they will be supplied as separate modules available for those who want to use them, knowing that additional limitations will apply.