esmith::FormMagick - esmith wrapper for CGI::FormMagick
use esmith::FormMagick;
my $f = new esmith::FormMagick();
$f->display();
my $f = new esmith::FormMagick( filename=>'/some/path/to/script' );
$f->display();
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.
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''.
Override for CGI::FormMagick::get_languages to only return languages which are
installed on this server
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.
Figures out the filename of the script being run, either from the
arguments or by looking at the perl special variable $0.
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.
Figures out the full filenames of all required i18n/l10n lexicons, and
returns them as a list.
Given a list of lexicon filenames, reads each of them in and returns
them as a concatenated string.
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.
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.
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.
The following exported functions may be used in your FormMagick scripts
and XML, for instance as page pre-events, validation routines, etc.
Turns off *all* buttons. Useful if you want to replace the Next/Prev
style of navigation with something else.
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.
Sets the status message to be displayed at the top of the next page.
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.
Return the description entry read from the script, or ``Unknown''
Return the heading entry read from the script, or ``Unknown''
Return the description weight entry read from the script, or zero
Return the heading weight entry read from the script, or zero
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'.
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.
Generates a date string in the preferred format for the locale.
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.
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.
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.
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.
the CGI::FormMagick manpage
the esmith::FormMagick::Tester manpage
the esmith::FormMagick::LexTester manpage
Mitel Networks Corporation
See http://www.e-smith.org/ for more information
|
