|
|
| Changed: |
<
< |
Inline search feature allows flexible formatting of search result
By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).
Two paramters can be used to specify a customized search result:
1. header="..." parameter
Use the header paramter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. I.e.
header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format paramter to specify the format of one search hit. I.e.
format="| $topic | $summary |"
Variables that can be used in the format string:
| Name: | Expands To: |
|---|
$n | New line |
$web | Name of the web |
$topic | Topic name |
$locked | LOCKED flag (if any) |
$date | Time stamp of last topic update, i.e. 09 Jan 2009 - 21:02 |
$isodate | Time stamp of last topic update, i.e. 2009-01-09T21:02Z |
$rev | Number of last topic revision, i.e. 1.4 |
$wikiusername | Wiki user name of last topic update, i.e. Main.JohnSmith |
$username | User name of last topic update, i.e. JohnSmith |
$summary | Topic summary |
$formfield(name) | The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm |
$pattern(reg-exp) | A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: .... |
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
Write this:
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
- Topic: Summary:
- TWikiFAQ: Frequently Asked Questions About Tharsis This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
- TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
- TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Write this in the Know web:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Write this:
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%
To get this:
TWiki FAQs:
- How do I delete or rename a topic? Answer...
- Why does the topic revision not increase when I edit a topic? Answer...
- TWiki has a GPL (GNU General Public License). What is GPL? 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...
- What happens if two of us try to edit the same topic simultaneously? Answer...
- I would like to install TWiki on my server. Can I get the source? Answer...
- So what is this WikiWiki thing exactly? Answer...
- Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
-- PeterThoeny - 28 Nov 2001
|
>
> |
Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file.
Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.
File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.
- You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using; create a central reference library that's easy to access and manage by an entire user group.
- For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!
- Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
- NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.
- To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table.
- Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex:
*.php files are renamed to *.php.txt.
- Currently there is no file size limit besides the disk space on the server.
- The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.
- NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.
An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.
It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.
- To reference an attachment located in another topic, write text:
-
%PUBURL%/%WEB%/OtherTopic/Sample.txt (for the same web)
-
%PUBURL%/Otherweb/OtherTopic/Sample.txt (for adifferent web)
- Attached HTML files and text files can be inlined in a topic. Example:
- Attach file:
Sample.txt
- Edit topic and write text:
%INCLUDE{"%ATTACHURL%/Sample.txt"}%
- GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
- Attach file:
Smile.gif
- Edit topic and write text:
%ATTACHURL%/Smile.gif
- Preview - text appears as
 , an image.
Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.
Clicking on an Action link takes you to a new page that looks like this:
- The first table is a list of all attachments, including their attributes. An
h means the attachment is hidden, it isn't listed when viewing a topic.
- The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
- To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
- To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.
- Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
|
| Deleted: |
<
< |
Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file.
Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.
File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.
- You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using; create a central reference library that's easy to access and manage by an entire user group.
- For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!
- Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
- NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.
- To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table.
- Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex:
*.php files are renamed to *.php.txt.
- Currently there is no file size limit besides the disk space on the server.
- The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.
- NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.
An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.
It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.
- To reference an attachment located in another topic, write text:
-
%PUBURL%/%WEB%/OtherTopic/Sample.txt (for the same web)
-
%PUBURL%/Otherweb/OtherTopic/Sample.txt (for adifferent web)
- Attached HTML files and text files can be inlined in a topic. Example:
- Attach file:
Sample.txt
- Edit topic and write text:
%INCLUDE{"%ATTACHURL%/Sample.txt"}%
- GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
- Attach file:
Smile.gif
- Edit topic and write text:
%ATTACHURL%/Smile.gif
- Preview - text appears as , an image.
Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.
Clicking on an Action link takes you to a new page that looks like this:
- The first table is a list of all attachments, including their attributes. An
h means the attachment is hidden, it isn't listed when viewing a topic.
- The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
- To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
- To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.
- Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
|
| Added: |
>
> |
Inline search feature allows flexible formatting of search result
By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).
Two paramters can be used to specify a customized search result:
1. header="..." parameter
Use the header paramter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. I.e.
header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format paramter to specify the format of one search hit. I.e.
format="| $topic | $summary |"
Variables that can be used in the format string:
| Name: | Expands To: |
|---|
$n | New line |
$web | Name of the web |
$topic | Topic name |
$locked | LOCKED flag (if any) |
$date | Time stamp of last topic update, i.e. 09 Jan 2009 - 21:02 |
$isodate | Time stamp of last topic update, i.e. 2009-01-09T21:02Z |
$rev | Number of last topic revision, i.e. 1.4 |
$wikiusername | Wiki user name of last topic update, i.e. Main.JohnSmith |
$username | User name of last topic update, i.e. JohnSmith |
$summary | Topic summary |
$formfield(name) | The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm |
$pattern(reg-exp) | A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: .... |
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
Write this:
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
- Topic: Summary:
- TWikiFAQ: Frequently Asked Questions About Tharsis This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
- TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
- TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Write this in the Know web:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Write this:
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%
To get this:
TWiki FAQs:
- How do I delete or rename a topic? Answer...
- Why does the topic revision not increase when I edit a topic? Answer...
- TWiki has a GPL (GNU General Public License). What is GPL? 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...
- What happens if two of us try to edit the same topic simultaneously? Answer...
- I would like to install TWiki on my server. Can I get the source? Answer...
- So what is this WikiWiki thing exactly? Answer...
- Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
-- PeterThoeny - 28 Nov 2001
Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs
TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
- Format is the same as in TWikiVariables, except all fields have a key.
-
%META:<type>{key1="value1" key2="value2" ...}%
- Order of fields within the meta variables is not defined, except that if there is a field with key
name, this appears first for easier searching (note the order of the variables themselves is defined).
- Each meta variable is on one line.
-
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
The current version of Meta Data is 1.0, with support for the following variables.
META:TOPICINFO
| Key | Comment |
|---|
| version | Same as RCS version |
| date | integer, unx time, seconds since start 1970 |
| author | last to change topic, is the REMOTE_USER |
| format | Format of this topic, will be used for automatic format conversion |
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
| Key | Comment |
|---|
| from | Full name i.e. web.topic |
| to | Full name i.e. web.topic |
| by | Who did it, is the REMOTE_USER, not WikiName |
| date | integer, unx time, seconds since start 1970 |
Notes:
- at present version number is not supported directly, it can be inferred from the RCS history.
- there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
META:TOPICPARENT
| Key | Comment |
|---|
| name | The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed. |
META:FILEATTACHMENT
| Key | Comment |
|---|
| name | Name of file, no path. Must be unique within topic |
| version | Same as RCS revision |
| path | Full path file was loaded from |
| size | In bytes |
| date | integer, unx time, seconds since start 1970 |
| user | the REMOTE_USER, not WikiName |
| comment | As supplied when file uploaded |
| attr | h if hidden, optional |
Extra fields that are added if an attachment is moved:
| Key | Comment |
|---|
| movedfrom | full topic name - web.topic |
| movedby | the REMOTE_USER, not WikiName |
| movedto | full topic name - web.topic |
| moveddate | integer, unx time, seconds since start 1970 |
META:FORM
| Key | Comment |
|---|
| name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name i.e. web.topic, but doesn't normally |
META:FIELD
Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.
| Key | Name |
|---|
| name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
| title | Full text from TWikiForms template |
| value | Value user has supplied via form |
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
- form fields remain in the order they are defined
- the
diff function output appears in a logical order
The recommended sequence is:
- META:TOPICINFO
-
text of topic
- META:TOPICMOVED (optional)
- META:TOPICPARENT (optional)
- META:FILEATTACHMENT (0 or more entries)
- META:FORM (optional)
- META:FIELD (0 or more entries; FORM required)
When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic
Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.
Current support covers:
| Variable usage: | Comment: |
|---|
| %META{"form"}% | Show form data, see TWikiForms |
| %META{"attachments"}% | Show attachments, exclude hidden |
| Options for Attachments: | |
| all="on" | Show ALL attachments (including hidden) |
| %META{"moved"}% | Details of any topic moves |
| %META{"parent [options]"}% | Show topic parent |
| Options for parent: | |
| dontrecurse="on" | By default recurses up tree, at some cost |
| prefix="..." | Prefix for parents, only if there are parents; default "" |
| suffix="..." | Suffix, only appears if there are parents; default "" |
| separator="..." | Separator between parents, default is " > " |
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.
-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001
|
| Deleted: |
<
< |
Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs
TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
- Format is the same as in TWikiVariables, except all fields have a key.
-
%META:<type>{key1="value1" key2="value2" ...}%
- Order of fields within the meta variables is not defined, except that if there is a field with key
name, this appears first for easier searching (note the order of the variables themselves is defined).
- Each meta variable is on one line.
-
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
The current version of Meta Data is 1.0, with support for the following variables.
META:TOPICINFO
| Key | Comment |
|---|
| version | Same as RCS version |
| date | integer, unx time, seconds since start 1970 |
| author | last to change topic, is the REMOTE_USER |
| format | Format of this topic, will be used for automatic format conversion |
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
| Key | Comment |
|---|
| from | Full name i.e. web.topic |
| to | Full name i.e. web.topic |
| by | Who did it, is the REMOTE_USER, not WikiName |
| date | integer, unx time, seconds since start 1970 |
Notes:
- at present version number is not supported directly, it can be inferred from the RCS history.
- there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
META:TOPICPARENT
| Key | Comment |
|---|
| name | The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed. |
META:FILEATTACHMENT
| Key | Comment |
|---|
| name | Name of file, no path. Must be unique within topic |
| version | Same as RCS revision |
| path | Full path file was loaded from |
| size | In bytes |
| date | integer, unx time, seconds since start 1970 |
| user | the REMOTE_USER, not WikiName |
| comment | As supplied when file uploaded |
| attr | h if hidden, optional |
Extra fields that are added if an attachment is moved:
| Key | Comment |
|---|
| movedfrom | full topic name - web.topic |
| movedby | the REMOTE_USER, not WikiName |
| movedto | full topic name - web.topic |
| moveddate | integer, unx time, seconds since start 1970 |
META:FORM
| Key | Comment |
|---|
| name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name i.e. web.topic, but doesn't normally |
META:FIELD
Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.
| Key | Name |
|---|
| name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
| title | Full text from TWikiForms template |
| value | Value user has supplied via form |
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
- form fields remain in the order they are defined
- the
diff function output appears in a logical order
The recommended sequence is:
- META:TOPICINFO
-
text of topic
- META:TOPICMOVED (optional)
- META:TOPICPARENT (optional)
- META:FILEATTACHMENT (0 or more entries)
- META:FORM (optional)
- META:FIELD (0 or more entries; FORM required)
When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic
Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.
Current support covers:
| Variable usage: | Comment: |
|---|
| %META{"form"}% | Show form data, see TWikiForms |
| %META{"attachments"}% | Show attachments, exclude hidden |
| Options for Attachments: | |
| all="on" | Show ALL attachments (including hidden) |
| %META{"moved"}% | Details of any topic moves |
| %META{"parent [options]"}% | Show topic parent |
| Options for parent: | |
| dontrecurse="on" | By default recurses up tree, at some cost |
| prefix="..." | Prefix for parents, only if there are parents; default "" |
| suffix="..." | Suffix, only appears if there are parents; default "" |
| separator="..." | Separator between parents, default is " > " |
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.
-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001
|
|
|
| Changed: |
<
< |
TWiki Reference Manual (01-Sep-2001)
|
>
> |
TWiki Reference Manual (01-Dec-2001)
|
| Changed: |
<
< |
|
>
> |
|
| Changed: |
<
< |
|
>
> |
|
| Changed: |
<
< |
|
>
> |
|
| Changed: |
<
< |
|
>
> |
|
| Changed: |
<
< |
|
>
> |
|
| Changed: |
<
< |
Definition of the templates used to render all HTML pages displayed in TWiki
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
- separates a set of common template parts into a base template that is included by all of the related templates;
- defines common variables, like a standard separator (ex: "|"), in the base template;
- defines variable text in the individual templates and passes it back to the base template.
- Special template directives (or preprocessor commands) are embedded in normal templates.
- Use of template directives is optional, templates work without them.
- All template preprocessing is done in
&TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
- Directives are of the form
%TMPL:<key>% and %TMPL:<key>{"attr"}%.
- Directives:
-
%TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
-
%TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
-
%TMPL:END%: Ends variable definition.
-
%TMPL:P{"var"}%: Prints a previously defined variable.
- Variables are live in a global name space, there is no parameter passing.
- Two-pass processing, so that you can use a variable before declaring it or after.
- Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the
twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
- NOTE: The template directives work only for templates, they do not get processed in topic text.
All common parts are defined in a master template, twiki.tmpl, that all other templates use.
| Template variable: | Defines: |
|---|
| %TMPL:DEF{"sep"}% | "|" separator |
| %TMPL:DEF{"htmldoctype"}% | Start of all HTML pages |
| %TMPL:DEF{"standardheader"}% | Standard header (ex: view, index, seach) |
| %TMPL:DEF{"simpleheader"}% | Simple header with reduced links (ex: edit, attach, oops) |
| %TMPL:DEF{"standardfooter"}% | Footer, excluding revision and copyright parts |
| %TMPL:DEF{"oops"}% | Skeleton of oops dialog |
There are two types of templates:
- HTML Page Templates: Defines layout of Tharsis pages
- Template Topics: Defines default text when you create a new topic
HTML Page Templates
Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.
The template files are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded per web. The following search order applies:
-
twiki/templates/$webName/$scriptName.tmpl
-
twiki/templates/$scriptName.tmpl
Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).
Note: TWikiSkins can be defined to overload the standard templates.
Special variables are used in templates, especially in view, to display meta data.
Template topics define the default text for new topics. There are three types of template topics:
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. The following search order applies when you create a new topic:
- The topic name specified by the
templatetopic CGI parameter.
- WebTopicEditTemplate in the current web.
- WebTopicEditTemplate in the TWiki web.
Here is an example for creating new topics based on a specific template topic:
Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="submit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
The "onlywikiname" parameter enforces WikiWords for topic names.
Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%
Attached is an example of an oops base template oopsbase.tmpl and a example oops dialog oopstest.tmpl which is based on the base template. NOTE: This isn't the release version, just a quick, simple demo.
The first line declares the delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%
%TMPL:DEF{"sep"}% | %TMPL:END%
<html>
<head>
<title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
<base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
<meta name="robots" content="noindex">
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellpadding="3" cellspacing="0">
<tr>
<td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
<a href="%WIKIHOMEURL%">
<img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
</td>
<td>
<b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
<B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
</td>
</tr>
<tr bgcolor="%WEBBGCOLOR%">
<td colspan="2">
%TMPL:P{"webaction"}%
</td>
</tr>
</table>
--- ++ %TMPL:P{"heading"}%
%TMPL:P{"message"}%
<table width="100%" border="0" cellpadding="3" cellspacing="0">
<tr bgcolor="%WEBBGCOLOR%">
<td valign="top">
Topic <b>%TOPIC%</b> . {
%TMPL:P{"topicaction"}%
}
</td>
</tr>
</table>
</body>
|
Each oops template basically just defines some variables and includes the base template that does the layout work.
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
* Some more blah blah blah blah blah blah blah blah blah blah...
* Param1: %PARAM1%
* Param2: %PARAM2%
* Param3: %PARAM3%
* Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%
|
With URL: .../bin/oops/Test/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
- A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template is a structurally complete HTML document with a
.tmpl filename extension - it contains unresolved %VARIABLES%, but can still be previewed directly in a browser.
-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
Skins are customized TWikiTemplates files. You can use skins to change the look of a Tharsis topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.
Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.
A skin can be activated in two ways:
- Add
?skin=name to the URL, for this example:
The ?skin=name URL parameter overrides the SKIN Preference value.
-- PeterThoeny - 14 Jul 2001
|
>
> |
Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all layed out below - refer back to this page in a pop-up window from the Edit screen.
|
Formatting Command:
|
Example: You write:
|
You get:
|
Paragraphs:
Blank lines will create new paragraphs.
|
1st paragraph
2nd paragraph
|
1st paragraph
2nd paragraph
|
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables.
|
---++ Sushi
---+++ Maguro
|
Sushi
Maguro
|
Bold Text:
Words get bold by enclosing them in * asterisks.
|
*Bold*
|
Bold
|
Italic Text:
Words get italic by enclosing them in _ underscores.
|
_Italic_
|
Italic
|
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
|
__Bold italic__
|
Bold italic
|
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
|
=Fixed font=
|
Fixed font
|
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in |
==Bold fixed==
|
Bold fixed
|
Note: Make sure to "stick" the * _ = == signs to the words, e.g. take away spaces.
|
_This works_,
_this not _
|
This works,
_this not _
|
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted.
Note: Each tag must be on a line by itself.
|
<verbatim>
class CatAnimal {
void purr() {
<code here>
}
}
</verbatim>
|
class CatAnimal {
void purr() {
<code here>
}
}
|
Separator:
At least three dashes at the beginning of a line.
|
-------
|
|
List Item:
Three spaces and an asterisk.
|
* bullet item
|
|
Nested List Item:
Six, nine, ... spaces and an asterisk.
|
* nested stuff
|
|
Ordered List:
Three spaces and a number.
|
1 Sushi
1 Dim Sum
|
- Sushi
- Dim Sum
|
Definition List:
Three spaces, the term, a colon, a space, followed by the definition.
Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the non-breaking-space entity.
|
Sushi: Japan
Dim Sum: S.F.
|
- Sushi
- Japan
- Dim Sum
- S.F.
|
Table:
Optional spaces followed by the cells enclosed in vertical bars.
Note: | *bold* | cells are rendered as table headers.
Note: | spaced | cells are rendered center aligned.
Note: | spaced | cells are rendered right aligned.
Note: | 2 colspan || cells are rendered as multi-span columns.
Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
|
| *L* | *C* | *R* |
| A2 | 2 | 2 |
| A3 | 3 | 3 |
| multi span |||
| A4 \ | next \ | next |
|
| L | C | R |
|---|
| A2 | 2 | 2 |
| A3 | 3 | 3 |
| multi span |
| A4 | next | next |
|
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different Tharsis web write Webname.TopicName.
|
WebNotify
Know.ReadmeFirst
|
WebNotify
ReadmeFirst?
|
#SquareBrackets
Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
|
[[wiki syntax]]
[[Main.TWiki users]]
|
wiki syntax
Main.TWiki users
|
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
|
[[WikiSyntax][syntax]]
[[http://gnu.org][GNU]]
|
syntax
GNU
|
Anchors:
You can define a link reference inside a Tharsis topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
|
[[WebHome#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
|
WebHome#NotThere
Jump
To here
|
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
|
<nop>SunOS
|
SunOS
|
Using HTML
You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
HTML and TWiki Usability
- On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit.
-
 NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
TWiki HTML Rendering
- TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
-
 If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
- NOTE: The opening and closing angle brackets -
<...> - of an HTML tag must be on the same line, or the tag will be broken.
- This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character,
<, ex: a > b
- If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
- GoodStyle is a WikiWord that links to the GoodStyle topic located in the current Tharsis web.
- NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
-
http://..., https://..., ftp://... and mailto:...@... are linked automatically.
- Email addresses like
name@domain.com are linked automatically.
Plugins provide additional text formatting capabilities and can extend the functionality of Tharsis into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.
Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:
- DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated
*_text_* as bold italic text.
- InterwikiPlugin: Link
ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
- TWikiDrawPlugin: Drawing editor
Check on current Plugin status and settings for this site in TWikiPreferences.
-- MikeMannix - 02 Dec 2001
|
| Changed: |
<
< |
|
>
> |
|
| Changed: |
<
< |
|
>
> |
Inline search feature allows flexible formatting of search result
By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).
Two paramters can be used to specify a customized search result:
1. header="..." parameter
Use the header paramter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. I.e.
header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format paramter to specify the format of one search hit. I.e.
format="| $topic | $summary |"
Variables that can be used in the format string:
| Name: | Expands To: |
|---|
$n | New line |
$web | Name of the web |
$topic | Topic name |
$locked | LOCKED flag (if any) |
$date | Time stamp of last topic update, i.e. 09 Jan 2009 - 21:02 |
$isodate | Time stamp of last topic update, i.e. 2009-01-09T21:02Z |
$rev | Number of last topic revision, i.e. 1.4 |
$wikiusername | Wiki user name of last topic update, i.e. Main.JohnSmith |
$username | User name of last topic update, i.e. JohnSmith |
$summary | Topic summary |
$formfield(name) | The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm |
$pattern(reg-exp) | A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: .... |
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
Write this:
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
- Topic: Summary:
- TWikiFAQ: Frequently Asked Questions About Tharsis This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
- TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
- TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Write this in the Know web:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Write this:
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%
To get this:
TWiki FAQs:
- How do I delete or rename a topic? Answer...
- Why does the topic revision not increase when I edit a topic? Answer...
- TWiki has a GPL (GNU General Public License). What is GPL? 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...
- What happens if two of us try to edit the same topic simultaneously? Answer...
- I would like to install TWiki on my server. Can I get the source? Answer...
- So what is this WikiWiki thing exactly? Answer...
- Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
-- PeterThoeny - 28 Nov 2001
|
| Changed: |
<
< |
Plug-in enhanced feature add-ons, with a Plugin API for developers
You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:
- add virtually unlimited features while keeping the main TWiki code compact and efficient;
- heavily customize an installation and still do clean updates to new versions of TWiki;
- rapidly develop new TWiki functions in Perl using the Plugin API.
Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.
TWiki comes with three Plugins as part of the standard installation.
- DefaultPlugin optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)
- EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.
- InterwikiPlugin is preinstalled but can be disabled or removed. Use it for shorthand linking to remote sites, ex:
TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own.
Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.
Most Plugins can be installed in three easy steps, with no programming skills required:
- Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
- Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
- Check the demo example on the Plugin topic: if it's working, the installation was fine!
Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.
Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.
- Doc page: Read all available info about the Plugin; download the attached distribution files.
- Dev page: Post feature requests, bug reports and general dev comments; topic title ends in
Dev (SomePluginDev).
- User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.
To test new Plugins on your installation before making them public, you may want to use one of these two approaches:
- Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
- Duplicate the
twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
- Test Plugins and other new features in the Test installation until you're satisfied.
- If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
- Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.
- Method 2: List the Plugin under
Test in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Test web and do the testing there.
When you finish installing a Plugin, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.
Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
- All Plugin modules present in the
lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the Tharsis web for the Plugin topics. Settings in TWikiPreferences are:
-
Set INSTALLEDPLUGINS = DefaultPlugin, ...
-
Set DISABLEDPLUGINS = EmptyPlugin, ...
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
- One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
-
Set SHORTDESCRIPTION = Blah blah woof woof.
- Debug Plugin, output can be seen in
data/debug.txt. Set to 0=off or 1=on:
- The settings can be retrieved as Preferences variables like
%<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
Plugin status variables let you list all active Plugins wherever needed. There are two list formats:
- The
%ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
- The
%PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.
DEMO: Automatically List Active Plugins Using Variables
Using %ACTIVATEDPLUGINS%:
On this TWiki site, the active Plugins are: DefaultPlugin, InterwikiPlugin, TWikiDrawPlugin, UpdateInfoPlugin.
Using %PLUGINDESCRIPTIONS%:
You can use any of these active TWiki Plugins:
- DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated
*_text_* as bold italic text.
- InterwikiPlugin: Link
ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
- TWikiDrawPlugin: Drawing editor
The TWiki Plugin API
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
The lib/TWiki/Func.pm implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
If you use functions not in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
- For best performance, enable only the functions you really need. NOTE:
outsidePREHandler and insidePREHandler are particularly expensive.
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
- All but the initPlugin are disabled. To enable a call back, remove
DISABLE_ from the function name.
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
- All modules require a
$VERSION='0.000' variable, beginning at 1.000.
- The
initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
- The Plugin initialization code does not register a Plugin that returns FALSE (or that has no
initPlugin handler).
With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API Plugins by providing a programming interface for TWiki.
- DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.
A basic TWiki Plugin consists of two elements:
- a Perl module, ex:
MyFirstPlugin.pm
- a documentation topic, ex:
MyFirstPlugin.txt
The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call.
In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop Plugins.
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic:
- Copy the Plugin topic template from EmptyPlugin. To copy the text, go to the page and:
- click Edit
- select all in the Edit box & copy
- Cancel the edit
- paste & save as a text file or new topic on your site
- Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
- Save your topic as a text file, for use in packaging and publishing your Plugin.
OUTLINE: Doc Topic Contents
Check EmptyPlugin on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:
Syntax Rules: <Describe any special text formatting that will be rendered.>"
MyFirstPlugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
- Plugins Preferences <If user settings are needed, explain... Entering valuse works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
- Set <EXAMPLE = value added>
How-to Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"
Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>"
Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
- Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
-
lib/TWiki/Plugins/MyFirstPlugin.pm
-
data/TWiki/MyFirstPlugin.txt
-
pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
- Create a zip archive with the Plugin name (
MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
-
lib/TWiki/Plugins/MyFirstPlugin.pm
-
data/TWiki/MyFirstPlugin.txt
-
pub/TWiki/MyFirstPlugin/uparrow.gif
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
- Post the Plugin documentation topic in the TWiki:Plugins web:
- Attach the distribution zip file to the topic, ex:
MyFirstPlugin.zip
- Link from the doc page to a new, blank page named after the Plugin, and ending in
Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
-- AndreaSterbini - 29 May 2001
-- PeterThoeny - 14 Sep 2001
-- MikeMannix - 03 Dec 2001
|
>
> |
Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file.
Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.
File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.
- You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using; create a central reference library that's easy to access and manage by an entire user group.
|
Sample.txt
Smile.gif
