5,576
edits
Changes
Jump to navigation
Jump to search
Created page with "{{Level|Developer}} === 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-t..."
{{Level|Developer}}
=== 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
[[Category:Howto]]
[[Category:SME Server Development Framework]]
[[Category:Development Tools]]
[[Category:SME9-Development]]
=== 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
[[Category:Howto]]
[[Category:SME Server Development Framework]]
[[Category:Development Tools]]
[[Category:SME9-Development]]