### Using BSCW elements

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 whole 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.

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 5.5.7 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 author]

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:

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.

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.

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 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.

Static: Yes
Parameters:

showlayout, showhome, showstyle (optional, default False)
By default, the layout page, the home page and the style definition do not appear in the contents list. You can force their appearance by setting the respective parameter to True.

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 whole 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 "*" .

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. You may use onlytypes together with onlynames at a time. In this case, only documents that pass both criteria will be displayed.

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.

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.

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.

sort (optional, default "byName")
Determines how the contents list 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.

If sort is not specified, sorting is by name.

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.

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.

Examples:

[element contents showlayout=True]
Displays a contents list including the layout page.

[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.

o date Inserts the current date and/or time. For available date formats also see 5.6.5 Functions.

Static: Yes
Parameters:

format (optional)
If you don’t like the default date and time format (as applied in 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 (or see the reference given above for a summary).

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 the non-JavaScript action menu (see 4.3.1 JavaScript, style sheets and user language) 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.

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.

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.

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.

Examples:

[element documentactions]
Inserts the non-JavaScript 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”.

Possible actions:
addpage (Add Page), addrole (Add Role), addsubwebfolder (Add Subfolder), addtempl (Copy from Template), attachnote (Attach Note), checkout (Lock), chrole (Assign Role), chtype (Change Type), copy (Copy), cut (Cut), cutattachment (Cut Attachment), duplicate_edit (Edit Copy), edit (Edit), editobject (Change Properties), editrole (Edit Role), export (Export), firstversion (Start Version Control), freeze (Freeze), get (Open), history (Show History), info (More Information), link (Link to Clipboard), make (Static Copy), printweb (Print), rate (Rate), rename (Change Name), replace (Replace), resubmit (Resubmit), revert (Revert Changes), uploaddoc (Upload Document).

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 non-JavaScript 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), addfolder (Add Folder), addmember (Invite Member), addnotes (Add Discussion Forum), addocset (Add Document Set), addrole (Add Role), addSearch (Add Search Folder), addurl (Add URL), addwebfolder (Add Web Folder), chbanner (Change Banner), chrole (Assign Role), copy (Copy), cut (Cut), editdescription (Change Description), editindex (Edit Home Page), editmetadata (Change Attributes), 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), rename (Change Name), uploaddoc (Upload Document).

o goto Inserts the non-JavaScript GoTo menu.

Static: No
Parameters: None

Example:

[element goto]

o history Inserts a list of the documents that were visited last as a list of clickable links.

Static: No
Parameters:

divider (optional)
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)
By default, at most 5 documents will be listed. With the maxdocs parameter you may set a different maximum.

showextensions (optional)
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 search Inserts the input field for the full-text search within the website folder. The search results replace the contents list or tree that were generated using contents or tree. Using search only makes sense if you use contents or tree at the same time, otherwise the search results will not be shown.

Statisch: Nein
Parameter: Keine

Beispiel:

[element search]

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)
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 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.

Static: Yes
Parameters:

Same as for contents.

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’.