5.5.4 Using BSCW elements

Contents

Index

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

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 (cf. 5.5.6). 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.

contents
Inserts a list of all objects contained in the current website folder as clickable links.
Static: Yes
Parameters:
showlayout (optional)
By default, the layout page does not appear in the contents list. You can force this by setting the showlayout parameter.
onlytypes (optional)
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 using the wildcard character ‘*’ (e.g., text/*) is also possible. Folders are not affected by the type filtering.
onlynames (optional)
Works like onlytypes, except that filtering is done on the basis of object names. Specify a comma-separated list of allowed names, e.g. *.html or image??.jpg (‘*’ 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 one time. In this case, only documents that pass both criteria will be displayed.
showfolders (optional)
Determines which folders are shown in addition to the other objects and may have one of the following three values:
- all All folders are shown.
- none No folders are shown.
- webonly Only website folders with an active home page are shown.
sort (optional)
Determines how the contents list is sorted and may have one of the following values:
- byType Objects are sorted by object type.
- byName Objects are sorted by name.
- bySize Objects are sorted by size.
- byDate Objects are sorted by date of last modification.
- byRating Objects are sorted by rating.
If sort is not specified, the current user’s sort criterion for the current folder will be applied.
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.
date
Inserts the current date and/or time.
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 11.5 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.
documentactions
Inserts the non-JavaScript action menu (cf. 4.2.1.3) 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 parameter (cf. below) 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 parameter is 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.
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 llink 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:
addrole (Add Role), attachnote (Attach Note), checkout (Lock), chrole (Assign Role), chtype (Change Type), copy (Copy), cut (Cut), cutattachment (Cut Attachment), duplicate_edit (Edit Copy), edit (Edit), editdescription (Change Description), editmetadata (Change Attributes), editrole (Edit Role), export (Export), firstversion (Start Verion Control), freeze (Freeze), get (Open), history (Show History), info (More Information), link (Link to Clipboard), make (Static Copy), rate (Rate), rename (Change Name), replace (Replace), resubmit (Resubmit).
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 opening 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), adddocument (Add Document), addfolder (Add Folder), addmember (Invite Member), addnotes (Add Discussion), 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), editprop (Change Properties), editrole (Edit Role), 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).
goto
Inserts the non-JavaScript GoTo menu.
Static: No
Parameters: None
Example:
[element goto]
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]
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 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/BSCW44/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”.
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, 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.
systembanner
Inserts the system banner, by default the BSCW system banner with a link to the BSCW help.
Static: No
Parameters: None
Example:
[element systembanner]

Contents

Index

	Help

Contents Index

5.5.4 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. 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 (cf. 5.5.6). 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. contents Inserts a list of all objects contained in the current website folder as clickable links. Static: Yes Parameters: showlayout (optional) By default, the layout page does not appear in the contents list. You can force this by setting the showlayout parameter. onlytypes (optional) 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 using the wildcard character ‘’ (e.g., `text/`) is also possible. Folders are not affected by the type filtering. onlynames (optional) Works like onlytypes, except that filtering is done on the basis of object names. Specify a comma-separated list of allowed names, e.g. `.html` or `image??.jpg` (‘’ 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 one time. In this case, only documents that pass both criteria will be displayed. showfolders (optional) Determines which folders are shown in addition to the other objects and may have one of the following three values: `all` All folders are shown. `none` No folders are shown. `webonly` Only website folders with an active home page are shown. sort (optional) Determines how the contents list is sorted and may have one of the following values: `byType` Objects are sorted by object type. `byName` Objects are sorted by name. `bySize` Objects are sorted by size. `byDate` Objects are sorted by date of last modification. `byRating` Objects are sorted by rating. If sort is not specified, the current user’s sort criterion for the current folder will be applied. 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. date* Inserts the current date and/or time. 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 11.5 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. documentactions Inserts the non-JavaScript action menu (cf. 4.2.1.3) 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 parameter (cf. below) 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 parameter is 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. 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 llink 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: addrole (Add Role), attachnote (Attach Note), checkout (Lock), chrole (Assign Role), chtype (Change Type), copy (Copy), cut (Cut), cutattachment (Cut Attachment), duplicate_edit (Edit Copy), edit (Edit), editdescription (Change Description), editmetadata (Change Attributes), editrole (Edit Role), export (Export), firstversion (Start Verion Control), freeze (Freeze), get (Open), history (Show History), info (More Information), link (Link to Clipboard), make (Static Copy), rate (Rate), rename (Change Name), replace (Replace), resubmit (Resubmit). 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 opening 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), adddocument (Add Document), addfolder (Add Folder), addmember (Invite Member), addnotes (Add Discussion), 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), editprop (Change Properties), editrole (Edit Role), 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). goto Inserts the non-JavaScript GoTo menu. Static: No Parameters: None Example: `[element goto]` 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]` 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 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/BSCW44/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”. 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, 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. systembanner Inserts the system banner, by default the BSCW system banner with a link to the BSCW help. Static: No Parameters: None Example: `[element systembanner]`

Contents Index