Building AdminWEB Interfaces

Overview

There are a number of components that make up the AdminWEB system but there is only one required component to build a new interface, the Properties file.

The Properties file is how your interface tells the Navigator about its' existence. You need not use any of the provided tools to build your interface, you can just point the Navigator to your CGI program in the Properties file like so:

	# Simple-Text-Database
	# Format is: :
        Navigator_Description:  Man Page Lookup
        Navigator_Keywords:     manpage help search information info lookup
        Navigator_URL:          /Documentation/Man/Search/View.cgi

There are two other sets of tools at your disposal for building interfaces but their use is at your option.

The Interface Builder generates complex HTML forms based on a simple description language (although it restricts the format of your interface somewhat); most of the BSDI provided interfaces are built using the Interface Builder. There are also a number of functions for building backends, including HTML generators, HTML and URL encoding, URL manipulation, system interface routines, etc.

You can use the Interface Builder and write your own backend from scratch or you can write your own interface and use some of the backend support functions, whatever is most approriate for your situation.

There is also a set of template files for getting started in the templates/ source directory.

Navigator

Interfacing with the Navigator

Your interface exchanges information with the Navigator via the Properties file in its directory. To be listed in the main menu an interface must have a Properties file with at least the following elements:

        # Simple-Text-Database
        # Format is: :
        Navigator_Description:  Man Page Lookup
        Navigator_Keywords:     manpage help search information info lookup
        Navigator_URL:          /Documentation/Man/Search/View.cgi

Interfaces may also specify an icon to be displayed under their description with Navigator_Icon. Interfaces using the Interface Builder should also list the available Views in View_List and the default view in Navigator_View. And finally, an interface can request to not be listed in the standard menu by including Navigator_Hidden: true in it's Properties file.

The Navigator simply searches the directory tree looking for Properties files and builds the interface from them, linking the Navigator_Description to the Interface Builder for that directory or the URL specified in Navigator_URL.

Properties

Properties files contain per interface configuration information and also provide the ability to maintain persistent state in your interface (if required, e.g., the Add Account interface must keep track of the next available user ID). To prevent conflicts between the various parts of the system that use the Properties file you should follow the following naming conventions.

Default_*

Available for interface defaults.

Backend_*

Available for use by the interface backend. (e.g., Backend_Program might be used to specify the name of a backend program instead of hardcoding it in your program).

View_*

Reserved by the Interface Builder.

• View_List: list of valid views
• View_Submit: Form submission tag name (defaults to Action)

Navigator_*

Reserved by the Navigator.

• Navigator_Description: interface description
• Navigator_Keywords: search keywords
• Navigator_View: the default view file
• Navigator_Icon: icon to include in interface description
• Navigator_URL: specify location for HREF
• Navigator_Hidden: if true, the interface will not be listed in the main menu

Property_Editor_*

Reserved for use by the Propert Editor (not available at this time)

• Property_Editor_List: space separated list of properties that should be editable by the user (e.g., all of Default_* are usually included).

This_*

Available for use by your interface for any purpose.

You should not use prefixs that are not listed above as they might conflict with future extensions to the system.

Interface Builder

The Interface Builder builds an HTML <FORM> from a simple record-based specification and helps manage the resulting submission. It also allows you to embeed your Help text right in your interface specification where it is most approriate.

Using the Interface Builder is not required but there are a number of advantages in doing so, including inheriting the standard look-and-feel for MaxIM interfaces. However, some small amount of perl5 programming is required to build interfaces using the Interface Builder so it isn't for everyone.

See View.pod for more information (XXX).

Support Functions

Perl5 Modules

The following perl5 modules are available. These modules implement interfaces that are not specific to the AdminWEB interface but were written to support it. No online documentation is available for these modules, run ``perldoc Module::Name'' (where Module::Name is the name of a module listed below) for more information.

• HTML::Markup::HTML2
• DataType::NamedTree
• DataType::Linkable
• DB::Properties
• File::Lock
• FileFormat::Calendar

Backends

The Backend Interface

The AdminWEB::StandardBackend module is for running simple programs on the backend that don't have any fancy processing needs. See SysAdmin/System/Date/* for an example.

CGI form parameters are passed in via ARGV's as `keyword=value' pairs. All CGI Environment variables are preserved.

The AdminWEB::StandardBackend module recognizes these return values from the backend program:

• 0: OK -- stdout/stderr contains status message for user
• 1: ERROR -- stdout/stderr contains error message for user
• 2: WARNING -- stdout/stderr contains an informational message that requires confirmation from the user before completing the action. When confirmed by the user the CGI parameter ``Action'' is set to ``Confirmed''.
• 3: raw-CGI -- stdout/stderr is taken as the raw CGI return data. This allows backends to issue CGI redirects and return whole HTML documents if needed for specialized return interfaces.

  If your backend is really a CGI program then you are far better off simply interfacing it with the system instead of using the AdminWEB::StandardBackend module.