Wiki have their own system of elements with a wiki-like
syntax ([element ...]) that allows you to use BSCW elements in your
pages. Examples are the date of the last modification of a page, links to edit a
page, the display of a page's history or even whole context menus. BSCW elements
have a name and may also have parameters with values. An abstract example for
the syntax of BSCW elements is
[element name param1=True param2="A long text
with spaces"]
This element name has two parameters
param1 and param2 with the values True and "A
long text with spaces" respectively. Note the quotation marks that are
only needed for values that contain spaces. A concrete example for a BSCW
element is
[element documentactions action=edit text="Edit
document"]
This element represents the Edit action that is
applied to the current document. In the Web view of an HTML document in a wiki,
the BSCW elements are evaluated and the results are inserted into the document.
In the example above, a link with the text Edit document would be
inserted into the document; clicking on the link would invoke the Edit
action on the document itself.
Note: In the
context of use in BSCW elements of wikis, some actions have different names than
usual. Examples are Undo Changes instead of Delete Versions and
New Subfolder instead of New Sub-Wiki.
Although the BSCW element syntax uses square brackets, you
may still use square brackets in the text of wiki documents. Only the string
[element is taken as the beginning of a wiki element. Errors in
BSCW element specifications lead to error messages that are inserted into the
evaluated text of a page while the rest of the page still behaves as expected.
You may embed a BSCW element in
arbitrary HTML text that is only displayed if the evaluation of the BSCW element
results in non-empty content, as shown in the following example.
[decoration] <HTML text> [element ..]
<HTML text> [/decoration]
Here all text between [decoration] and
[/decoration] is not displayed if the BSCW element does not provide
any content.
In the following, the available BSCW elements are listed in
alphabetical order. The attribute 'Static' indicates whether the element in
question is included in a static copy of the wiki or not (see 8.7.6 Export Wiki and make it publicly available).
You may insert the BSCW elements directly into the source code of your wiki
pages or use the related menu in the integrated HTML editor.
For a detailed definition of the parameters click on the
name of the elements.
•
authors Inserts a list of
authors of documents of the current wiki. Clicking on an author name restricts
the display of objects in the contents list created by contents to
those objects created by that author. Note that clicking on an author name has
no effect on hierarchical lists created with tree.
Static: No
Parameters: None
Example:
[element authors]
•
back Inserts a link that
leads out of the wiki to the first parent non-wiki.
Static: Yes
Parameters:
icon (optional)
Instead of a
text you can also underlay the back reference with an icon. Specify the URL of
the icon as the value for the icon parameter. If both icon and
text are specified, the action reference is underlaid with the icon and
the text acts as a tooltip.
text (optional)
By default, the
text for the back link is set to the corresponding BSCW text in the
user's language (i.e., "Back" in German). You may use the text parameter
to specify a different label for the link.
Example:
[element back
text="Up"]
•
categories Inserts a list
of categories assigned to objects in the current wiki. Clicking a category
restricts the display of objects in the content list generated by contents
to those objects that have been assigned that category. Note that clicking a
category has no effect on hierarchical lists created with tree.
Static: No
Parameters: None
Example:
[element categories]
•
comments Lists the
existing comments on the current page and offers an input field for new comments
by default, if the user has the right to enter comments. Any replies to comments
are not displayed.
Static: Yes
Parameters:
latestfirst (optional, default False).
Comments are sorted by date of creation. By default, the oldest comment
appears at the top of the list. If you want the list to start with the newest
comment, set the parameter to True.
maxcomments (optional, default value
None, i.e. no limit).
The number
of displayed comments is not limited by default. You can use the maxcomments
parameter to limit the number. If there are more comments than can be
displayed due to the limit, a link will appear that allows you to view all
comments as a discussion forum in the normal BSCW view.
showform (optional, default True).
By
default the input field for new comments is shown. You can disable this by
setting the parameter to False.
Note: if the user does not
have the right to enter new comments, the input field will not be displayed
regardless of the value of the parameter.
Example:
[element comments
latestfirst=True maxcomments=7]
•
contents Inserts a list of
all objects directly contained in the current wiki as clickable links. After a
full-text search, the search results replace the contents list if no separate
search results page has been defined with searchresults.
Static: Yes
Parameters:
emptymsg (optional, default True).
By
default, if the content list is empty (e.g. due to filtering), the "no results"
message is displayed. If you set the parameter to "", this message will not appear. If
you set the parameter to False,
the whole element will remain empty. In the latter case [decoration] (see above) can be used.
indextopmost (optional, default
True).
By
default, the start page of a wiki is displayed first in the content list.
However, you can also sort the start page into the content list according to the
valid criterion by setting the indextopmost parameter to False.
metafilterdocs (optional, default
None).
The
metafilterdocs
parameter allows you to display only documents in the
content list that meet certain criteria regarding one of their metadata
attributes. The parameter value consists of a metadata attribute and a
comma-separated list of possible values. It can be checked for equality (=), inequality (! ), and containedness (%). Qualifying the operators with a
preceding * causes a display even of those
documents that do not have the searched metadata attribute. The examples below
explain the use of the parameter. The metadata attributes are to be specified
with their internal identifiers. A list of possible metadata and their
identifiers can be found below after the examples. In the default case, metadata
is not filtered.
metafilterfolders (optional, default
None).
Works like metafilterdocs, but refers to the display of folders in
the content list.
onlynames (optional, default value
"*")
The onlynames parameter
allows you to exclude from the contents list documents whose names do not
contain certain strings. Specify a comma-separated list of allowed names, such
as image??.jpg or *.html (where * stands for any string
and ? for any character). Folders are not affected by this filtering by name.
onlytypes (optional, default "text/html").
Has the same effect as onlynames, except that it filters based on the
MIME type of the objects. Specify a comma-separated list of allowed types as the
value of this parameter, e.g. text/html for HTML documents. Specification of
whole groups of MIME types is also possible, using * as wildcard, e.g. text/*. Folders are not affected by
this filtering by MIME type. If you want to turn off the filter, specify "*"
as the value. You can use onlytypes at the same time as
onlynames. In this case, only documents that meet both criteria are
displayed.
paging (optional, default True)
Determines whether the
entries of the contents list, if necessary, are split into multiple pages that
can be switched between, or not. The number of entries per page corresponds to
the user setting "Maximum number of visible entries in folder views" defined in
the top menu under the "Appearance" tab in the main
Settings menu.
showextensions (optional, default
False).
By default, file name extensions (such as .html)
are not shown in the
contents list. However, you can display these extensions by setting
showextensions to True.
showfolders (optional, default "webonly").
Determines which folders are displayed in addition to the other objects, and
can have one of the following three values:
o all
All folders are displayed.
o none No folder is displayed.
o webonly Only wiki with active start
page are displayed.
showhome (optional, default True).
By
default, the home page appears in the content list. You can deviate from this
procedure by setting
the parameter to False.
showlayout, showstyle (optional, default
False).
By default, layout page and style definition
do not
appear in the content list. You can force this by setting the
corresponding parameter to True.
showtemplatefolders (optional, default
False).
By default, template
folders are not shown in the content list. You can force this by setting the
showtemplatefolders parameter to True, provided that these folders
would be displayed at all according to the value of the showfolders
parameter.
showtitle (optional, default False).
Determines whether the name of the current folder should be displayed above
the contents list.
sort (optional, default value "byName").
Sets the sort order of the
content list and can have the following values:
o byType Sorting by object type
o byName Sort by name
o bySize Sort by
size
o byDate Sort by
date of last change
o byRating Sort by
rating
Multiple sort criteria can also be specified as a
comma-separated list. A -
before the sort criterion reverses the sort order. If sort is not
specified, sorting is done by name.
uplink (optional, default False).
By default, the content
list for all sub-wiki contains a reference to the parent wiki, but not in the
top-level wiki. You can suppress this reference by setting the uplink
parameter to False. You can
also make the reference appear at top level by setting the value to True.
target (optional, default "")
Specifies in which
browser window documents of a certain type included in the content list should
be opened. The value of the parameter consists of a comma-separated list of
specifications related to the target window and the MIME type of the document.
Specifying a window name alone refers to all documents, specifying [MIME type]:[window name] refers only
to displaying documents of the mentioned MIME type. For the use of the parameter
see also the examples below. By default, all documents are opened in the current
window of the browser, thus replacing the display of the contents list.
topitems (optional, default value
"").
Specifies the items of
the current folder that should be displayed first, regardless of the selected
sort order. The value of the parameter consists of a comma-separated list of
object names.
Examples:
[element
contents showlayout=True topitems="First,Second"]
Displays a
contents list that includes the layout page. The First and Second objects appear at the top of
the list, regardless of the sort order.
[element contents
onlynames="*.html"]
Displays a contents list that contains
only objects whose names end in .html, in addition to folders.
[element contents
onlytypes="text/plain, text/html"]
Displays a contents list containing only text and HTML documents in addition
to folders.
[element
contents metafilterdocs="bscw:keywords=cat,dog"]
Displays a contents list containing only those documents that contain the
tags cat or dog.
[element
contents metafilterdocs="bscw:keywords*=cat,dog"]
As before, except that documents without tags are also
displayed.
[element
contents metafilterfolders="bscw:keywords!cat,dog"]
Displays a contents list containing only those folders that do not
contain the tags cat or dog.
[element contents
target="_blank"]
Causes
all documents in the contents list to open in a new browser
window.
[element
contents target="application/pdf:_blank"]
Causes all PDF documents in the contents list to open in a new
browser window. All other documents will be opened in the current
window.
[element
contents target="_blank, application/pdf:myWindow"]
Causes all PDF documents in the contents list to be opened in the
myWindow window. All other documents
will be opened in a new window.
Metadata identifier
selection
General metadata of BSCW
objects
bscw:category (category),
bscw:description) (description), bscw:keywords (tags), bscw:name (name),
bscw:priority (priority)
Dublin Core attributes of documents
DC:author (author), DC:coverage (area), DC:created (created on), DC:format
(format (MIME type)), DC:language (language), DC:publisher (publisher),
DC:source (source), DC:subject (subject), DC:title (title)
Metadata of users and contacts
bscw_contact:givenname (first name), bscw_contact:mail (email address),
bscw_contact:org (organization), bscw_contact:surname (last name)
Document attributes for document approval
bscw_doc:approval_status (status), bscw_doc:responsible (responsible)
Metadata of flow folders
bscw_flowfolder:responsible (responsible), bscw_flowfolder:task (task)
For a
complete list of available metadata, contact your BSCW administrator. You may
get a list of metadata identifiers of a specific metadata profile by selecting
Specification
from the
profile's context menu.
•
contentsmetatable Inserts
a table with selected metadata of all objects directly contained in the current
wiki into the current document. This contents table can be sorted by the user
according to the metadata displayed. By default, the columns of the table
display the metadata name, tags and description of the contained objects. You
can also display other metadata. Metadata attributes are identified by their
identifiers. You can get a list of metadata identifiers for a metadata profile
by calling
from the metadata profile's context menu. For examples of metadata identifiers,
see contents above.
Static: Yes
Parameters:
columns (optional, default "bscw:name, bscw:keywords,
bscw:description")
By default, the content table displays in its
columns the metadata name, tags and description of the directly contained
objects in this order. Specify a comma-separated list of metadata names here if
you want to deviate from the default.
In addition, the following parameters are available, which
have the same effect as in contents, namely to exclude certain objects
from inclusion in the contents table.
metafilterdocs (optional, default
None)
metafilterfolders (optional, default
None)
onlynames (optional, default value
"*")
onlytypes (optional, default "text/html")
showfolders (optional, default value
"webonly")
showhome (optional default True)
showlayout (optional, default False)
showstyle (optional, default False)
showtemplatefolders (optional, default
False)
Example:
[element
contentsmetatable]
Shows the contained documents and web folders in tabular form with names,
tags and description.
•
date Inserts the current
date and time.
Static: Yes
Parameters:
format (optional)
If you don't like the
default format for date and time (example: 2007-07-10 14:31) and you are
familiar with Python programming, you can specify your own format here. Consult
the Python manual under strftime.
Example:
[element date
format="%A, %d. %B, %H:%M"]
Inserts the
current date and time in a custom format that results in Tuesday, July 10, 14:31
instead of the default format above.
•
documentactions Inserts a
complete context menu for the current document or a reference to a specific
action.
Static: No
Parameters:
action (optional)
If this parameter is omitted, a
whole context menu will be inserted. Otherwise a direct reference to the
specified action will be created. The allowed values for the action
parameter are listed below. If the specified action is not allowed for the
current user, the documentactions element will be replaced by the value
of the forbiddentext or forbiddenicon parameters, or by an empty
string.
forbiddenicon (Optional; used only if action is
set).
If the specified action is not allowed for the current
user, the icon referenced by the value of this parameter is displayed instead of
the reference to the action.
forbiddentext (Optional; used only if action is
set).
If the specified action is not allowed for the current
user, the value of this parameter will be displayed instead of the reference to
the action. If the parameter is omitted, an empty string will be displayed in
this case.
icon (optional; only used if action is
set).
The icon parameter can be
used to provide the reference to the action with an icon. The value of the
parameter is a URL that points to the icon. If the value is set to
True, the BSCW icon for the action
will be taken. If both icon and text are specified, the action
reference is underlaid with the icon and the text acts as tooltip.
onlyif (optional, default "")
Defines a condition for displaying the context menu. If the condition is not
met, the whole element remains empty. The value of the parameter is a string.
Currently available conditions check whether the current page is the start page
of the wiki (index) or which
skill level the user has (beginner, advanced, expert: profile_ui_beginner, profile_ui_advanced, profile_ui_expert). The competence
level is set in the upper menu under the main
menu Settings in the tab "General". The logical operator not
can also be used. Compare also the examples below.
text (Optional; used only if action is set).
The text of the reference to the specified
action corresponds to the value of the text
parameter. If the
text parameter is omitted, the text of the reference consists of the BSCW
name of the action in the language of the current user. Remember that text
containing spaces must be enclosed in quotes.
Examples:
[element
documentactions]
Inserts the user interface context menu for
the current document.
[element
documentactions action=get text="Source text"]
Inserts a link
to open the current document with the text "source text". This action displays
the source text of the document, i.e. BSCW and text elements are not evaluated
and replaced.
[element
documentactions action=replace]
Inserts a reference to replace the current document with the default text,
action name "Replace".
[element
documentactions action=printweb icon=True onlyif="not index"]
Inserts the default icon for printing the current document into the current
document, unless it is the home page.
[element
documentactions action=edit icon=True
onlyif=profile_ui_expert]
Inserts the default icon for editing
the current document into the current document if the user's skill level is set
to "Expert".
Possible actions:
attachnote (attach note), checkout (lock), chtype (change type), copy
(copy), cut (cut), cutattachment (cut attachment), duplicate_edit (edit copy),
edit (edit), editobject (change properties), export (Export), freeze (Freeze),
get (Open), history (Show history), info (More information), link (Link to
clipboard), printweb (Print), rate (Rate), replace (Replace), resubmit
(Resubmit), revise (New version).
•
fileupload Inserts an
interaction element for uploading images to the current folder. Only one
fileupload element is allowed per page.
The
interaction element consists of three buttons [Select file(s) to upload...],
[Upload] and [Cancel upload] as well as a preview area for the files to be
uploaded. The first button initiates a standard file selection dialog, the
second button causes the actual upload, and the third button cancels the upload
process. You can also drag files to be uploaded over the [Upload] button and
drop them there. The files selected for upload are displayed in the preview area
below the buttons.
Note:
Currently, the fileupload element is intended for uploading image
files only.
Static:
No
Parameters: None
Example:
[element fileupload]
•
folderactions Works
exactly like documentactions, but the current wiki is the subject of the
context menu or the individual actions that are referenced.
Static: No
Parameters:
The same as for documentactions.
Examples:
[element
folderactions] Inserts
the user
interface context menu without JavaScript for the current wiki.
[element
folderactions action=get text="List of all objects in BSCW style"]
Inserts a link to open the current wiki with the text
"List of all objects in BSCW style". This action displays the BSCW-style list of
entries of the wiki.
[element
folderactions action=history]
Inserts a
reference to the history of the current wiki with the default text, action name
"show history".
Possible actions:
addcal
(New group calendar), addctlist (New contact list), addmember (Add member),
addnotes (New discussion forum),addpage (New page), addsubwebfolder (New
folder), addrole (New role), addSearch (New search folder), addurl (New URL),
chbanner (Change banner), chrole (Assign role), copy (Copy), cut (Cut),
editindex (Edit home page), editobject (Change Properties), editrole (Change
role), editstyle (Edit style definition), edittemplate (Edit layout page),
export (Export), get (Open), getweb (Show web view), history (Show history),
info (More information), link (Link to repository), make (Static copy),
pubaccess (Make public), uploaddoc (Upload document).
•
gallery Represents the
images contained in the current wiki in the form of a gallery with miniaturized
views. Images are understood to be documents with a corresponding MIME type
(image/jpg, image/png, etc.).
Static: Yes
Parameters:
emptymsg (optional, default True).
By
default, the "no results" message is displayed when the image gallery is empty.
If you set the parameter to "",
this message will not appear. If you set the parameter to False, the whole element will remain
empty. In the latter case [decoration] (see above) can be used.
hover (optional, default False)
If the parameter is set to
True, a gallery image over which the
cursor is located will be slightly enlarged.
lightbox (optional, default False).
If the parameter is set to True, a full-screen preview is
displayed when a gallery image is clicked.
paging (optional, default False)
Basically works like contents. Only here you can additionally specify
the maximum number of entries per page directly as the value of the parameter,
which replaces the user setting "Maximum number of visible entries in folder
views".
size (optional, default "small")
Controls the size of the
displayed gallery images. Other possible values are "medium" and "large".
sort (optional, default value "byType,
byName").
By default, images are sorted
by type and name. Different sorts are defined with this parameter as with
contents.
Example:
[element gallery
paging=10 sort="byName" lightbox=True]
•
history Inserts the list
of recently visited documents as clickable links.
Static: No
Parameters:
divider (optional, default ",
").
By
default, references in the list are separated by commas and spaces. You can use
the divider parameter to specify another string as a separator.
maxdocs (optional, default value
5).
By default, a
maximum of five documents are displayed in the list. With maxdocs you can
set a different maximum number.
showextensions (optional, default
False).
By default, file name extensions (such as .html) are not shown in the history
list. However, you can display these extensions by setting showextensions
to True.
Example:
[element history
divider=" | " maxdocs=7]
•
lastmod Inserts the date
and time of the last modification of the current document.
Static: Yes
Parameters:
format (optional)
You can specify your own format
here, as explained above for date.
Example:
[element lastmod]
•
lastmodby Inserts the
name of the user who last modified the current document.
Static: Yes
Parameters: None
Example:
[element lastmodby]
•
location Inserts the path
to the current document as clickable links.
Static: Yes
Parameters: None
Example:
[element location]
•
message Inserts a BSCW
system message. These messages are displayed in the language set by the current
user.
Static: Yes
Parameters:
name (required)
The name of the message to be
displayed. The available messages are listed in the BSCW
directory/messages/en/lg_msgconfig.py on your BSCW server. Ask your BSCW
administrator for the contents of this file or the exact location of this file
in your BSCW installation.
Example:
[element message
name=location]
Displays the message with the name 'location'.
In German this results in "Ihre Position".
•
metadata Inserts a list
with the metadata of the current object, organized by the groups of the
respective metadata profile, and provides a button to change the metadata.
Unlike contentsmetatable, this is about an object.
Static: Yes
Parameters: None
Example:
[element
metadata]
•
search Inserts the input
area for the full text search in the wiki. If possible, a [Advanced] button
appears to the right of the search field, leading to the full search form. The
results of the search appear on a search results page that you have defined with
searchresults for the current wiki. Without a special search results
page, the search results replace content lists or content trees created with
contents or tree, respectively. The use of search only makes sense
if searchresults, contents or tree are used at the same
time, because otherwise the search results will not be displayed.
Static: No
Parameters:
None
Parameters:
selectscope (optional, default False).
Determines whether
the search scope (whole wiki or current folder) can be selected at the user
interface.
scopeall (optional, default True)
Specifies whether the search will take place in the whole wiki or not. Set
the parameter to False if you want to limit the search
to the current folder.
Example:
[element search]
•
searchresults Defines the search results page that displays the results
of searches in the current wiki.
•
size Inserts the size of
an object.
Static: Yes
Parameters:
filename (optional)
By default, the size of the current
document is displayed. You can specify another object whose size should be
displayed by specifying its name in the filename parameter.
unit (optional, default value B).
The default unit is byte
(B). If your object is quite
large, another unit might be more appropriate. Valid units are B, KB, MB, GB.
Example:
[element size
filename="files/dvd-image.iso" unit=GB]
Inserts the size of the dvd-image.iso object in the files subfolder of the current folder
in gigabytes.
•
systembanner Inserts the
system banner; by default this is the normal BSCW system banner.
Static: Yes
Parameters: None
Example:
[element
systembanner]
•
tags Inserts a list of
tags assigned to objects in the current wiki. Clicking a tag restricts the
display of objects in the content list generated by contents to only
those objects that have been assigned that tag. Note that clicking a tag has no
effect on hierarchical lists created with tree.
Static: No Parameters:
None
Example:
[element tags]
•
toc Displays a table of
contents of the current document consisting of the headings as clickable links
that allow navigation in the document.
Static: No
Parameters:
headingcount (optional, default
1).
Sets
the minimum number of headings in the table of contents. If this value is not
reached, no table of contents will be displayed at all. This parameter is
intended to allow the toc element to be used on layout pages as well,
preventing the table of contents of embedded content pages from being too
sparse.
highest (optional, default value
5)
Specifies the level up to which headings should be included in the table of
contents. For example, a value of 3
specifies that headings <h1> , <h2> and <h3>
should be included in the table of contents, but not headings
<h4> , <h5> etc.
lowest (optional, default value
1)
Specifies the level at which headings should be included in the table of
contents. For example, a value of 2
specifies that headings <h2> , <h3> , etc. should be included in the table
of contents, but not headings <h1>.
title (optional, default None)
This parameter can be used to specify a title line for the table of
contents.
Example:
[element toc
headingcount=5 highest=3 title="Contents"]
Displays a table of contents
consisting of at least five headings with headings <h1> , <h2> and <h3>
and preceded by the title line
Contents.
•
tree Inserts a tree view
of the current folder and all parent wikis consisting of clickable links. After
a full-text search, the search results replace the content tree if no separate
search results page has been defined with searchresults.
Static: Yes
Parameters:
The same as for contents except for paging and
an exception for the default value.
showhome (optional, see below for default).
By default, the home page is shown for the top folder, but not for
the subfolders in the tree. You can deviate from this procedure by setting the
parameter to True
or False.
Examples:
[element tree
showlayout=True]
Displays a content tree with
layout pages.
[element tree
onlynames=*.html]
Displays a content tree that contains
only objects whose names end in .html, in addition to folders.