Difference: FormQueryPlugin ( vs. 1)

Revision 12008-12-12 - TWikiGuest

Line: 1 to 1
Added:
>
>

FormQueryPlugin

The FormQueryPlugin provides a query interface to the TWiki::Contrib::DBCacheContrib module, giving a way to present query results as formatted tables.

When using the plugin each topic is treated as a container for data fields. These fields can be the fields in the form attached to the topic, or can be parsed out of the topic. The database is managed by the TWiki::Contrib::DBCacheContrib module, which must be installed for this plugin to work.

The tutorial section of this topic gives an introduction to formulating and formatting queries using this plugin, and is a good place to start.

Note: This variant of FormQueryPlugin is incompatible with earlier releases by

  • removing support for features that are not part of the core functionality of this plugin, and
  • striving towards compatibility with core TWiki functionality and key plugins such as SpreadSheetPlugin.
If the requirements management features of earlier versions of FormQueryPlugin are required, do not use this version.

On this page:

Features

  • Perform complex queries on the database
  • Extensive conditional formatting support
  • Automatic derivation of new topic names
  • Recognition and special formatting of key data strings

How the database gets built

The basic database is built using the DBCacheContrib. Refer to the documentation of that module for details of how it works.

As well as the form data loaded by the DBCacheContrib, the FormQueryPlugin adds the ability to extract embedded tables from topics.

Embedded tables that follow a specific format (defined using the EditTablePlugin) are added to the topic as an array of rows, each of which contains a map keyed on the fields and mapping to the values in the table. This array is added to the topic as a field named the same as the table type. Where there are multiple tables of the same type in a topic, they are concatenated together into a single array. See Settings for more information about how to set up tables.

Topics can also be automatically related to each other by name. The plugin uses something called Topic Relations that allow the creation of two-way relationships between topics. Topic relations from parent topics to child topics are stored in the map of the parent topic using the name of the relation as the field name and an array of references to the maps of child topics. Reverse relations from child to parent topics are also stored. See Settings for more information about how to set up topic relations.

Most of the rest of this documentation describes how to search this database and generate reports.

Syntax Rules

A query has first to be formed using FORMQUERY, and then shown using SHOWQUERY. You can combine these operations using DOQUERY. Queries are output according to a format specification in the parameters to SHOWQUERY. You can cache these specifications for re-use by defining them using TABLEFORMAT.

Queries

%FORMQUERY

%FORMQUERY is the basic query mechanism. A %FORMQUERY works either on the whole database or, if the query parameter is given, the results of another query.
Parameter Description
name Required, gives the name of the query result for use in %SHOWQUERY or another %FORMQUERY
search Required, the search to perform (see Search operators). Default parameter; the keyword search may be omitted.
casesensitive Optional, if missing or off search is not casesensitive.
query Optional, the name of the query to refine. If missing, defaults to the whole database
extract Optional, the name of a field in each of the matched maps to flatten out into the returned list.
moan Optional, "on" or "off", if set to "off" will disable match failed message

For example, 

%FORMQUERY{name=AQuery search="Owner='Main\.Fred'"}%
%FORMQUERY{name=BQuery query=AQuery search="Product='Boiled Egg'"}%
%FORMQUERY{name=CQuery query=BQuery search="" extract=CookingTimes}%
%FORMQUERY{name=DQuery query=CQuery search="Time < '4'"}%
will search for all topics with a form field Owner set to Main.Fred, then filter that down to those topics that have Product set to Boiled Egg. Then it will extract and flatten out the embedded table CookingTimes in each matched topic. By "flatten out" we mean that future queries on CQuery must refer to the fields of the CookingTimes table, not the fields of the topic, i.e. CQuery will be an array of all the rows in the embedded table. Finally it will filter down to those rows that have the column Time < 4 minutes.

Of course there is more than one way to skin a cat. A faster way to formulate the same query would be to say: 

%FORMQUERY{name=AQuery search="Owner='Main\.Fred' AND Product='Boiled Egg'" extract=CookingTimes}%
%FORMQUERY{name=DQuery query=AQuery search="Time < '4'"}%

FORMQUERY is normally silent i.e. it generates no output unless there is an error, in which case an error description is inserted. This error message can be disabled using the moan parameter which makes FORMQUERY totally silent.

Search operators

Fields are given by name, and values by strings or numbers. Strings should always be surrounded by 'single-quotes'. Strings which are regular expressions (RHS of , ~ operators) use 'perl' regular expression syntax (google for =perlre for help). Numbers can be signed integers or decimals. Single quotes in values may be escaped using backslash (\).

The following operators are available:

Operator Result Meaning
= Boolean LHS exactly matches the regular expression on the RHS. The expression must match the whole string.
!= Boolean Inverse of =
=~ Boolean LHS contains RHS i.e. the RHS is found somewhere in the field value.
< Boolean Numeric <
> Boolean Numeric >
>= Boolean Numeric >=
<= Boolean Numeric <=
lc String Unary lower case
uc String Unary UPPER CASE
EARLIER_THAN BOOLEAN Date is earlier than the given date
LATER_THAN Boolean LHS is later than the given date (string containing a date e.g. '1 Apr 2003')
WITHIN_DAYS Boolean Date (which must be in the future) is within n working days of todays date
! Boolean Unary NOT
AND Boolean AND
OR Boolean OR
() any Bracketed subexpression

Dates for EARLIER_THAN, LATER_THAN and WITHIN_DAYS must be dates in the format expected by Time::ParseDate (like the ActionTrackerPlugin). WITHIN_DAYS works out the number of working days (i.e. excluding Saturday and Sunday). Apologies in advance if your weekend is offset ± a day! Integers will automatically be converted to dates, by assuming they represent a number of seconds since midnight GMT on 1st January 1970.

Search operators work on the fields of each map, be it a topic or an embedded table row.

Fields can be simple field names or can be more complex, and may even contain embedded searches. See Fields below for more information.

A search defined as some text string without any search operators is interpreted as text=~'string'.

At present there is no way to constrain a search on the contents of a contained table, such as an embedded table or forward relation. However there are usually ways around this; for example, a %FORMQUERY that uses extract to flatten all the sub-tables, and then use of the parent relation to complete the search. For example: 

%FORMQUERY{name=AQuery search="Product='Boiled Egg'" extract=CookingTimes}%
%FORMQUERY{name=DQuery query=AQuery search="Time < '4' AND CookingTimes_of.Owner='Main\.Fred'"}%

Fields
Field references can be as simple as the name of a field, or may be more complex expressions that can even include embedded searches. The precise interpretation of the syntax depends on the type (Map or Array) of the object being referenced.

Arrays

  • N where N is a number will get the Nth entry in the array e.g. attachments.9
  • X will return the sum of the subfield X of each entry e.g. TaskTable.Effort will sum the Effort column in a table called TaskTable.
  • [?search] will perform the given search over the entries in the array. Always returns an array result, even when there is only one result. For example: attachments[?name='pitcha.gif'] will return an array of all the entries that have their subfield name set to pitcha.gif.
  • [*X] will get a new array made from field X of each entry in this array. For example attachments[*size] will get an array of the sizes of each attachment.
Maps
  • X will get the subfield named X. For example, Product will get the formfield named Product.
  • X.Y will get the subfield Y of the subfield named X.
In all cases
  • # means "reset to root". So #.Y will return the subfield Y of the Map at the root of the query.

Reports

%TABLEFORMAT

%TABLEFORMAT provides a template for the display of values extracted from a query (like the old Fortran 'format' statement).
Parameter Description
name Required, gives the name of the format for use in %SHOWQUERY or another %FORMQUERY
format Required, gives the format of the body rows (or the format to subclass)
header Optional, gives the format of the header row
separator Optional, separate rows with this (default newline)
footer Optional, gives the string to use to terminate the table
sort Optional, defines the sort order
help Optional, if present then a helpful message will be output for undefined fields. So if you see a table entry that is blank and you don;t think it should be, add the help parameter and it should give some guidance.
moan Optional, "on" or "off", if set to "off" disables error output

The header, footer and format parameters are very similar in application to the parameters used in the standard %SEARCH TWiki command. For the uninitiated, the header is used to define the first row of the results table: 

header="| *Topic* | *Summary* |"
header="<table><tr><th>Topic</th><th>Summary</th></tr> |"
footer="</table>"

The format parameter is overloaded so it can also be used to refer to a table format previously defined using %TABLEFORMAT. This allows you to derive new formats (e.g. with different sort orders) For example, 

%TABLEFORMAT{ name=TBLFMT format="|$topic|" sort="Owner,Priority"}%
%TABLEFORMAT{ name=SUBFMT format=TBLFMT sort="Priority,Owner" }%
Any of the header, footer or sort parameters in the referenced table format can be overridden by giving new values in the %SHOWQUERY.

The footer is usually only used for tables generated directly in HTML, in which case it is usually set to footer="</table>" 

footer="</table>"

The format is used to define the rows in the body of the table:

format="| $topic | $Summary |"

Any fields in the form in the topic can be output by putting a $ sign before the name of the field. The two special fields $topic and $form are available for outputting the name of the topic and the type of the form. You can also refer to fields in related topics using the syntax $field.field where $field is the name of the relation and field is a field in the related topic; for example, format="|$Child_of.topic|".

The following special variables can be used in the format string:

Name: Expands To:
$web Name of the web
$topic Topic name
$topic(20) Topic name, "- " hyphenated each 20 characters
$topic(30, -<br />) Topic name, hyphenated each 30 characters with separator "-<br />"
$topic(40, ...) Topic name, shortended to 40 characters with "..." indication
$parent Name of parent topic; empty if not set
$parent(20) Name of parent topic, same hyphenation/shortening like $topic()
$text Formatted topic text.
$locked LOCKED flag (if any)
$date Time stamp of last topic update, e.g. 28 Apr 2025 - 15:16
$isodate Time stamp of last topic update, e.g. 2025-04-28T15:16Z
$rev Number of last topic revision, e.g. 1.4
$username Login name of last topic update, e.g. jsmith
$wikiname Wiki user name of last topic update, e.g. JohnSmith
$wikiusername Wiki user name of last topic update, like Main.JohnSmith
$createdate Time stamp of topic revision 1.1
$createusername Login name of topic revision 1.1, e.g. jsmith
$createwikiname Wiki user name of topic revision 1.1, e.g. JohnSmith
$createwikiusername Wiki user name of topic revision 1.1, e.g. Main.JohnSmith
$summary Topic summary, with 162 characters
$summary(50) Topic summary, with 50 characters
$summary(showvarnames) Topic summary, with %ALLTWIKI{...}% variables shown as ALLTWIKI{...}
$summary(noheader) Topic summary, with leading ---+ headers removed
Note: The tokens can be combined into a comma separated list like $summary(100, showvarnames, noheader)
$formname The name of the form attached to the topic; empty if none
$formfield(name) The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm. An alternative to using the name of the field directly.
$formfield(name, 10) Form field value, "- " hyphenated each 10 characters
$formfield(name, 20, -<br />) Form field value, hyphenated each 20 characters with separator "-<br />"
$formfield(name, 30, ...) Form field value, shortended to 30 characters with "..." indication
$pattern(reg-exp) A regular expression pattern to extract some text from the topic text (does not search meta data; use fields instead).
• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .*, and must end in .*
• Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*)
• Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ...
• This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance
• Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does
• Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag
$n or $n() New line
$nop or $nop() Is a "no operation". This variable gets removed; useful for nested search
$quot Double quote ("). Alternatively, write \" to escape it.
$percnt Percent sign (%)
$dollar Dollar sign ($)

It is also possible to expand the contents of tables embedded in the topic, in two ways:

  • using the syntax $field[format=FORMAT] where $field is the table type, which is named the same as the table topic, and FORMAT is the name of a format previously defined using %TABLEFORMAT and suitable for expanding the sub-table.
  • using the syntax $field.subfield where subfield is a numeric field in the contents of the embedded table (i.e. it contains a number). In this case the result will be the sum of all subfield values over all the rows in the table.

sort is used to define the sort order, and is a list of field names (without $'s) separated by commas. You can reverse the sort order for a column by prepending '-' to the field name. For example,

sort="Owner,-Priority"

The default sort method is string comparison. If the field data is numeric, then you can put a '#' in front of the field name to force the sort to be numeric. For example,

sort="Owner,#Priority"

or

sort="Owner,-#Priority"

%TABLEFORMAT is silent i.e. it produces no output on the page unless there is an error, in which case a descriptive error message is output. This message can be disabled using the moan parameter.

%SHOWQUERY

Used to show the results of a query, %SHOWQUERY accepts all the same parameters as %TABLEFORMAT (except name), and also the following parameters:
Parameter Description
query Required, gives the name of the query to show
start Optional, first row to display
limit Optional, number of rows to display, or all
For example, 
%SHOWQUERY{ query=AFORMQUERY format=ATBLFMT }%
Note: If you render your results in TWiki table format and limit the rows displayed using limit (e.g. first 10 from 99 rows), and also use TablePlugin to allow sorting on the headers, then only the 10 displayed rows will be sorted by TablePlugin (and not the full 99 rows in the table).

%DOQUERY

Combines a query and showing the results of that query, %DOQUERY accepts all the same parameters as %FORMQUERY and %SHOWQUERY (except name and query).

Interface to SpreadSheetPlugin

%QUERYTOCALC

Used to transform the results of a query into a format which SpreadSheetPlugin can operate on. %QUERYTOCALC accepts all the same parameters as %TABLEFORMAT (except name), and also the following parameters:
Parameter Description
query Required, gives the name of the query to show
start Optional, first row to display
limit Optional, number of rows to display, or all
For example, 
%QUERYTOCALC{ query=AFORMQUERY format=ATBLFMT }%
The query must be formatted as a table. This variable produces no output, but must precede any calculation on the resultant query.

%SHOWCALC

Operates on the result of a query represented as a table, using a previous %QUERYTOCALC. Accepts a single, unnamed parameter:
Parameter Description
  Required; the calculation to perform
The parameter is text as required by the $CALC statement (see SpreadSheetPlugins); all operations supported by %CALC are supported by %SHOWCALC. This command behaves identical to %CALC when used following a table; it operates on the implicit table constructed by a preceding %QUERYTOCALC statement. Arbitrary many %SHOWCALC can be performed; all apply to the preceeding implicit table.

Example: 

%SHOWCALC{"$ROW()"}%
returns the number of matches of a query that had been formatted as an implicit table.

Querying results of a search

%SUMFIELD

Used to calculate the sum of a numeric field across all the matches in a query result.
Parameter Description
query Required, name of the query to sum over
field Required, name of the field to sum
For example, let's say we have a form type called "VitalStatistics" that has a field "Age" in it. We can sum all the ages in all occurences of the form using: 
%FORMQUERY{name=vs search="form='VitalStatistics'"}%
Sum of ages = %SUMFIELD{query=vs field="Age"}%
The result is a single number representing the sum of all the fields.

Note that values embedded in tables can be summed using the shorthand described above.

%MATCHCOUNT

Used to determine the total number of results a query returned.
Parameter Description
query Required, name of the query to sum over
The result is a single number representing the number of results the query returned.

Tutorial

See TWiki::Plugins/FormQueryPluginTutorial for a tutorial describing how to use the plugin in real-world applications.

Formatted query examples

%TABLEFORMAT% is able to generate (roughly) the same output as FormattedSearch, based on an earlier query. Multiple different formatted results can be produced without having to rerun the query.

Bullet list showing topic name and summary

Write this:

%FORMQUERY{name="q1" search="topic=~'FAQ'" web="TWiki"}%
%SHOWQUERY{query="q1" header="   * *Topic: Summary:*" format="   * [[$web.$topic]]: $summary(25)"}%

To get this:

Extract some text from a topic using regular expression

Write this:

%FORMQUERY{name="q1" search="text=~'__Back to:__ TWikiFAQ'" web="TWiki"}%
%SHOWQUERY{query="q1" header="TWiki FAQs:" format="   * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$web.$topic][Answer...]]"}%

To get this:

TWiki FAQs:

  • Answer...
  • \s*([^\n]*).*) Answer"}% Answer...
  • I would like to install TWiki on my server. Can I get the source? Answer...
  • How can I create a simple TWiki Forms based application? Answer...
  • Why does the topic revision not increase when I edit a topic? Answer...
  • Answer...
  • What does the "T" in TWiki stand for? Answer...
  • How do I delete or rename a topic? Answer...
  • How do I delete or rename a file attachment? Answer...
  • TWiki is distributed under the GPL (GNU General Public License). What is GPL? Answer...
  • Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
  • What happens if two of us try to edit the same topic simultaneously? Answer...
  • So what is this WikiWiki thing exactly? Answer...
  • I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer...

Nested Search

Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.

For example, let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).

  • First search:
    • %FORMQUERY{name="q1" search="text=~'culture'" web="TWiki"}% %SHOWQUERY{query="q1" format="   * $web.$topic is referenced by:$n(list all references)"}%
  • Second search. For each hit we want this search:
    • %DOQUERY{"(topic found in first search)" separator=", " web="TWiki" format="$web.$topic"}%
  • Now let's nest the two. We need to escape the second search, e.g. the first search will build a valid second search string. Note that we escape the second search so that it does not get evaluated prematurely by the first search:
    • Use $percnt to escape the leading percent of the second search
    • Use \" to escape the double quotes
    • Use $dollar to escape the $ of $topic

Write this:

%FORMQUERY{name="q1" search="text=~'culture'" web="TWiki"}%
%SHOWQUERY{query="q1" format="   * $web.$topic is referenced by:$n      * $percntDOQUERY{\"$topic\" separator=\", \" web=\"TWiki\" format=\"$dollarweb.$dollartopic\"}$percnt "}%

To get this:

  • TextFormattingFAQ is referenced by:
    • %DOQUERY{"TextFormattingFAQ" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • TWikiFAQ is referenced by:
    • %DOQUERY{"TWikiFAQ" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • TWikiDownload is referenced by:
    • %DOQUERY{"TWikiDownload" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • AnApplicationWithWikiForm is referenced by:
    • %DOQUERY{"AnApplicationWithWikiForm" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • EditDoesNotIncreaseTheRevision is referenced by:
    • %DOQUERY{"EditDoesNotIncreaseTheRevision" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • FormQueryPlugin is referenced by:
    • %DOQUERY{"FormQueryPlugin" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • WhatDoesTWikiStandFor is referenced by:
    • %DOQUERY{"WhatDoesTWikiStandFor" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • DeleteOrRenameATopic is referenced by:
    • %DOQUERY{"DeleteOrRenameATopic" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • DeleteOrRenameAnAttachment is referenced by:
    • %DOQUERY{"DeleteOrRenameAnAttachment" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • GnuGeneralPublicLicense is referenced by:
    • %DOQUERY{"GnuGeneralPublicLicense" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • WikiCulture is referenced by:
    • %DOQUERY{"WikiCulture" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • SimultaneousEdits is referenced by:
    • %DOQUERY{"SimultaneousEdits" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • WhatIsWikiWiki is referenced by:
    • %DOQUERY{"WhatIsWikiWiki" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • SearchDoesNotWork is referenced by:
    • %DOQUERY{"SearchDoesNotWork" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • FormQueryPlugin is referenced by:
    • %DOQUERY{"FormQueryPlugin" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • FormattedSearch is referenced by:
    • %DOQUERY{"FormattedSearch" format="$web.$topic" separator=", " web="TWiki"}% :No values returned
  • WikiCulture is referenced by:
    • %DOQUERY{"WikiCulture" format="$web.$topic" separator=", " web="TWiki"}% :No values returned

Note: Nested search can be slow, especially if you nest more then 3 times. Nesting is limited to 16 levels. For each new nesting level you need to "escape the escapes", e.g. write $dollarpercntDOQUERY for level three, $dollardollarpercntDOQUERY for level four, etc.

Most recently changed pages

Write this:

%FORMQUERY{name="q1" search="" web="TWiki"}%
%SHOWQUERY{query="q1" limit="7" sort="info.date" format="| $web.$topic | $wikiusername | $date |"}%

To get this:

WebLeftBarLogin TWikiContributor 1970-01-01 - 01:00
SimultaneousEdits TWikiContributor 2005-03-27 - 15:14
WhatIsWikiWiki TWikiContributor 2005-03-27 - 15:14
SearchDoesNotWork TWikiContributor 2005-03-27 - 15:14
WebBottomBar TWikiContributor 2005-03-27 - 15:14
FileAttribute TWikiContributor 2005-03-27 - 15:14
BumpyWord TWikiContributor 2005-03-27 - 15:14

Search with conditional output

A regular expression search is flexible, but there are limitations. For example, you cannot show all topics that are up to exactly one week old, or create a report that shows all records with invalid form fields or fields within a certain range, etc. You need some additional logic to format output based on a condition:

  1. Specify a search which returns more hits then you need
  2. For each search hit apply a spreadsheet formula to determine if the hit is needed
  3. If needed, format and output the result
  4. Else supress the search hit

This requires the TWiki:Plugins.SpreadSheetPlugin. The following example shows all topics that are up to exactly one week old.

Write this:

%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%FORMQUERY{name="q1" search="name='.*'" web="TWiki"}%
%SHOWQUERY{query="q1" sort="info.date" format="$percntCALC{$dollarIF($dollarTIME($date) < $dollarGET(weekold), , | $web.$topic | $wikiusername | $date | $rev |)}$percnt" }%

  • The first line sets the weekold variable to the serialized date of exactly one week ago
  • The SHOWQUERY has a deferred CALC. The $percnt makes sure that the CALC gets executed once for each search hit
  • The CALC compares the date of the topic with the weekold date
  • If topic is older, a <nop> is returned, which gets removed at the end of the TWiki rendering process
  • Otherwise, the search hit is formatted and returned

To get this:

WebLeftBarLogin TWikiContributor 1970-01-01 - 01:00 6
TWikiIfNodeDotPm      
TWikiResponseDotPm      
TWikiQueryNodeDotPm      
TWikiUsersTWikiUserMappingDotPm      
TWikiUsersPasswordDotPm      
TWikiNetHTTPResponseDotPm      
TWikiInfixParserDotPm      
TWikiUICopyDotPm      
TWikiUIViewDotPm      
TWikiInfixNodeDotPm      
TWikiAccessControlExceptionDotPm      
TWikiLoginManagerDotPm      
TWikiUIChangeFormDotPm      
TWikiOopsExceptionDotPm      
TWikiUIRestDotPm      
TWikiUIUploadDotPm      
TWikiI18NDotPm      
TWikiEngineDotPm      
TWikiFormDotPm      
TWikiStoreRcsWrapDotPm      
TWikiConfigureCheckersCertificateKeyCheckerDotPm      
TWikiStoreSearchAlgorithmsForkingDotPm      
TWikiUIMdrepoUIDotPm      
TWikiUIRDiffDotPm      
TWikiAttrsDotPm      
TWikiAttachDotPm      
TWikiRenderDotPm      
TWikiEngineExceptionDotPm      
MacrosPlugin      
TWikiMergeDotPm      
TWikiFormListFieldDefinitionDotPm      
TWikiSearchDotPm      
TWikiUISearchDotPm      
TWikiNetDotPm      
TWikiCompatibilityDotPm      
TWikiSandboxDotPm      
TWikiI18NExtractDotPm      
TWikiFuncDotPm      
TWikiFormFieldDefinitionDotPm      
TWikiConfigureImgToolDotPm      
TWikiUserMappingDotPm      
TWikiAggregateIteratorDotPm      
TWikiUIDotPm      
TWikiIfParserDotPm      
SourceCode      
TWikiUIRegisterDotPm      
TWikiPluginsDotPm      
TWikiConfigureLoadDotPm      
TWikiMdrepoDotPm      
TWikiLoginManagerSessionDotPm      
WebLeftBarSearch      
TWikiConfigureCheckersCertificateDotPm      
TWikiPrefsDotPm      
TWikiStoreSearchAlgorithmsPurePerlDotPm      
TWikiListIteratorDotPm      
TWikiStoreRcsLiteDotPm      
TWikiStoreQueryAlgorithmsBruteForceDotPm      
TWikiUsersDotPm      
TWikiUIEditDotPm      
LdapContribAdminPlugin      
TWikiFormSelectDotPm      
TWikiRequestDotPm      
TWikiStoreRcsFileDotPm      
TWikiPrefsParserDotPm      
TWikiQueryParserDotPm      
TWikiUsersApacheHtpasswdUserDotPm      
TWikiTimeDotPm      
TWikiInfixErrorDotPm      
TWikiLoginManagerTemplateLoginDotPm      
TWikiUsersHtPasswdUserDotPm      
TWikiStoreDotPm      
TWikiPrefsPrefsCacheDotPm      
TWikiPluralsDotPm      
TWikiAccessDotPm      
TWikiPluginDotPm      
TWikiUIManageDotPm      
TWikiUIStatisticsDotPm      
TWikiUIOopsDotPm      
TWikiLoginManagerApacheLoginDotPm      
TWikiQueryHoistREsDotPm      
TWikiUsersBaseUserMappingDotPm      
TWikiDotPm      
TWikiUISaveDotPm      
TWikiMetaDotPm      
TWikiConfigureUIsEXTENDDotPm      
TWikiLineIteratorDotPm      
TWikiIfOP_iswebDotPm      
TWikiTemplatesDotPm      
TWikiIfNodeDotPm      
TWikiResponseDotPm      
TWikiQueryNodeDotPm      
TWikiUsersTWikiUserMappingDotPm      
TWikiUsersPasswordDotPm      
TWikiNetHTTPResponseDotPm      
TWikiInfixParserDotPm      
TWikiUICopyDotPm      
TWikiUIViewDotPm      
TWikiInfixNodeDotPm      
TWikiAccessControlExceptionDotPm      
TWikiLoginManagerDotPm      
TWikiUIChangeFormDotPm      
TWikiOopsExceptionDotPm      
TWikiUIRestDotPm      
TWikiUIUploadDotPm      
TWikiI18NDotPm      
TWikiEngineDotPm      
TWikiFormDotPm      
TWikiStoreRcsWrapDotPm      
TWikiConfigureCheckersCertificateKeyCheckerDotPm      
TWikiStoreSearchAlgorithmsForkingDotPm      
TWikiUIMdrepoUIDotPm      
TWikiUIRDiffDotPm      
TWikiAttrsDotPm      
TWikiAttachDotPm      
TWikiRenderDotPm      
TWikiEngineExceptionDotPm      
WebLeftBarLogin TWikiContributor 1970-01-01 - 01:00 6
MacrosPlugin      
TWikiMergeDotPm      
TWikiFormListFieldDefinitionDotPm      
TWikiSearchDotPm      
TWikiUISearchDotPm      
TWikiNetDotPm      
TWikiCompatibilityDotPm      
TWikiSandboxDotPm      
TWikiI18NExtractDotPm      
TWikiFuncDotPm      
TWikiFormFieldDefinitionDotPm      
TWikiConfigureImgToolDotPm      
TWikiUserMappingDotPm      
TWikiAggregateIteratorDotPm      
TWikiUIDotPm      
TWikiIfParserDotPm      
SourceCode      
TWikiUIRegisterDotPm      
TWikiPluginsDotPm      
TWikiConfigureLoadDotPm      
TWikiMdrepoDotPm      
TWikiLoginManagerSessionDotPm      
WebLeftBarSearch      
TWikiConfigureCheckersCertificateDotPm      
TWikiPrefsDotPm      
TWikiStoreSearchAlgorithmsPurePerlDotPm      
TWikiListIteratorDotPm      
TWikiStoreRcsLiteDotPm      
TWikiStoreQueryAlgorithmsBruteForceDotPm      
TWikiUsersDotPm      
TWikiUIEditDotPm      
LdapContribAdminPlugin      
TWikiFormSelectDotPm      
TWikiRequestDotPm      
TWikiStoreRcsFileDotPm      
TWikiPrefsParserDotPm      
TWikiQueryParserDotPm      
TWikiUsersApacheHtpasswdUserDotPm      
TWikiTimeDotPm      
TWikiInfixErrorDotPm      
TWikiLoginManagerTemplateLoginDotPm      
TWikiUsersHtPasswdUserDotPm      
TWikiStoreDotPm      
TWikiPrefsPrefsCacheDotPm      
TWikiPluralsDotPm      
TWikiAccessDotPm      
TWikiPluginDotPm      
TWikiUIManageDotPm      
TWikiUIStatisticsDotPm      
TWikiUIOopsDotPm      
TWikiLoginManagerApacheLoginDotPm      
TWikiQueryHoistREsDotPm      
TWikiUsersBaseUserMappingDotPm      
TWikiDotPm      
TWikiUISaveDotPm      
TWikiMetaDotPm      
TWikiConfigureUIsEXTENDDotPm      
TWikiLineIteratorDotPm      
TWikiIfOP_iswebDotPm      
TWikiTemplatesDotPm      

Note: If you don't see any output, then there are no files newer than 7 days. Rows without entries in all but the first field are due to incorrect topics present in the TWiki web (no topic info line, thus we cannot find date, author, rev).

Embedding search forms to return a formatted result

Use an HTML form and an embedded formatted search on the same topic. You can link them together with an %URLPARAM{"..."}% variable. Example:

Write this: 

<form action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
Find Topics: 
<input type="text" name="q" size="32" value="%URLPARAM{"q"}%" />
<input type="submit" value="Search" />
</form>
Result:
%FORMQUERY{name="q1" search="text=~''" web="TWiki"}%
%SHOWQUERY{query="q1" limit="7" format="   * $web.$topic: %BR% $summary" }%

To get this:

Find Topics:

Result (first 7):

  • WebLeftBarLogin:
    `
  • SimultaneousEdits:
    FAQ: What happens if two of us try to edit the same topic simultaneously? Answer: TWiki allows multiple simultaneous edits of the same topic, and then merges the...
  • WhatIsWikiWiki:
    FAQ: So what is this WikiWiki thing exactly? Answer: A set of pages of information that are open and free for anyone to edit as they wish. They are stored in...
  • SearchDoesNotWork:
    FAQ: I`ve problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it`s the same problem. Answer: That is an indication...
  • WebBottomBar:
  • FileAttribute:
    Each FileAttachment in a Topic has an attribute string. At present only the hidden attribute is supported. If the attribute includes h then the attachment is considered...
  • BumpyWord:
    See WikiWord Related Topics: UserDocumentationCategory

Generate a table with embedded calculations

Assume you want to produce a summary of all the large attachments in a topic (where by large we mean any attachment greater than 10k). The table should show topic, the name of the attachment, the file size in k, and the date when the attachment was created.

Write this:

%FORMQUERY{name="all" search="" web="TWiki" extract="attachments"}%
%FORMQUERY{name="big" query="all" search="size>'10240'"}%
%SHOWQUERY{query="big" format="|$_up.web.$_up.name|$name|  $percntCALC{$dollarROUND($dollarEVAL($size / 1024), 1)k}$percnt|$percntCALC{$dollarFORMATTIME($date, $dollarday $dollarmon $dollaryear)}$percnt|"}%

To get this:

EditTablePlugin EditTablePluginCalendarExample.gif 19.2k 12 Dec 2012
ColorPickerPlugin screenshot-edit.png 28.9k 26 Nov 2010
UsingMultipleDisks multiple-disks.png 15.1k 22 Sep 2012
TreeBrowserPlugin dtree.js 12.1k 01 Oct 2006
DatePickerPlugin screenshot.png 21.5k 10 Dec 2012
MovedSkin fullscreen.png 34.3k 17 Dec 2012
MovedSkin screenshot.png 46.1k 17 Dec 2012
FormPlugin screenshot_validation_example.png 23.1k 14 May 2007
FormPlugin form_on_submit_diagram.png 54.3k 12 May 2007
TWikiSheetPlugin screenshot.png 27.8k 26 Mar 2016
TWikiSheetPlugin screenshot-classic.png 29.2k 03 Apr 2016
TWikiSheetPlugin screenshot-toggle.png 28.2k 03 Apr 2016
BackupRestorePlugin backup-console-overview.png 60.7k 15 Aug 2011
BackupRestorePlugin backup-console-detail.png 98.3k 05 Sep 2011
SyntaxHighlightingPlugin cpp-screenshot.png 45.3k 14 Feb 2013
SyntaxHighlightingPlugin cpp-screenshot-300.png 39.8k 14 Feb 2013
PatternSkinGraphics bg_button_16x16_generic.psd 41.5k 10 Jul 2007
PatternSkinGraphics bg_button_small_gradient.psd 44.6k 07 Jul 2007
PatternSkinGraphics bg_buttoncancel_gradient.psd 47.2k 10 Jul 2007
PatternSkinGraphics bg_sidebar_reflection.psd 39.8k 13 Jul 2007
PatternSkinGraphics button_arrow.psd 48.2k 11 Jul 2007
PatternSkinGraphics border_sidebar_personal.psd 30.4k 07 Jul 2007
PatternSkinGraphics button_font_selector.psd 200.4k 11 Jul 2007
PatternSkinGraphics bg_action_gradient.psd 32.4k 13 Jul 2007
PatternSkinGraphics bg_button_gradient.psd 45.8k 07 Jul 2007
PatternSkinGraphics bg_submit_gradient.psd 45.8k 05 Jul 2007
PatternSkinGraphics bg_outer_gradient.psd 40.9k 13 Jul 2007
PatternSkinGraphics TWiki_header.psd 415.5k 27 Jun 2007
UserReports business-card-example.png 41.9k 03 Jun 2012
UserReports faded-bubble.png 12.7k 07 Feb 2013
UserReports small-box-example.png 27.6k 28 Jul 2012
UserReports slim-box-example.png 16.5k 28 Jul 2012
UserReports select-users-example.png 30.1k 28 Jul 2012
JSCalendarContrib screenshot-small.png 21.8k 03 Dec 2010
JSCalendarContrib screenshot.png 20.4k 03 Dec 2010
TWikiForms screenshot-combobox.png 11.7k 27 Dec 2012
TinyMCEPlugin screenshot.png 63.2k 19 Sep 2013
TWikiDashboardAddOn dashboard-dimensions.png 167.8k 06 Oct 2012
TWikiDashboardAddOn dashboard-example.png 243.2k 06 Oct 2012
TWikiDashboardAddOn dashboard-example-300.png 37.9k 06 Oct 2012
CsvToTWikiAddOn import-diagram.png 96k 31 Oct 2014
MetadataRepository site-mirroring.png 16.2k 14 Jun 2012
ActionTrackerPlugin Screenshot.png 21k 05 Mar 2013
PlainSkin fullscreen.gif 20.6k 26 Jul 2004
TopMenuSkin fullscreen.png 106.6k 06 Sep 2012
TopMenuSkin screenshot.png 29.6k 06 Sep 2012
PatternSkinCss CSS_element_layout_view.pattern.tmpl.png 36.5k 16 Aug 2004
WatchlistPlugin watchlist-changes-300.png 72.5k 04 Mar 2013
WatchlistPlugin watchlist-topics.png 43.8k 04 Mar 2013
WatchlistPlugin watchlist-changes.png 69.3k 04 Mar 2013
WatchlistPlugin watchlist-preferences.png 25.8k 04 Mar 2013
WatchlistPlugin watchlist-profile.png 159.5k 05 Mar 2013
TWikiJavascripts twiki.js 18.2k 24 Jun 2010
TWikiJavascripts twikiuiToggle.js 11.3k 24 Jun 2010
TWikiJavascripts unicode_chars.js 10.4k 24 Jun 2010
PrintSkin fullscreen.gif 12.7k 27 Jul 2004
AutoSectionsPlugin autosections-demo.png 62.7k 10 Jun 2013
AutoSectionsPlugin autosections-editing.png 46.5k 26 Aug 2013
JqPlotPlugin chart1.png 20.6k 14 Nov 2012
TagMePlugin topictags_styleblog.gif 12.4k 27 Aug 2008
TagMePlugin topictags_styleblog_open.gif 21.7k 27 Aug 2008
TagMePlugin buttons_gradient.psd 40.7k 07 Mar 2006
TWikiAccessControl access-denied.png 32k 24 Apr 2013
TWikiDashboardImages above-silicon-valley.jpg 52.4k 13 Oct 2012
TWikiDashboardImages all-hands-meeting.jpg 51.3k 13 Feb 2013
TWikiDashboardImages autumn-leaves.jpg 61.1k 22 Nov 2012
TWikiDashboardImages baergli-swiss-alps.jpg 49.7k 13 Oct 2012
TWikiDashboardImages barns-in-winter.jpg 46.7k 01 Feb 2013
TWikiDashboardImages baseball-game.jpg 81.7k 22 Nov 2012
TWikiDashboardImages bay-night-colors.jpg 62.5k 18 Nov 2012
TWikiDashboardImages brainstorming-meeting.jpg 49.7k 13 Feb 2013
TWikiDashboardImages brainstorm-session.jpg 62.3k 02 Feb 2013
TWikiDashboardImages boarding-swiss.jpg 61.3k 01 Feb 2013
TWikiDashboardImages boeing-factory.jpg 53.9k 13 Oct 2012
TWikiDashboardImages boreal-by-night.jpg 37.1k 13 Oct 2012
TWikiDashboardImages bubbling-blob.gif 249.5k 27 Dec 2012
TWikiDashboardImages cern-atlas-construction.jpg 85.6k 05 Dec 2012
TWikiDashboardImages cern-atlas-detector.jpg 76k 05 Dec 2012
TWikiDashboardImages cern-cms-cavern.jpg 75.9k 05 Dec 2012
TWikiDashboardImages cern-control-room.jpg 65.1k 05 Dec 2012
TWikiDashboardImages cern-datacenter.jpg 81.9k 05 Dec 2012
TWikiDashboardImages cern-lhc-tunnel.jpg 67.5k 05 Dec 2012
TWikiDashboardImages chur-by-night.jpg 59.5k 01 Feb 2013
TWikiDashboardImages code-camp.jpg 122k 13 Oct 2012
TWikiDashboardImages color-patterns.jpg 78k 02 Feb 2013
TWikiDashboardImages community-leaders.jpg 89.7k 14 Oct 2012
TWikiDashboardImages community-team.jpg 50.6k 13 Feb 2013
TWikiDashboardImages computer-cables.jpg 80.8k 05 Dec 2012
TWikiDashboardImages computer-wires.jpg 56.9k 05 Dec 2012
TWikiDashboardImages conference-room.jpg 74.1k 02 Feb 2013
TWikiDashboardImages conference-session.jpg 66k 02 Feb 2013
TWikiDashboardImages conference-talk.jpg 69.2k 02 Feb 2013
TWikiDashboardImages cubicle-panorama.jpg 55.9k 19 Nov 2012
TWikiDashboardImages datacenter-desk.jpg 85.5k 05 Dec 2012
TWikiDashboardImages datacenter-racks.jpg 72.7k 05 Dec 2012
TWikiDashboardImages dawn-blue.jpg 39.2k 27 Dec 2012
TWikiDashboardImages design-boards.jpg 44k 13 Feb 2013
TWikiDashboardImages empire-state.jpg 81.8k 27 Apr 2013
TWikiDashboardImages endeavour-cockpit.jpg 87k 13 Feb 2013
TWikiDashboardImages ferries-wheel-light.jpg 59.5k 27 Apr 2013
TWikiDashboardImages flute-cave.jpg 90k 22 Nov 2012
TWikiDashboardImages glacier-express.jpg 67.6k 01 Feb 2013
TWikiDashboardImages gold-dagger.jpg 94k 06 Apr 2013
TWikiDashboardImages golden-gate-dawn.jpg 56.4k 13 Oct 2012
TWikiDashboardImages golden-gate-sunrise.jpg 35k 18 Nov 2012
TWikiDashboardImages golden-gate-sunset.jpg 35.6k 02 Oct 2012
TWikiDashboardImages grand-central.jpg 69.2k 27 Apr 2013
TWikiDashboardImages hakone-garden.jpg 81k 02 Oct 2012
TWikiDashboardImages hong-kong-skyline.jpg 72.3k 13 Oct 2012
TWikiDashboardImages lake-tahoe-blue.jpg 56.8k 06 Apr 2013
TWikiDashboardImages lake-tahoe-lakes.jpg 71.1k 06 Apr 2013
TWikiDashboardImages lake-tahoe-winter.jpg 65.4k 06 Apr 2013
TWikiDashboardImages lecture-room.jpg 83.1k 02 Feb 2013
TWikiDashboardImages marin-headlands.jpg 33.5k 02 Oct 2012
TWikiDashboardImages meeting.jpg 66.1k 02 Feb 2013
TWikiDashboardImages merz-bakery.jpg 80.6k 01 Feb 2013
TWikiDashboardImages moonlight-over-city.jpg 53k 27 Dec 2012
TWikiDashboardImages monterey-by-bike.jpg 50.1k 13 Oct 2012
TWikiDashboardImages museum-ceiling.jpg 71.6k 06 Apr 2013
TWikiDashboardImages nasa-airfield.jpg 72.1k 16 Aug 2013
TWikiDashboardImages nasa-shed-orange.jpg 101.4k 02 Oct 2012
TWikiDashboardImages new-years-eve.jpg 76.7k 07 Jan 2013
TWikiDashboardImages new-york-buildings.jpg 105.1k 27 Apr 2013
TWikiDashboardImages new-york-cabs.jpg 97.7k 27 Apr 2013
TWikiDashboardImages new-york-colors.jpg 43.6k 27 Apr 2013
TWikiDashboardImages new-york-highrises.jpg 99.3k 27 Apr 2013
TWikiDashboardImages new-york-sky.jpg 74.2k 27 Apr 2013
TWikiDashboardImages niagara-falls.jpg 60k 02 Nov 2012
TWikiDashboardImages picture-gallery.jpg 44.5k 19 Nov 2012
TWikiDashboardImages rio-de-janeiro.jpg 66.5k 02 Nov 2012
TWikiDashboardImages river-pebbles.jpg 76.9k 27 Dec 2012
TWikiDashboardImages sakura-and-bee.jpg 48k 06 Apr 2013
TWikiDashboardImages sakura-garden.jpg 112.7k 06 Apr 2013
TWikiDashboardImages sakura-trees.jpg 111.7k 06 Apr 2013
TWikiDashboardImages salt-flats.jpg 50.5k 27 Apr 2013
TWikiDashboardImages san-francisco-airport.jpg 67.1k 18 Nov 2012
TWikiDashboardImages san-francisco-cityscape.jpg 49.7k 02 Nov 2012
TWikiDashboardImages san-francisco-skyline.jpg 57.9k 27 Dec 2012
TWikiDashboardImages saratoga-evening.jpg 48.3k 13 Oct 2012
TWikiDashboardImages seasons-greetings.jpg 81.5k 27 Dec 2012
TWikiDashboardImages shanghai-by-night.jpg 96.1k 16 Jul 2013
TWikiDashboardImages sierra-nevada.jpg 61.6k 27 Apr 2013
TWikiDashboardImages silicon-valley-colors.jpg 53.4k 27 Apr 2013
TWikiDashboardImages silicon-valley-night.jpg 60.7k 27 Apr 2013
TWikiDashboardImages subway-station.jpg 65.2k 27 Apr 2013
TWikiDashboardImages silicon-valley-sunrise.jpg 43k 06 Nov 2012
TWikiDashboardImages solar-flare.jpg 50.3k 22 Nov 2012
TWikiDashboardImages solar-surface.jpg 39.8k 22 Nov 2012
TWikiDashboardImages sports-shoes.jpg 81.9k 01 Feb 2013
TWikiDashboardImages stadelhofen-station.jpg 56.9k 01 Feb 2013
TWikiDashboardImages summit-panorama.jpg 44.9k 02 Feb 2013
TWikiDashboardImages sunrise-colors.jpg 44.3k 27 Dec 2012
TWikiDashboardImages swiss-castle.jpg 63.9k 28 Nov 2012
TWikiDashboardImages swiss-chalet.jpg 74k 01 Feb 2013
TWikiDashboardImages sydney-harbour-bridge.jpg 53k 02 Nov 2012
TWikiDashboardImages teamwork-amish.jpg 66.3k 04 Feb 2013
TWikiDashboardImages teamwork-office.jpg 59.9k 04 Feb 2013
TWikiDashboardImages teamwork-patrouille-suisse.jpg 26.1k 04 Feb 2013
TWikiDashboardImages terra-cotta-warriors.jpg 38.1k 06 Apr 2013
TWikiDashboardImages tokyo-roppongi-district.jpg 99.7k 07 Jan 2013
TWikiDashboardImages tokyo-roppongi-hill.jpg 100k 07 Jan 2013
TWikiDashboardImages tokyo-skyline.jpg 57.6k 07 Jan 2013
TWikiDashboardImages venetian-macau.jpg 63.9k 02 Oct 2012
TWikiDashboardImages venice-grand-canal.jpg 58k 02 Nov 2012
TWikiDashboardImages wine-tasting.jpg 67.3k 13 Oct 2012
TWikiDashboardImages wood-floor.jpg 81.5k 27 Apr 2013
TWikiDashboardImages workplace.jpg 68.3k 02 Feb 2013
TWikiDashboardImages zurich-at-dawn.jpg 66.9k 29 Nov 2012
ScrollBoxAddOn Dsc08566.jpg 27.2k 23 Dec 2010
ScrollBoxAddOn Dsc08581.jpg 27k 23 Dec 2010
ScrollBoxAddOn Dsc08580.jpg 27k 23 Dec 2010
ScrollBoxAddOn Dsc08567.jpg 27k 23 Dec 2010 

<--
One line description, shown in the TextFormattingRules topic: 
    

  •  Set SHORTDESCRIPTION = Provides query capabilities across a database defined using forms and embedded tables in TWiki topics. 

 
-->

Topic Relations

Topic relations are defined by setting the FORMQUERYPLUGIN_RELATIONS variable in the WebPreferences topic of the web to be processed. This defines a semicolon-separated list of rules for deriving relationships between topics using common portions of names. This is best illustrated by an example. Let's say we set FORMQUERYPLUGIN_RELATIONS to be: 
ReQ%Ax%B SubReq ReQ%A; TiT%An%B TestItem ReQ%A
This describes two rules, the first of which says "Any topic named "ReQ<something>x<something>" is a SubReq of another topic called "ReQ<something>". Single upper case characters with a preceding percent sign are used to define the <something>s. So, in this example, ReQ1456 has the SubReq relation to ReQ1456x7. The reverse relation is also inserted, but appending _of to the relation name, so ReQ1456x7 has the SubReq_of relation to ReQ1456.

Obviously a single topic may have many topics that have the same relation to it (i.e. they are one-to-many), so forward relations are stored as arrays in the maps that represent topics. Reverse relations are many_to_one so they are stored as a simple field in the other topic. Relations are stored as pointers to the maps of the other topic so they can't be printed as if they were simple names. Instead you have to use them to refer to fields within the other topic. For example, in a %SHOWQUERY showing ReQReQ1456x7 you can't refer simply to $SubReq_of to get ReQ1456 (the name of the related topic); you have to use $SubReq_of.topic instead.

The default value of FORMQUERYPLUGIN_RELATIONS is none.

Tables

Tables to be read into the database must use the EditTablePlugin 'include= topic ' feature (or the EditTablerow 'template= topic ' feature), which define the format of the tables in another topic. Tables to be read are defined by setting the FORMQUERYPLUGIN_TABLES variable in the WebPreferences topic of the web. This is a list of the names of the topics that EditTablePlugin or EditTablerowPlugin use to find the table formats. Tables are read in as arrays of maps, with each map keyed on a field name generated by stripping all non-alphabetic characters from the column header. Note that the column header where the table is defined is used, not the column header in the EditTable include= topic. If the FORMQUERYPLUGIN_TABLES variable is set to All (case-insensitive), then any valid table is added to the database.

The defaut is to load all tables:

  • Set TABLES = all

Two special map entries are added to each table row, topic and the equivalent of the reverse relation described above, represented by _up. So if you load a table type "CookingTimes", each row will have topic set to the name of the topic it was loaded from and _up set to the map of that topic. This allows you to refer to the fields of the topic that contains a table even after the table has been extracted.

When a table contains calculations using TWiki:Plugins.SpreadSheetPlugin, these are applied before the map entries are created for this table. These calculations must not refer to data outside of the table.

If there are multiple EDITTABLE calls with the same table type, all the table data is concatenated into a single table.

The current value of FORMQUERYPLUGIN_TABLES is all.

For example, let's say we have a table in a topic called TableDefinition, like this:

Name Description

Now, in another topic, TableUse, we have 

%EDITTABLE{include="TableDefinition"}%
| Cat | Small furry animal |
...
%EDITTABLE{include="TableDefinition"}%
| Dog | Latch used to seal a hatch on a ship |
In this case, $TableDefinition.0.Name is Cat, $TableDefinition.1.Name is Dog.

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

  • If you have TWiki 4.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • If you have any problems, then you can still install manually from the command-line:
    1. Download one of the .zip or .tgz archives
    2. Unpack the archive in the root directory of your TWiki installation.
    3. Run the installer script ( perl <module>_installer )
    4. Run configure and enable the module, if it is a plugin.
    5. Repeat for any missing dependencies.
  • If you are still having problems, then instead of running the installer script:
    1. Make sure that the file permissions allow the webserver user to access all files.
    2. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
    3. Manually edit LocalSite.cfg to set any configuration variables.

  • The variable %FORMQUERYPLUGIN_ENABLE% must be set either globally or in the web where you want to use it. If the plugin is enabled globally (on all webs), this may have an unwelcome performance impact, as the plugin may create a cache of topics in a web where it is not intended to be used. To enable the plugin for selected webs only, put the following line into the WebPreferences topic of the web you want to enable it on: 
      * Set FORMQUERYPLUGIN_ENABLE = 1

Plugin Info

Plugin Author: TWiki:Main/CrawfordCurrie, TWiki:Main/ThomasWeigert
Plugin Version: 15561 (12 Dec 2008)
Change History:  
21 May 2007 Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
24 Apr 2007 (13527) Merge YetAnotherFormQueryPlugin back in. Fixed a lot. Prepared for use with TWiki 4.2.
04 Sep 2006 Expand calculations using TWiki:Plugins.FormQueryPlugin.
23 Jun 2006 Ported to Dakar.
9 Jul 2005 Added support for tables defined using TWiki:Plugins/EditTablerowPlugin
  Added support for searches over multiple webs
  Support %MATCHCOUNT%
  Allow TWiki:Plugins/SpreadSheetPlugin computation to be applied to the result of a query
  Made "moan" a preference rather than a per call option
  Removed %TOPICCREATOR%
  Removed %ARITHMETIC% (as one can use the TWiki:Plugins/SpreadSheetPlugin)
  Removed the color map feature
  Extended %FQPINFO% to support showing results of queries
  Integrate the Attribute parser from TWiki:Codev/DakarRelease
  Add caseinsensitivity as option
  Handle one line at a time so that query memory can be reused in another query
  Added the special variables supported by FormattedSearch
  Changed some of the option names to be more consistent with TWikiSearch (e.g., row_count)
  More flexibility for using tables
  Add a %DOANDSHOWQUERY% tag
  Support embedding of %SEARCH% and %FORMQUERY% in the format option to allow searches and queries to be applied to the result of a query (a poor man's intersection)
  Added option to switch on/off "Undefined" messages for undefined field values
  Expanded fields no longer have spaces around them. This is more correct, but requires care in format definitions.
16 Jul 2004 Split into sub-components
02 Apr 2004 TWiki:Main/SimonHardyFrancis bugfixes incorporated. TWiki:Main/TimSlidel patches incoporated for mod_perl, autocreate, and collapsing same-type tables in a single topic
05 Feb 2004 Bugfix version
11 Jul 2003 Initial version
TWiki Dependencies: TWiki:Plugins.SpreadSheetPlugin
Dependencies:
NameVersionDescription
TWiki::Contrib::DBCacheContrib>=1.001Required. Download and install from the TWiki:Plugins/DBCacheContrib code library.
Time::ParseDateRequired. Available from CPAN.
Storable>=2.072.13 recommended; accelerates cache handling. Available from CPAN
TWiki::Plugins::MacrosPlugin>=1.000Recommended; used for parameterised includes. Download from TWiki:Plugins/MacrosPlugin repository.
Perl Version: 5.0
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/FormQueryPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/FormQueryPluginDev
Demo URL: http://www.owiki.org/FQP/

Copyright

This code is based on an original development of Motorola Inc. and is protected by the following copyrights:

  • Copyright © 2002-2003, 2005 Motorola. All Rights Reserved.
  • Copyright © 2004. Crawford Currie http://www.c-dot.co.uk

Extending or customising

Extension or customisation is welcome, as long as all extensions are described and code provided back to the author.

The module is shipped with a perl build file, which should be used for installation and testing. Testing is done using Test::Unit, and is invoked using the 'test' build target. Writing tests is a useful way of feeding back bugs as well. I can't encourage you enough to maintain and extend the tests!

License

As required for the publication of all extensions to TWiki, this software is published under the terms of the GNU General Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, published at http://www.gnu.org/copyleft/gpl.html

-- TWiki:Main/ThomasWeigert - 04 Sep 2006 

<-- Do not attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Dev topic instead. -->
View topic | History: r1 | More topic actions...
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding ARC TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.FormQueryPlugin.