See
PublishedAPI for packages intended to be used by Plugin and Contrib authors, or
browse all packages.
See also
Developing plugins,
Developer's Bible,
Technical Overview
Methods used to query and manipulate the configuration spec.
Contract
All the methods take two parameters; a parameter hash, and a
reporter. The parameter hash is described for each method,
as is the return value, which is always a perl reference.
All methods return undef if they fail badly. $reporter→ERROR is used to
describe fatal errors to the caller.
The $reporter should be clear before calling any of these methods,
as existing errors in the reporter will be detected as fatal errors
and cause the method to fail.
StaticMethod getcfg(\%params, $reporter) → \%response
Retrieve for the value of one or more keys. \%params may include
-
keys - array of key names to recover values for.
If there isn't at least one key parameter, returns the
entire configuration hash. Values are returned unexpanded
(with embedded $Foswiki::cfg references intact.)
The result is a hash containing that subsection of %Foswiki::cfg
that has the keys requested.
StaticMethod search(\%params, $reporter) → \@response
-
search - text fragment to search for
Search headlines and keys for a fragment of text. The response
gives the path(s) to the item(s) matched in an array of arrays,
where each entry is a single path.
Searches are case-sensitive.
StaticMethod getspec(\%params, $reporter) → \%response
Use a search to find a configuration item spec. \%params may include:
-
get - specifies the search. The following fields can be used in searches:
-
headline - title of a section,
-
typename - type of a leaf spec entry,
-
parent - a structure that will be used to match a parent,
-
keys - keys of a spec entry,
-
desc - descriptive text of a section or entry.
-
depth - matches the depth of a node under the root (which is depth 0)
-
depth - specifies the depth of the subtree below matched items to return.
Only exact matches are supported.
For example,
{ 'get': {'headline':'Store'}} will retrieve the entire
spec subtree for the section called 'Store'.
{ 'get' : {'keys' : '{Store}{Implementation}'}} will retrieve the spec
for that one entry. You cannot pass a list; if you require the spec for a
subsection, retrieve the section title.
{ 'get' : { 'parent' : {'headline' : 'Something'}, 'depth' : 0} will
return all specs within the section named
Something.
The response is a reference to the spec subtree. Note that this will
contained blessed hashes.
StaticMethod check_current_value(\%params, $reporter) → \@response
Runs the server-side
check-current_value checkers on a set of keys.
The keys to be checked are passed in as key-value pairs. You can also
pass in candidate values that will be set before any keys are checked.
-
set - hash of key-value pairs that maps the names of keys to the value to be set. Strings in the values are assumed to be unexpanded (i.e. with $Foswiki::cfg references intact).
-
keys - array of keys to be checked (or the headline(s) of the sections(s) to be recursively checked. '' checks the root. All keys under the headlined section(s) will be checked). The default is to check everything under the root.
-
check_dependencies - if true, check everything that depends on any of the keys being checked. This include dependencies explicitly expressed through CHECK and implicit dependencies found from the value of the checked item.
The results of the check are reported in an array where each entry is a
hash with fields
keys and
reports.
reports is an array of reports,
each being a hash with keys
level (e.g.
warnings,
errors), and
message.
NOTE check_dependencies will look into the values of other keys for
$Foswiki::cfg references, for example into the entries in a PERL hash.
If a dependency is found, the closest checkable entity (i.e. the PERL
key) will be checked, and
not the subkey.
StaticMethod wizard(\%params, $reporter) → \%response
Call a configuration wizard.
Configuration wizards are modules that support complex operations on
configuration data; for example, auto-configuration of email and complex
and time-consuming integrity checks.
-
wizard - name of a wizard class to load
-
keys - name of a checker to use if wizard is not given
-
method - name of the method in the wizard or checker to call
If the wizard method returns an object, that will be passed back
as the result of the call. If the wizard method returns undef, the
return result is a hash containing the following keys:
*
report - Error/Warning etc messages, formatted as HTML. Each
entry in this array is a hash with keys 'level' (e.g. error, warning)
and 'message'.
-
changes - This is a hash mapping changed keys to their new values