The ExSite kernel consists of the libraries that perform the core services of ExSite. These services include:
System configuration settings are stored in the %config global
variable, which is initialized with defaults in Config.pm. The %config variable
is a nested hash which contains parameters that are often bundled into
groups, for example:
$config{parameter}
$config{group}{parameter}
$config{group}{subgroup}{parameter}
To change configuration settings in your local installation, you can
specify your preferred values in the file exsite.conf (place this file
in cgi-bin, or cgi-bin/conf). The format to change the parameters
above would be:
parameter = value
group.parameter = value
group.subgroup.parameter = value
There is no need to quote values; it will take in everything
from the first non-whitespace character after the "=" to the end of the
line.
To create parameter groups, simply use them as above. ExSite
will automatically create the group as needed. To create arrays
of values, define the first value as above, then add more values to it,
like so:
group.subgroup.parameter += anothervalue
In your code, this will be represented by a structure like:
$config{group}{subgroup}{parameter} = [ "value", "anothervalue" ];
You can inspect Config.pm to get a complete list of system
configuration settings. (They are fairly well commented.)
You can also obtain a quick listing of all configuration parameters
with their current settings using the utility script printconf.pl, which is distributed in the bin
directory of the ExSite Base distribution. This will print out
the over 400 known configuration settings and their values in your
installation.return $msg{"Permission denied - please log in."};
If you have defined a language preference, and a translation exists for
this message, that translated message will be used. If no
translation exists, or you are using the default language
configuration, then you will get the message as it is coded. If
you do not use this technique for handling system messages, and simply
output a string in Engligh (or any other language), your messages will
still work, but will not benefit from the built-in internationalization
features of ExSite.Kernel configuration parameters are written into exsite.conf, but plug-in web application modules may have their own configuration data that is read from separate files.
When ExSite dynamically loads a plug-in module named Foo, it looks for a matching configuration file in cgi-bin/conf/Foo.conf. The parameters in this file are loaded into $config{Foo}{...}. For example, if cgi-bin/conf/Foo.conf contains the parameter:
group.parameter = 10
then this will be loaded into $config{Foo}{group}{parameter}. This is equivalent to the following written into the main config file, exsite.conf:
Foo.group.parameter = 10
Plug-in modules do not have to define their own configuration files or parameters, so the presence of a plug-in module does not ensure that these configuration categories will exist.
The file cgi-bin/myConfig.pm
is automatically loaded by ExSite when it starts up. As
distributed, this file contains only a few code stubs that do
nothing much. However, the local site can add their own kernel
customization code into this file, using various hooks that the system
provides for this purpose. It is best practice to keep your
customizations restricted to this file, so that the kernel itself can
be easily upgraded as needed.
The primary hooks are:
sub my_handlers {
my $self = shift;
$self->handler("authenticate",\&my_custom_authenticate_function);
}
Your custom function should be included in myConfig.pm. It will execute as if a member of the calling object's class.ExSite contains many hooks for handlers at various
places in the Kernel and also in some plug-ins. Each hook has a
unique name. If you register a handler routine for that name,
your special routine will be executed whenever that hook is reached
during execution.
Handlers should return a single scalar value. By convention
they return undef if they abort (such as if the handler decides that it
should not do anything special in this case). In that case,
ExSite will proceed with the regular system code. However, if the
handler returns a defined value, then ExSite knows that it executed and
performed its special function. ExSite then has the option of not
executing the regular system code.
Multiple handlers can be registered under a given hook's name.
In this case, each handler will be executed in turn (in the order in
which they were registered) until one returns a defined value,
indicating that it executed. At that point, no further handlers
under that hook will execute.
Handlers may accept any number of parameters as input. Because
they typically substitute for standard system routines, they usually
take the same parameter list as their corresponding system
routine. You should always check the code to verify how handlers
are called, and how their output is processed.
The kernel method that displays a datum taken from an ExSite-managed database is ExSite::Report::show_data(). It accepts up to 4 parameters: the table name, the column name, the data value, and optionally the record id. ExSite determines how to display the data value based on the datatype of this column and other factors. This routine has a hook called "show_data" that can be used to override the system rules for displaying data. If you needed to override this logic in particular cases, you would create a handler, for instance:
sub my_show_data {
my ($this,$table,$column,$data,$id) = @_;
# special display logic for internet users
if ($ENV{REMOTE_ADDR} !~ /^192\.168/) {
# user is not on our LAN -
# block the display of all columns from "secure_data" table
if ($table eq "secure_data") {
return "n/a";
}
}
# in all other cases, return undef to use default kernel logic
return undef;
}
In this example, we override the ExSite::Report::show_data() logic in the case where the system is showing data from one particular sensitive table to a user who is not on our LAN. In this case, the system always returns "n/a" as the data value. Otherwise the handler returns undef, which tells ExSite that the handler aborted and ExSite should proceed with its normal logic to display the requested data.
The above handler would be registered in &my_handlers using a call like this:
$self->handler( "show_data", \&my_show_data );
sub foo_bar {
my ($self,$input) = @_;
# hook to execute a handler if one exists
my $stat = $self->run_handler("foo_bar",$input);
return $stat if (defined $stat);
# resume normal execution
...
}
In this example, we try to run any handlers registered under the
"foo_bar" hook. If none exist, or the ones that are registered do
not take any action, the hook returns an undef, and we execute our
regular code. If, on the other hand, an actual return value is
received back, we know that our handlers executed and did
something. In this case we use that return value as our own
return value, and do not bother to execute the default code. In
practice, you can do anything you like with the return value.This is a list of hooks in the ExSite kernel libraries as of
v3.6. Other hooks may also exist in other CGI programs or plug-in
modules.
| approve | allow the user to perform some database function |
| authenticate | confirm the user's claimed identity |
| authorize | grant the user a certain level of access |
| build_form | generate an HTML form based on data that has been provided to FormBuilder |
| cancel_form | executed when user hits a cancel button on a form |
| crypt_key | obtain encryption key |
| decrypt | decrypt some ciphertext |
| delete_key | delete a single record |
| do_login | login a user |
| encrypt | encrypt some plaintext |
| fetch_metadata | obtain metadata for an object |
| find_ancestor | find the root record in a tree of record relationships |
| find_owner | find the user who has authority over a data record |
| group_owns | find the group who has authority over a data record |
| identify | determine who the user is claiming to be |
| import_record | modify data that is about to be imported into the database |
| input_column | generate an HTML input field corresponding to a database column |
| input_date | generate an HTML date input field |
| input_exsite | generate an HTML input field corresponding to an ExSite datatype |
| is_member | test if user is a member of a section or site |
| login | validate a login/password pair |
| login_form | generate an HTML form for the user to log in |
| login_reminder_form | generate an HTML form for the user to get a password reminder or reset |
| login_temp | log the user in for the current request, but do not let the identity persist |
| log_login | do something when a successful login occurs |
| lookup | find the user information corresponding to the user's claimed identity |
| my_name | return the user's actual name |
| page_authorize | allow the user to view a web page |
| page_get_url | get the URL for a web page |
| post_delete | do something after a database deletion |
| post_insert | do something after a database insertion |
| post_make_content | do something after a new content object is created |
| post_make_page | do something after a new page is created |
| post_make_section | do something after a new section is created |
| post_select | do something after records have been fetched |
| post_update | do something after records have been updated |
| pre_delete | do something before a database deletion |
| pre_insert | do something before a database insertion |
| pre_make_content | do something before a new content object is created |
| pre_make_page | do something before a new page is created |
| pre_make_section | do something before a new section is created |
| pre_select | do something before records have been fetched |
| pre_update | do something before records have been updated |
| report_generic | format an HTML report based on data collected by ReportBuilder |
| report_links | create links/tools in database reports |
| report_links_extra | append extra links/tools in database reports |
| report_title | compose a title for automatically generated database reports |
| select_foreign_key | fetch the list of records to be selected from when building a select input to point to a foreign key |
| select_foreign_key_label | create the selector strings used to select foreign keys in select inputs |
| show_data | display any datum taken from the database |
| trash_r | recursively move records to the trash |
| user_owns | determine if the user owns a data record |
| validate | determine if data in a recordhash is valid and can be dispatched to the database |
| validate_column | determine if a datum corresponding to a particular database column is valid and can be dispatched to the database |
| validate_datatype | determine if a datum matches the expected format for its datatype |