Esmith::FormMagick

	Skill level: Developer
	Risk of inconsistencies with Koozali SME Server methodology, upgrades & functionality is high. One must be knowledgeable about how changes impact their Koozali SME Server. Significant risk of irreversible harm.

NAME

      esmith::FormMagick - esmith wrapper for CGI::FormMagick

In a root terminal you can do the command below if you want to display the up-to-date content

perldoc esmith::FormMagick

SYNOPSIS

        use esmith::FormMagick;

        my $f = new esmith::FormMagick();
        $f->display();

        my $f = new esmith::FormMagick( filename=>’/some/path/to/script’ );
        $f->display();

DESCRIPTION

esmith::FormMagick is a wrapper for CGI::FormMagick which automatically does all the things that we always want to do for the SMEServer manager. These include:

• Turning off unwanted buttons (previous, reset)

• Automatically clearing %ENV for taint-friendliness

• Disabling uploads through CGI.pm and setting the MAX_POST size to 100KB.

• Reading in FormMagick XML from the __DATA__ section of the script

This last point is the most important one. In order to avoid having XML files littering the filesystem, we have chosen to include them along with the script which parses them. Your script will therefore look like this:

          my $fm = esmith::FormMagick->new();
          $fm->display();

          # miscellaneous subroutines, etc

          __DATA__
          <form ...>
              <page ...>
                  <field ...> ... </field>
                  <field ...> ... </field>
                  <field ...> ... </field>
              </page>
              <page ...>
                  <field ...> ... </field>
                  <field ...> ... </field>
                  <field ...> ... </field>
              </page>
          </form>

esmith::FormMagick also provides certain convenience functions to assist in writing FormMagick web panels.

METHODS

new()

Creates a new esmith::FormMagick object. Takes an optional hash of arguments, including:

more_lexicons       a list of additional lexicon files to use
charset             the character set encoding of the lexicon files (default is UTF-8).

Notes on lexicon files:

By default, lexicons are read in from /etc/e-smith/locale/*/FormMagick (general FormMagick-internal phrases) and /etc/e-smith/locale/*/$scriptpath (where $scriptpath is something like etc/e-smith/web/functions/useraccounts. NB: any symlinks will be traced to their source). You can append items to this list using the more_lexicons argument. Later lexfiles override earlier ones.

For debugging purposes, $fm->{lexfiles} will tell you which files were read in, and $fm->{original_xml} will show you the XML that was generated by smushing those files together. The script will also be parsed to look for the following special coments, which are used to generate the navigation bar:

# heading     : Security # description : Remote access # navigation  :
1000 1200

Note on character set encodings: Valid character sets are "ISO-8859-1", "US-ASCII", "UTF-8" and "UTF-16".

get_languages

Override for CGI::FormMagick::get_languages to only return languages which are installed on this server

page_pre_event

This method overrides the same method in CGI::FormMagick. It adds some functionality that is not specific to general CGI::FormMagick use, specifically the big-red error message whenever there are errors in the page.

_filename

Figures out the filename of the script being run, either from the arguments or by looking at the perl special variable $0.

_scriptname_from_filename

Given a filename such as that found in $0, follows symlinks and figures out the actual original filename. This is mostly used to turn /etc/e-smith/web/panels/manager/cgi-bin/whatever into /etc/e-smith/web/functions/whatever.

_lexicon_filename_list

Figures out the full filenames of all required i18n/l10n lexicons, and returns them as a list.

_read_lexicons

Given a list of lexicon filenames, reads each of them in and returns them as a concatenated string.

$fm->_navigation_setup(%args)

Sets up various properties related to the navigation menu, such as heading/description/etc. You need to pass it the same args as were passed to new(). It doesn’t return anything.

$fm->get_validation_attribute

This method overrides the one in CGI::FormMagick::Validator to forcibly add "nopipes" to the list of validations performed. Note that if the validation string contains "permitpipes", it will be removed, and "nopipes" will _not_ be added.

$fm->props_to_query_string()

Given a hash of properties, turns them into a CGI query string. Useful for if you need to pre-populate a form based on data from the accounts or config database. See the table on the first page of the "useraccounts" web function for an example.

EXPORTED FUNCTIONS

The following exported functions may be used in your FormMagick scripts and XML, for instance as page pre-events, validation routines, etc.

turn_off_buttons()

Turns off *all* buttons. Useful if you want to replace the Next/Prev style of navigation with something else.

print_button(’STRING’)

Given a string, prints a submit button with that string localised. For instance, print_button(’SAVE’) will localise SAVE and put it onto the button. This is used to replace the next/prev/etc buttons with custom buttons.

set_status_message($message)

Sets the status message to be displayed at the top of the next page.

print_status_message()

Prints an status message on the first page, to give an indication of success/failure of the previous step. Resets the status message to blank and turns off all buttons as a side-effect.

description

Return the description entry read from the script, or "Unknown"

heading

Return the heading entry read from the script, or "Unknown"

description_weight

Return the description weight entry read from the script, or zero

heading_weight

Return the heading weight entry read from the script, or zero

validate_password ($strength, $password)

Checks the supplied password for security. Strength can be "strong", "normal" or "none". A "strong" password passes the cracklib tests. A "normal" password passes the tests in CGI::FormMagick::Validator::Network::password, and "none" will accept any password. An invalid argument for ’strength’ is considered to be ’normal’.

validate_description ($description).

Checks the supplied description. Period is allowed in description

nopipes

Validation routine to ensure there are no pipe characters in a field. This is necessary because we don’t want them to end up in the esmith configuration databases. Note that this validation routine is automatically added to every field, so you do not have to call it explicitly.

gen_locale_date_string

Generates a date string in the preferred format for the locale.

success

This method takes a lexicon tag as argument, optionally with a page name as second argument (defaulting to ’First’), and sets the status message to the lexicon tag, and sets the next page. To make use of this, the page that the method is directing FormMagick to should have, as pre-event, the print_status_message method.

This method simply factor’s all of the results of successful operations, and helps to ensure that all results end up in looping back to the start page.

error

This method is much like the above ’success’ method, except it is intended for display of error messages.

It is currently identical to success(), but can be altered to yield different results, like addition of red text, or logging of the error, etc.

display_error

This method displays an error using the sme-error style. This should be used when displaying a page, and the error() method is not applicable.

display_success

This method displays a success message using the success style. This should be used when displaying a page, and the success() method is not applicable.

SEE ALSO

      CGI::FormMagick

      esmith::FormMagick::Tester

      esmith::FormMagick::LexTester

AUTHOR

Mitel Networks Corporation See http://www.e-smith.org/ for more information