Website folders have a built-in element system with a
wiki-like [element …] syntax, allowing you to include
BSCW elements into your pages, e.g. a page’s last modification date, links for
editing the page, a display of the page history or even entire action menus.
BSCW elements have a name and may also have parameters with values. An abstract
example of the BSCW element syntax,
[element name param1=True param2="A long text
with spaces"]
represents the BSCW element name with two
parameters, one named param1 with value True, the
other one named param2 with value "A long text with
spaces". Note the double quotes, which are only needed for values
containing spaces. A concrete example of a BSCW element is
[element documentactions action=edit
text="Change me!"]
representing the action Edit to be applied to the
current document. In the Web view of an HTML document in a website folder, the
BSCW elements are evaluated and the results are inserted into the page. In the
above example, a clickable link labelled Change me! would be
inserted into the document that would invoke the Edit action on the
document itself.
Note: In the
context of BSCW elements in website folders, some actions have names that differ
from their usual names in BSCW. Examples are Revert Changes
instead of Destroy Versions and Add Subfolder
instead of Add Subsidiary Website Folder.
Even though all BSCW elements are enclosed in square
brackets, you can still use square brackets in documents of a website folder as
normal text. Only the string [element will be recognized as the
start of a website folder element. Errors in BSCW element specifications lead to
error messages inserted into the page while the rest of the page will still work
as expected.
You may embed BSCW elements in
arbitrary HTML text that is shown only if the evaluation of the BSCW element
results in a non-empty content. In the following example
[decoration] <HTML text> [element ..]
<HTML text> [/decoration]
the text between [decoration] and
[/decoration] will not be shown, if the result of the BSCW element
evaluation is empty.
In the following, the available BSCW elements are listed in
alphabetical order. The ‘Static’ attribute tells you whether the particular
element will be included in a static copy of the website folder or not (see
8.6.6 Exporting and publishing website folders).
You may enter the BSCW elements directly into the source text of your website
folder’s pages or use the respective drop-down menu of BSCW’s built-in HTML
editor.
Click on an element’s name to have a detailed definition of
its parameters displayed.
o authors Inserts a list of
authors of objects of the current website folder. Clicking on an author name
restricts the list of objects shown in the list generated by contents to
the objects generated by a specific author. Note that clicking on an author name
has no effect on hierarchical lists generated by tree.
Static: No
Parameters:
None
Example:
[element authors]
o back Inserts a link that
leads from inside the website folder to the first parent folder that is
not a website folder.
Static: Yes
Parameters:
icon (optional)
Instead of a
text, you may also label the link with an icon. Enter the URL of the icon as
value of the icon parameter. If both icon and text are given, the
link is labelled with the icon and the text is used as tooltip.
text (optional)
By default, the
label of the back link is taken from the BSCW language files in the
current user language (in English that would be “Back”). You may enter an
alternative label using the text parameter.
Example:
[element back
text="Up and away"]
o categories Inserts a list
of categories assigned to the objects of the current website folder. Clicking on
a category restricts the list of objects shown in a list generated by
contents to the objects with a specific category. Note that clicking on a
category has no effect on hierarchical lists generated by tree.
Static: No
Parameters:
None
Example:
[element categories]
o comments Lists the
comments on the current page and by default offers an input field for entering
new comments, if the user has the right to enter new comments. Eventual answers
to comments are not shown.
Static: Yes
Parameters:
latestfirst (optional, default False)
The comments are sorted by date of creation. By default, the oldest comment
appears at the top of the list. Set the parameter to True. To have the list start with the
latest comment.
maxcomments (optional, default None, i.e. no
restrictions)
The number of the comments shown is not restricted
by default. Using the parameter maxcomments, you may limit the number of
comments shown. If there are more comments than can be shown because of the
limit, a link will appear that takes you to a discussion forum with all comments
shown in the normal BSCW view.
showform (optional, default True)
The input field for new comments is offered by default. You can prevent this
by setting the parameter to False.
Note: If the user does not have the right to enter comments, the
input field will not be offered regardless of the parameter value.
Example:
[element comments
latestfirst=True maxcomments=7]
o contents Inserts a list of
all objects contained in the current website folder as clickable links. In case
of a full-text search the list will be replaced by the search results, if no
proper search result page has been defined using searchresults.
Static: Yes
Parameters:
emptymsg (optional, default True)
By default, the message “No results” will be shown if the contents list is
empty (e.g. because of filtering). Set the parameter to "" to suppress this message. If you
set the parameter to False, the
element remains altogether empty. In this case, you may use [decoration] (see above).
indextopmost (optional, default
True)
By
default, the home page of a website folder comes first in the contents list,
independent of the sorting criterion. You can have the home page being inserted
into the contents list according to the current sorting criterion by setting the
indextopmost parameter to False.
metafilterdocs (optional, default
None)
The
metafilterdocs parameter allows you to hide all documents that do not
satisfy certain criteria regarding one of their metadata attributes. The
parameter value consists of a metadata attribute and a comma-separated list of
possible values. You may check for equality (=), inequality (!) and being part of (%). A qualification of the operators
with a preceding * causes the
display of all documents that do not have the metadata attribute in question.
The examples below demonstrate the use of this parameter. The metadata
attributes are specified using their internal keys. A list of possible metadata
attributes and their keys is given after the examples below. By default, there
is no filtering by metadata attributes.
metafilterfolders (optional, default
None)
Works like metafilterdocs, relates, however, to the display of
folders in the contents listing.
onlynames (optional, default "*")
Works like onlytypes, except that filtering is done on the basis of
object names. Specify a comma-separated list of allowed names, e.g. image??.jpg or *.html (* stands for an arbitrary
string, while ? stands for an arbitrary character). Again, folders are not
affected by the name filtering.
onlytypes (optional, default "text/html")
The onlytypes parameter allows you to hide all documents that do not
have a certain MIME type. Specify a comma-separated list of allowed types, e.g.
text/html for HTML documents.
Specification of entire groups of MIME types is also possible using the wildcard
character * (e.g. text/*).
Folders are not affected by the type filtering. If you want to turn the
filtering off, set the parameter to "*". You may use onlynames
together with onlytypes at a time. In this case, only documents that pass
both criteria will be displayed.
paging (optional, default True)
Determines whether the
entries of the content listing are split into multiple pages if necessary or
not. The maximal number of entries per page corresponds to the user setting
“Maximum number of visible entries in folder listings”, which is defined in the
top menu under Options
Preferences in the section
“Presentation”.
showextensions (optional, default
False)
By default, file name extensions (like .html) are not shown in the contents
list. You can force showing file extensions by setting the showextensions
parameter to True.
showfolders (optional, default "webonly")
Determines which folders are shown in addition to the other objects and may
have one of the following three values:
o all All
folders are shown.
o none No
folders are shown.
o webonly Only website folders
with an active home page are shown.
showhome (optional, default True)
By
default, the home page is shown in the contents listing. You may deviate from
this procedure by setting the parameter to False.
showlayout, showstyle (optional, default
False)
By default, the layout page and the style definition do not appear in the
contents list. You can force their appearance by setting the respective
parameter to True.
showtemplatefolders (optional, default
False)
By
default, template folders are not shown in the contents list. You can force
their appearance by setting the showtemplatefolders parameter to True given that these folders would be
shown at all according to the showfolders setting.
showtitle (optional, default False)
Determines whether the name of the current folder is to be displayed above
the contents listing.
sort (optional, default "byName")
Determines how the contents listing is sorted and may have one of the
following values:
o byType Objects are
sorted by object type.
o byName Objects are
sorted by name.
o bySize Objects are
sorted by size.
o byDate Objects are
sorted by date of last modification.
o byRating Objects are sorted by
rating.
You may also specify several sorting criteria as a
comma-separated list. A - preceding a sorting criterion
inverts the sorting order. If sort is not specified, sorting is by name.
uplink (optional, default False)
By default, the contents
list contains a link to the parent website folder in all subsidiary website
folders, but not in the top-level folder. You can suppress this link by setting
the uplink parameter to False. You can also force the link to
appear in all website folders including the top-level one by setting the value
to True.
target (optional, default "")
Specifies in which browser window documents of a certain type, which are
contained in the contents listing, are to be opened. The value of the parameter
consists of a comma-separated list of specifications relating to the target
window and the MIME type of the document. The specification of a window alone
relates to all documents, the specification of [MIME type]:[window name] relates to
the documents of the MIME type given. For the use of the parameter also see the
examples given below. By default, all documents are opened in the current
browser window, thus replacing the contents listing.
topitems (optional, default "")
Specifies the objects of
the current folder which are to be listed at the top independent of the sorting
chosen. 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 including the layout page. The objects
First and Second appear at the top of the list
independent of the sorting chosen.
[element contents
onlynames="*.html"]
Displays a contents list hiding all
non-folder objects with names not ending in ‘.html’.
[element contents
onlytypes="text/plain,
text/html"]
Displays a
contents list hiding all non-folder objects other than HTML and text documents.
[element
contents metafilterdocs="bscw:keywords=cat,dog"]
Displays a contents list with only those documents containing the tags cat or dog.
[element
contents metafilterdocs="bscw:keywords*=cat,dog"]
Like the previous example, only that documents without any tags are also
shown.
[element
contents metafilterfolders="bscw:keywords!cat,dog"]
Displays a contents list with only those folders not containing the
tags cat or dog.
[element
contents target="_blank"]
Causes all documents of the contents list to be opened in a new browser
window.
[element
contents target="application/pdf:_blank"]
Causes all PDF documents
of the contents list to be opened in a new browser window.
[element
contents target="_blank, application/pdf:myWindow"]
Causes all PDF documents of the contents list to be opened in myWindow, all other documents in a new
window.
Selection of metadata
keys
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 (Coverage), 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 (Given name), bscw_contact:mail (E-Mail address),
bscw_contact:org (Organization), bscw_contact:surname (Surname)
Document attributes used with document
review
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 metadata available, please contact your BSCW administrator. You
can obtain a list of the metadata keys of a given metadata profile selecting
Specification in the
action menu of the metadata profile.
o contentsmetatable Inserts
a table of selected metadata of all objects directly contained in the current
website folder into the current document. This contents table may be sorted by
the user with respect to the metadata shown. By default, the columns of the
table show name, tags and description of the objects directly contained. You may
also have other metadata attributes displayed. Metadata attributes are
identified by their keys. You can obtain a list of the metadata keys used in a
metadata profile by selecting
in the action menu of the metadata profile. For examples of metadata keys also
see contents above.
Static: Yes
Parameters:
columns (optional, default "bscw:name, bscw:keywords,
bscw:description")
By default, the contents table shows in its columns the name, tags and
description of the objects directly contained. If you want to deviate from the
default, enter a comma-separated list of metadata keys as value for the
columns parameter.
Moreover, the following parameters are available which have
the same effect as in contents, namely to exclude certain objects from
the contents table.
metafilterdocs (optional, default
None)
metafilterfolders (optional, default
None)
onlynames (optional, default "*")
onlytypes (optional, default "text/html")
showfolders (optional, default "webonly")
showhome (optional default True)
showlayout (optional, default False)
showstyle (optional, default False)
showtemplatefolders (optional, default
False)
Example:
[element
contentsmetatable]
Shows the documents and website folders directly contained in the current
folder as a table with name, tags and description columns.
o date Inserts the current
date and/or time.
Static: Yes
Parameters:
format (optional)
If you don’t like the
default date and time format (example: 2007-07-03 14:31) and are familiar with
Python programming, you can specify your own format. Please refer to the Python
reference manual under strftime.
Example:
[element date
format="%A, %B %d, %I:%M %p"]
Inserts the current date
and time in a user-defined format, yielding Tuesday, July 03, 02:31 PM instead
of the standard format above.
o
documentactions Inserts a
complete action menu for the current document or a direct link to a specific
action.
Static: No
Parameters:
action (optional)
If the parameter is
omitted, a whole action menu will be inserted. Otherwise, a direct link to the
action specified will be created. See below for admissible values of the action
parameter. If the action specified is not allowed for the current user, the
documentactions element will be replaced by the value of the
forbiddentext or forbiddenicon parameters or an empty string.
forbiddenicon (optional and only used if action
is specified)
If the action specified is not allowed for the current
user, the icon referred to by the value of the parameter will be displayed
instead of the action link.
forbiddentext (optional and only used if action
is specified)
If the action specified is not allowed for the current
user, the value of the parameter will be displayed instead of the action link.
The forbiddentext parameter defaults to an empty string.
icon (optional and only used if action is
specified)
The link to the action specified will be
labelled with an icon. The value of the icon parameter is the URL that
refers to the icon. The value may also be True in which case the BSCW icon of
the action is taken. If both icon and text are given, the link is
labelled with the icon and the text is used as tooltip.
onlyif (optional, default "")
Specifies a condition for the display of the action or action menu. If the
condition is not satisfied, the whole element remains empty. The value of the
parameter is a string of characters. The conditions that are currently available
check whether the current document is the home page (index) or which level of proficiency
the user has (beginner, advanced or expert: profile_ui_beginner, profile_ui_advanced, profile_ui_expert). The level of
proficiency is set in the top menu under Options
Preferences
in the section ‘General’. You may also use the logical operator not in your conditions. See below for
some examples.
text (optional and only used if action is
specified)
The link to the action specified will be
labelled with the value of the text parameter. If the text and
icon parameters are omitted, the link will be labelled with the BSCW name
of the action in the current user’s preferred language. Remember that a text
containing spaces must be enclosed in double quotes.
Examples:
[element
documentactions]
Inserts the action menu for the current
document.
[element
documentactions action=get text="Source"]
Inserts a link for
opening the current document with the link labelled “Source”. This action will
show the document’s source code, i.e. BSCW elements or text elements are not
evaluated and replaced.
[element
documentactions action=replace]
Inserts an action link for replacing the current document with the default
link label “Replace”.
[element
documentactions action=printweb icon=True onlyif="not index"]
Inserts the default icon for printing the current document into the current
document if it is not the home page of the current website folder.
[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 has set
the level of proficiency 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 (Revise).
o fileupload Inserts an
interaction element for uploading images to the current folder. There is to be
at most one fileupload element per page.
The
interaction element consists of three buttons [Select file(s) to upload…],
[Upload], [Cancel upload] and a preview domain showing the files intended for
upload. The first button initiates a standard file selection dialog, the second
button causes the actual uploading and the third button cancels the upload
process. You may also specify files for uploading by dropping them over the
[Upload] button. The files intended for uploading are shown in the preview area
below the buttons.
Note: Currently, the fileupload element is to be used for
uploading image files only.
Static: No
Parameters:
None
Example:
[element fileupload]
o
folderactions Works
exactly like documentactions, but takes the current website folder as the
object of reference for the action menu or the action links.
Static: No
Parameters:
Same as for documentactions.
Examples:
[element
folderactions]
Inserts the action
menu for the current website folder.
[element
folderactions action=get text="List all objects in BSCW
style"]
Inserts
a link to open the current website folder with link label “List all objects in
BSCW style”, resulting in a normal folder listing.
[element
folderactions action=history]
Inserts a link to the folder’s
history with the default link label “Show History”.
Possible actions:
addcal
(Add Group Calendar), addctlist (Add Contact List), addmember (Invite Member),
addnotes (Add Discussion Forum),addpage (Add Page), addsubwebfolder (Add
Folder), addrole (Add Role), addSearch (Add Search Folder), addurl (Add URL),
chbanner (Change Banner), chrole (Assign Role), copy (Copy), cut (Cut),
editindex (Edit Home Page), editobject (Change Properties), editrole (Edit
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 Clipboard), make (Static Copy) pubaccess
(Public Access), uploaddoc (Upload Document).
o gallery Displays the
image files that are contained in the current folder in form of a gallery with
miniaturized previews. Image files are documents with a respective MIME type
(image/jpg, image/png etc.).
Static: Yes
Parameters:
emptymsg (optional, default True)
By
default, the message “No results” is displayed if the current folder contains no
image files. If you set the parameter to "" this message will not appear. If
you set the parameter to False
the whole element remains empty. In the latter case, you can use [decoration]
(see above).
hover (optional, default False)
Set the parameter to True to have a gallery image over
which the cursor is positioned slightly enlarged.
lightbox (optional, default False)
Set the parameter to True to have a full-window preview
displayed when you click on a gallery image.
paging (optional, default False)
Works as with
contents. Here you can additionally set the maximal number of entries per
page directly as the value of the parameter paging. This replaces the
user setting “Maximum number of visible entries in folder listings”.
size (optional, default value "small")
Controls the size of the
gallery images displayed. Other possible values are "medium" and "large".
sort (optional, default "byType, byName")
By default, the images are sorted by type and name.
Other sorting orders are defined via this parameter as with contents.
Example:
[element gallery
paging=10 sort="byName" lightbox=True]
o history Inserts a list of
the documents that were visited last as a list of clickable links.
Static: No
Parameters:
divider (optional, default ", ")
By default, the links in the
list are separated by a comma and a blank. Using the divider parameter,
you may enter an alternative separation string.
maxdocs (optional, default 5)
By default, at
most five documents will be listed. With the maxdocs parameter you may
set a different maximum.
showextensions (optional, default
False)
By default, file extensions (such as .html) are not shown in the history
list. By setting showextensions to True you may force showing file
extensions.
Example:
[element history
divider=" | " maxdocs=7]
o lastmod Inserts the date
and/or time of the current document’s last modification.
Static: Yes
Parameters:
format (optional)
You can specify your own date and
time format as explained under date above.
Example:
[element
lastmod]
o lastmodby Inserts the
name of the user who last modified the current document.
Static: Yes
Parameters:
None
Example:
[element lastmodby]
o location Inserts the path
to the current document as clickable links.
Static: Yes
Parameters:
None
Example:
[element location]
o message Inserts a BSCW
system message. These messages are displayed in the preferred language of the
current user.
Static: Yes
Parameters:
name (required)
The name of the message to
display. The available messages are contained in the file
bscw-directory/messages/en/lg_msgconfig.py
on your BSCW server. Ask your BSCW system administrator for the precise
location of this file in your particular BSCW installation.
Example:
[element message
name=location]
Displays the message named ‘location’. In
English, this yields “Your location”.
o metadata Inserts the
metadata of the current object as a table arranged according to the groups of
the respective metadata profile and offers a button for changing the metadata.
In contrast to contentsmetatable, metadata is about one single
object.
Static:
Yes
Parameters: None
Example:
[element metadata]
o search Inserts the input
field for the full-text search within the website folder. The search results
appear on the search results page that you have defined for the current website
folder using searchresults. Without a specific search result page, the
search results replace the contents list or tree that were generated using
contents or tree. Using search only makes sense if you use
searchresults, contents or tree at the same time, otherwise
the search results will not be shown.
Static: No
Parameter:
None
Parameters:
selectscope (optional, default False)
Specifies
whether the search domain (entire website folder or current folder) can be
selected at the user interface.
scopeall (optional, default True)
Specifies whether the entire website folder is to be searched. Set the
parameter to False if you want
to restrict the search to the current folder.
Example:
[element search]
o searchresults Specifies
the appearance of the search result page that shows the results of a search in
the current folder.
Static: No
Parameters:
The same as for contents with the following additions:
grouping (optional,
default)
Allows the grouping of search results
according to folders in which they are contained. The default setting has the
search results presented as a normal list sorted by the sorting criteria of the
sort parameter. If you set the parameter grouping to
True, the search
results are presented in groups: each group contains all hits that were found in
a particular folder; the groups themselves are sorted according to the path that
leads to a specific folder; within the groups the search results are sorted
according to the criteria of the sort parameter. If you set the parameter
grouping to a number n>1, a maximum of n search results will be shown per
group.
paging (optional, default False)
Works basically as with contents, i.e. the search results are
distributed to several pages if necessary, if the parameter has not the value
False. As with gallery
you can also set the maximal number of entries per page directly as the value of
the parameter paging. This replaces the user setting “Maximum number of
visible entries in folder listings”.
The way search results are distributed to different pages here also depends
on the value of the parameter grouping. If grouping has the
default value False, the search
results are distributed to pages according to the value of the parameter
paging. If the parameter grouping has the value True, the parameter paging
specifies how many groups (not search results) are to appear on one page at
most. Also, when grouping has a value of n>1, paging specifies the maximal
number of groups that are to appear on a single page, only that now not all
search results of a group are shown, but at most only n.
showpath (optional, default False)
Specifies whether the path of the folder containing the search result is to
be displayed after the name of the search result.
Example:
[element
searchresults grouping=8 paging=4]
Specifies that search
results are to be grouped according to the subfolders in which they are
contained, that a maximum of eight search results are to be displayed per group
and that a maximum of four groups are to be displayed per page.
o size Inserts an object’s
size.
Static: Yes
Parameters:
filename
(optional)
By default, the current
document’s size is used. You can specify a different object by giving its name
in the filename parameter.
unit (optional, default B)
The default unit is bytes
(B). If your document is rather
large, another unit may be more appropriate. Valid units are B, KB, MB, and GB.
Example:
[element size
filename="files/dvd-image.iso"
unit=GB]
Inserts the size of the
object dvd-image.iso in subfolder files of the current folder, measured
in gigabytes.
o systembanner Inserts the
system banner, by default the BSCW system banner.
Static: Yes
Parameters:
None
Example:
[element
systembanner]
o tags Inserts a list of
tags assigned to the objects of the current website folder. Clicking on a tag
restricts the list of objects shown in a list generated by contents to
the objects with a specific tag assigned. Note that clicking on a tag has no
effect on hierarchical lists generated by tree.
Static: No
Parameters:
None
Example:
[element tags]
o toc Displays a table of
contents of the current document consisting of headings as clickable links
allowing navigation within the document.
Static: Yes
Parameters:
headingcount (optional, default
1)
Specifies the minimal number of headings in the table of contents. If the
document has fewer headings, no table of contents will be displayed at all. This
parameter is to enable the use of the element toc also in layout pages
and at the same time to prevent too meager tables of contents of embedded
content pages.
highest (optional, default 5)
Defines the highest level of headings to be included in the table of
contents. A value of 3, e.g.,
lets headings <h1>, <h2> and <h3> appear in the table of
contents, but not headings <h4>, <h5> etc.
lowest (optional, default 1)
Defines the lowest level of headings to be included in the table of
contents. A value of 2, e.g.,
lets headings <h2>, <h3>, <h4> etc. appear in the table of
contents, but not <h1>
headings.
title (optional, default None)
Using this parameter you can define your own title 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 of
level <h1>, <h2> and <h3> and the preceding title
Contents.
o tree Inserts a tree of
clickable links showing the contents of the current website folder from top
level down to the current document. In case of a full-text search the tree will
be replaced by the search results when no proper search results page has been
defined using searchresults.
Static: Yes
Parameters:
Same as for contents with the exception of paging and
an exception concerning a default procedure:
showhome (optional, default procedure see below)
By default, the home page is shown for the top-level folder,
but not for subsidiary folders in the tree. You may deviate from this procedure
by setting the parameter to either True or False.
Examples:
[element tree
showlayout=True]
Displays a contents tree
including layout pages.
[element tree
onlynames=*.html]
Displays a contents tree hiding all
non-folder objects with names not ending in ‘.html’.