Using BSCW elements

Website folders have a built-in element system with a wiki-like [element …] syntax, al­low­ing 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 ele­ments 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 dif­fer from their usual names in BSCW. Examples are Revert Changes instead of Destroy Ver­sions 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 ex­pected.

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 web­site 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 in­sert­ed 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 speci­fied 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 char­ac­ter). 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 ap­pear in the con­tents list. You can force their appearance by setting the re­spec­tive 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 follow­ing 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 speci­fied, 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 brow­ser win­dow.

[element contents target="application/pdf:_blank"] 
Causes all PDF documents of the contents list to be opened in a new brow­ser win­dow.

[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 administra­tor. You can obtain a list of the metadata keys of a given metadata profile selecting action  Specification  in the action menu of the metadata profile.

o  contentsmetatable Inserts a table of selected metadata of all objects directly con­tain­ed 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 action  Specification  in the action menu of the metadata profile. For examples of metadata keys also see con­tents 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 de­scrip­tion 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 para­meter.

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 fol­der as a table with name, tags and description columns.

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 cur­rent document or a direct link to a speci­fic 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 val­ues of the action parameter. If the action specified is not allowed for the cur­rent user, the documentactions element will be replaced by the value of the for­biddentext 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 para­meter 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 para­meter 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 con­dition is not satisfied, the whole element remains empty. The value of the para­meter 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_be­ginner, profile_ui_advanced, profile_ui_expert). The level of pro­ficiency 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 ele­ments 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), cut­attachment (Cut Attachment), duplicate_edit (Edit Copy), edit (Edit), editobject (Change Pro­per­ties), export (Export), freeze (Freeze), get (Open), history (Show History), info (More In­for­mation), link (Link to Clipboard), print­web (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 web­site fol­der 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 ob­jects 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 Dis­cussion Forum),addpage (Add Page), addsub­web­folder (Add Fol­der), addrole (Add Role), addSearch (Add Search Folder), addurl (Add URL), chbanner (Change Banner), chrole (Assign Role), copy (Copy), cut (Cut), edit­index (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), his­to­ry (Show His­tory), info (More Information), link (Link to Clipboard), make (Static Copy) pub­access (Public Access), uploaddoc (Up­load Do­cument).

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 modifica­tion.    

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 pre­ferred 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 lo­cation of this file in your particular BSCW installation.

Example:

[element message name=location]  
Displays the message named ‘location’. In English, this yields “Your loca­tion”.

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, other­wise 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 con­tains 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 para­meter 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 ob­ject 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 click­able 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 docu­ment 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 con­tents.

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 sub­sidiary 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’.