DBCachePlugin

Description

This is a lightweighted frontend to the DBCacheContrib. The provided tags DBQUERY and DBCALL can be used as a drop-in replacement for SEARCH and INCLUDE that use the database store instread of searching and extracting on the raw topic files. If you are looking for a more sophisticated way of handling queries and sub-queries then have a look at the TWiki:Plugins.FormQueryPlugin.

DBQUERY is provided to ease the use of TWikiApplications based on the DBCacheContrib combining its flexible query language with unrestricted formatting and an extend mechanism to extract topic properties.

DBCALL is named "call" and not "include" as its main purpose is to ease TWikiApplications where TopicFunctions are treated as stored procedures. It fetches pre-compiled topics or sections of it. "Glue" chars (see TWiki:Plugins:GluePlugin) are applied in advance so that the actual rendering time is minimized. DBCALL does therefore not allow to call "external" pages as INCLUDE allows. DBCALL's "warn" parameter can only be set to "on" and "off" and does not allow alternative content in case of a warning. The "pattern" feature used to extract a fragment from an INCLUDEd text using regular expression has been dropped. That aside, DBCALLs can be called recursively as INCLUDEs can, parametrized using key-value arguments and obeys to %STARTINCLUDE%, %STOPINCLUDE%, %STARTSECTION{"..."}% and %ENDSECTION{"..."}%.

Using the DBCacheContrib topic sections are stored into the topic object of the database. The section between %STARTINCLUDE% ... %STOPINCLUDE% is called _sectiondefault whereas all sections between %STARTSECTION{"<name>"}% .... %ENDSECTION{"<name>"}% are called _section<name> and are stored accordingly.

Syntax

DBQUERY

DBQUERY can be used in either of two modes (a) as a pure search tool or (b) as a tool to extract properties of (a set of) known topics.

Syntax:

%DBQUERY{"<search>" ... }%
"<search>"	search clause, see documentation of the DBCacheContrib (mode (a))
topics="..." or topic="..."	set of topics to consult (mode (b)); if "topics" are specified in addition to a "search" it will be restricted to the given topics
web="..."	web where to search for hits; defaults to the current one
format="..."	format string to display search hits; defaults to "$topic"; the special format string "none" disables the format string
header="..."	format string to prepended to the list of hits
footer="..."	format string to appended to the list of hits
separator="..."	format string used to separate hits; defaults to "$n"; the special separator "none" disables separation
include="..."	pattern each found topic name must match to be considered a hit
exclude="..."	pattern each found topic name must not match to be considered a hit
order="..."	specifies the sorting of hits; defaults to "name"
reverse="..."	specify if hits should be sorted in reverse order; defaults to "off"
limit="..."	maximum number of topics to include in the hit set
skip="..."	number of topics to skip while constructing the hit set; defaults to "0"
hidenull="..."	flag to indicate that an empty hit set should not be displayed

Following variables are expanded in format strings:

• $percnt: % sign
• $dollar: $ sign
• $n: newline
• $t: tab
• $nop: "empty string"
• $count: the number of hits
• $web: the web where the hits where found
• $formfield(<formfield-name>): the value of the given formfield
• $formatTime(<formfield-accessor> [,<format>]): format the datefield pointed to by the <formfield-accessor> using the given <format>; the format can be in any form supported by TWiki::Func::formatTime() (see TWikiVariables documentation).
• $expand(<formfield-accessor>): return the formfield pointed to by the <formfield-accessor>
• $encode(...): encode entities so that the text can be included in an rss feed
• $flatten(...): remove any special markup producing a flattened text representation
• $trunc(...,length): truncate a string to the given length

Formfield accessors:

In its most basic form $expand(Ref) is identical to $formfield(Ref). In addition $expand() can be used to refer to topic properties of related topics that can be reached from the current one using the '@' symbol. For example, if a topic A uses a form that contains a field named "Ref" and specifies a reference to another topic B (by using its name) you can access the "Headline" in B from A using $expand(@Ref.Headline). A formfield accessor can be a composed one using 'or' and 'and'. Example: $expand(Name or Author) will expand to the value of the formfield "Name" if it exists and is non-empty and to the value of the formfield "Author" otherwise. More valid examples:

• $expand(@Ref.Headline): headline of the refered topic
• $expand(Nr and '.'): append a dot to the formfield value "Nr" if it exists
• $expand(Name or Author): expand to "Name" or "Author"

DBCALL

Fetch topic content or a section of it from the database store.

Syntax:

%DBCALL{"<topic" ... }%
"<topic>"	topic that we'd like to call
section="..."	optional named section; without this parameter the "default" section is used
<key>="<value>"	topic arguments to be substituted within the included text; that is every occurence of <key> is substituted with <value>
warn="on,off"	enable/suppress error warnings

DBSTATS

Compute and format a statistics on the database.

Syntax:

%DBSTATS{"<search>" ...}%
"<search>"	query string that defines a search, see DBCacheContrib
web="..."	the web where to search in (default: current web)
field(s)="..."	name of one or more formfields to be extracted (default: "text")
pattern="..."	regex pattern to extract keys from the formfield(s); you must provide a group ("(...)") in the pattern string that encloses the key to be extracted (default: "(\w+)")
header="..."	header format string to be prepended to the output
format="..."	format string used for each key in the output
sep(arator)="..."	separator to put between formatted keys
footer="..."	footer format string to be appended to the output
sort="alpha,created"	order of keys in the output
reverse="on,off"	sort keys descending or ascending
limit="..."	maximum number of keys to be formated in the output
hidenull="..."	flag to indicate that an empty hit set should not be displayed

The DBSTATS searches for all topics in given web and reads the given form fields. It then uses the pattern to extract any key in the data and counts their occurrence. The result is rendered using the format parameter for each token found, separating them by sep, prepend the header and append the footer. Results can be sorted alphabetically or by createdate.

Format strings (header, format, footer) can use the following variables to insert the computed statistics:

• $key: the found key, this must match the first group in the pattern argument
• $count: the number of occurences of the key
• $index: index of the key within the sorted result set
• $min: minimum count found in the search
• $max: maximum count found in the search
• $mean: mean occurence of a key in the result set
• $keys: total number of keys found
• $web: the web we search in

DBDUMP

Display the database record of a topic (usefull for debugging).

Syntax:

%DBDUMP{"<topic>" ... }%
"<topic>"	topic that we'd like to debug
web="..."	name of the web to look for the given topic; note that you can use the dot-notation in specifying the web.topic also

Perl API

The DBCachePlugin supports overloading the contained default database cache by inheriting from DBCachePlugin::WebDB being itself a DBCacheContrib. The only purpose of the DBCachePlugin::WebDB is to extract the TopicFunctions contained in a topic as described above. You can easily extend this functionality by deriving a WebDB specific to your own TWikiApplication. For example, the TWiki:Plugins.BlogPlugin defines a WebDB of its own where it caches the createdate of a topic being either specified in a formfield or given in the timestamp of the first revision of a topic.

DBCachePlugin

getDB()

Returns a database object used for further queries. This function must be called ahead of any actual database access. If your TWikiApplication is using a derived WebDB then use the WEBDB variable in your WebPreferences to point to its implementation (example: =Set WEBDB = TWiki::Plugins::BlogPlugin::WebDB=). If WEBDB is not defined the default implementation TWiki::Plugins::DBCachePlugin::WebDB is used. Note, that this way only one application-specific database cache can be loaded per web. This is rather a design decision; otherwise each DBQUERY and DBCALL tag would have to declare which database it operated on. So currently the rule of thumb is: one web one TWikiApplication making use of this plugin.

$webDB = getDB($web)
web	name of the web whose database is to be loaded

returns a database object. See the TWiki:Plugins::DBCacheContrib documentation for its interfaces.

DBCachePlugin::WebDB

This implements the database object that is used to access the topic records in a web. Note, that for each web there is exactly one WebDB database object. A database object is fetched (and initialized if needed) by the DBCachePlugin::getDB() function.

dbQuery()

The DBQUERY functionality can be access from within perl using the plugins dbQuery() method.

(@$topicNames, %$topicObjs, $errorMsg) = $db->dbQuery([$search, @$topics, $order, $reverse, $include, $exclude])
webDB	database object
search	search clause
topics	restrict search to this list of topics
order	define a sorting on the hit set; this can be any formfield accessor or one of the shortcuts "created" (for createdate) or "modified" (for info.date) provided for compatibility with TWiki's SEARCH
reverse=on,off	revert the sorting order
include	pattern that topic names must match to be considered a hit
exclude	pattern that topic names must not match to be considered a hit

returns a list pointer of all found topics names, a hash pointer to an array of all found topic objects (keys are the name of the topics) and a possibly defined error message.

getFormField()

Access the formfield value of an arbitrary topic.

$value = $db->getFormField($topic, $formfield)
topic	a topic name
formfield	a formfield name

returns the value of the named formfield

TODO: document the rest of the methods

Plugin Settings

Plugin description:

• Set SHORTDESCRIPTION = Lightweighted frontend to the DBCacheContrib

Each web can specify an alternative implementation inheriting from DBCachePlugin::WebDB. To specify it you have to set the WEBDB variable in the WebPreferences. If not the following is the default paramenter (omitting the #)

• #Set WEBDB = TWiki::Plugins::DBCachePlugin::WebDB

Plugin Installation Instructions

• Download the ZIP file
• Download and install all additionally required plugins listed in the dependencies information below
• Unzip DBCachePlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/DBCachePlugin.txt	Plugin topic
  lib/TWiki/Plugins/DBCachePlugin.pm	Plugin Perl module
  lib/TWiki/Plugins/DBCachePlugin/Core.pm	Plugin Perl module
  lib/TWiki/Plugins/DBCachePlugin/WebDB.pm	Plugin Perl module

Plugin Info

Plugin Author:	TWiki:Main.MichaelDaum
Copyright ©:	2005-2006, MichaelDaum@WikiRing.com
License:	GPL (GNU General Public License)
Plugin Version:	v1.22
Change History:
15 June 2006:	generate an inline error instead of an oops on a bad search string to DBQUERY
05 Mai 2006:	don't segfault on uncompiled WebDB implementations
30 Mar 2006:	added WebDB property createdate formerly only known by the BlogPlugin; dont choke twiki if DBDUMPing a non-existing topic;
27 Mar 2006:	added $trunc()
20 Mar 2006:	using TWiki::Attrs to parse section names
12 Mar 2006:	added hidenull to DBSTATS
10 Mar 2006:	use ENV instead of the CGI object to detect the current cgi action
02 Mar 2006:	fixed bad init error showing up on speedy/mod_perl
01 Mar 2006:	added DBSTATS tag; modularized the plugin for delayed compilation
15 Feb 2006:	don't use the query object in scripted mode
14 Feb 2006:	forcing to reload the database after a save
10 Feb 2006:	more performance on mod_perl/speedy_cgi: don't reload the topic cache if it hasn't changed
03 Jan 2006:	fixed INCLUDING(WEB,TOPIC) in DBCALL; don't apply glue in advance anymore when storing topic sections, it's serving a better purpose when done during a DBCALL
26 Jan 2006:	fixed internal links in DBCALL; support for STARTSECTION, old SECTION being deprecated
24 Nov 2005:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	none
Other Dependencies:	TWiki:Plugins/DBCacheContrib
Perl Version:	5.8
Benchmarks:	GoodStyle nn%, FormattedSearch nn%, DBCachePlugin nn%
Plugin Home:	TWiki:Plugins/DBCachePlugin
Feedback:	TWiki:Plugins/DBCachePluginDev
Appraisal:	TWiki:Plugins/DBCachePluginAppraisal

-- TWiki:Main.MichaelDaum - 15 June 2006