SCAN

verion 1.0 – 30 July - Rob Vermeulen
credits:

Pierre van Rooden (NOS) – 7.1 INFO Module

Mark Huijser (EO) - 5 Field-formatting commands

Abstract *

Introduction *

MMBase object cloud *

Separation of Content and Presentation *

How to create a MMBase website *

A Template *

1. The $MOD Command *

2. The LIST Commands *

2.1 List Objects *

2.2 List Relations *

2.3 List Multilevel *

2.4 $ITEML & $ITEMP *

2.5 $PARAM *

2.6 Shorted *

2.7 Where *

2.8 Listloop *

3 IF statement *

4 PART *

5 Field-formatting commands *

5.1 Date/Time *

5.2 Text *

5.3 Other *

6 Problem solving *

Your template gives an incorrect result *

How can i update an out of date webpage if I used CACHE HENK or no MEMCACHE="NO" *

The template does not work *

WHERE in the listing does not work *

7 Modules *

7.1 INFO Module *

7.2 SESSION Module *

7.3 IMAGE Module *

7.5 CALC Module *

7.6 STATS Module *

7.7 CACHE HENK *

Abstract

This document explains SCAN. SCAN is a MMBase scripting language used to publish dynamic content. The VPRO created SCAN to enable web designers to retrieve information from MMBase with a simple syntax. This in contradiction to scripting languages that look similar to programming languages (such as PHP, JSP).

The VPRO is using SCAN now for more than 3 years. SCAN started with a couple of simple commands. Nowadays SCAN is grown to a more complex command set with many possibilities. Unfortunately, this grown has lead to an inconsistent set of commands and that is what makes SCAN difficult.

From August 2001 MMBase contains a MMCI interface that enables more scripting languages to retrieve information from MMBase. A JSP/TAGLIB project is defining a new set of commands that contain the SCAN functionality. The advantage of TAGLIBS is that it is being used widely and that the commands work in a organized structured manner.

For those who want to use SCAN can use this manual. It contains all information available for SCAN.

Introduction

It’s good to have an understanding about how MMBase works before creating a website. This chapter gives the needed background information.

MMBase object cloud

MMBase manages its information as an object cloud. This means that MMBase does not store web pages but pieces of information (objects) and the relations between these pieces of information. e.g. A pinkpop site contains a couple of objects like: artists, audio, video, bands and news items. These objects are related to each other like ‘an artist belongs to a certain band’, or ‘a audio fragment is a single of a band’. Within the MMBase community this set of objects and relations is called the object cloud. This object cloud enables web designers to perform questions like: ‘show me all bands that play at Pinkpop 2000’ or ‘Show me all singles from a certain band’. The exact SCAN syntax will be given in next chapters.

Separation of Content and Presentation

The MMBase object cloud doesn’t contain information about presentation, only data is stored. In this way all data can be published in different ways by using different templates. If content is mixed with the presentation than the following problem appears. e.g. if an article contains an url like this ‘<A HREF=http://www.pinkpop.nl>Pinkpop site</a> than the article will be published correct if HTML is used, but what if this news article is sent to a mobile phone or what if the article is converted to a PDF file. In short, MMBase stores content (without information about the presentation) in the MMBase object cloud. Templates are used to make views on the object cloud. By using different templates, different views can be created.

How to create a MMBase website

A website (a presentation of MMBase information) can be made by creating templates that retrieve information from the MMBase object cloud. E.g. The homepage of the Pinkpop site could be a template with one listing: ‘show all bands related to the Pinkpop event’. The template will be evaluated by MMBase and the internet user will see all the bands that play at Pinkpop. If new bands are added to the Pinkpop event, they will appear at the website. The presentation is stored in the template, the information is retrieved from the MMBase object cloud.

A Template

This document will explain how to create SCAN templates that show pieces of the object cloud in a website. A SCAN template has the extension ‘.shtml’. The webserver knows when it detects a page with the ‘.shtml’ extension that it has to pass the file to MMBase. MMBase will evaluate the template and give it back to the webserver. Instead of SCAN other scripting languages can be used. e.g. if you see a webpage ending in ‘.jsp’ you know that it’s a JSP page, not a SCAN page. Each SCAN page starts with a processor tag. The tag looks like <PROCESSOR MMBASE>

Examples of templates can be found in the html/mmexamples directory of your MMBase system.

1. The $MOD Command

Each object in MMBase has an unique object number. The $MOD command is able to retrieve an object from the object cloud. After retrieving the object you have to specify the field of the object you want to show in your template.

e.g. If the MMBase object cloud contains an artist object, with object number 123. The following commands can be used retrieve the firstname and surname of the artist.

give the firstname of the artist with object number 123.

$MOD-MMBASE-FIELD-123-firstname^

give the surname of the artist with object number 123.

$MOD-MMBASE-FIELD-123-surname^

An object can have relations to other objects. SCAN contains a command to show the number of relations. To publish the number of relations the artist has, the following command can be used.

$MOD-MMBASE-GETRELATIONCOUNT-123^

In some situations you only want to count relations of a certain type. You can retrieve this information by specifying the relation type in the command. This command shows the number of relations the artist has with bands.

$MOD-MMBASE-GETRELATIONCOUNT-123-bands^

2. The LIST Commands

The list commands enables you to create listings in your templates. Listings are:

Show me all bands.
Show me all bands related to the event Pinkpop.
Show me the band, related to the event Pinkpop, that is performing now.

The questions can vary from easy question to more and more complex ones. And believe me, they can become very complex. SCAN contains three listing commands: list objects, list relations, list multilevel. In the next paragraph the differences between the list commands will be explained. All LIST commands have to be placed on one line, so no separation with enters!

2.1 List Objects

List objects enables you to query a list of objects that are all of the same type. The following listing will show the names of the bands present in the object cloud.

The list object command contains a TYPE attribute. The TYPE attribute informs MMBase which objects MMBase has to list. In this example it are band objects. The second attribute is the FIELDS attribute. This attribute informs MMBase which fields you want to display of the object specified by TYPE. $ITEM1 corresponds to the first field listed in the FIELDS attribute. So ITEM1 shows the name of the band.

This tag shows the possible attributes for a list objects command.

Information about the WHERE attribute can be found in paragraph ‘2.7 Where’. DBSORT specifies the field to be sorted. DBDIR specifies if the sorting has to be ascending or descending. MAX specifies a maximal amount of bands you want to see. OFFSET specifies from which band you want to start.

2.2 List Relations

The list relations command enables you to list related objects. e.g. If you want to list all bands that are related to the Pinkpop event you use the list relations command. The command looks like this.

The TYPE attribute is used to specify which related objects you want to see. The FIELDS attribute is used to show which fields you want to display. The NODE attribute is used to indicate the object from which you want to search the relations. Object number 123 corresponds (in this case) to the object number of the Pinkpop event.

The attributes for sorting differ from the list objects attribute. The list relations attributes are:

Instead of using DBSORT the list relations command uses SORTED. SORTED can be set to ALPHA if only one fieldname in the FIELDS attribute is listed. If there is only one field listed, SCAN will sort on that field. If more fieldnames are specified in the FIELDS attribute than you have to use SORTED="MALPHA". SORTPOS is used to indicate which field has to be sorted. SORTPOS starts counting from 0, so if you want to sort on the second fieldname use SORTPOS="1".

This query shows five bands that perform at the Pinkpop event. The list is also sorted on the name of the bands. b.t.w. First the list will be sorted and that the first five items will be taken.

2.3 List Multilevel

The list multilevel command is the most extensive one and in most cases this command will be used. The list multilevel command enables you to make ‘chains’ of information. The next example will show all audio fragments of all the bands that perform at Pinkpop.

<LIST MULTILEVEL TYPE="event,bands,audio" NODE="123"

FIELDS="bands.name,audio.title" VERSION="2.0" MEMCACHE="NO">

Audio fragment of $ITEM1 : $ITEM2

</LIST>

The TYPE attribute contains a ‘chain’ of object types. The NODE attribute specifies what the starting point of the chain is. The list command starts with an event (see TYPE attribute). This event has object number 123, this is specified with the NODE attribute. So the list command lists all bands related to Pinkpop and of all the bands all related audio is listed. The FIELDS attribute specifies the fields you want to use in the template. The VERSION attribute is, uhhh, just needed. The list multilevel commands enables you to make complicated queries, that’s why the list multilevel command is cached! If you want to create very dynamic webpages you maybe want to disable the caching, this can be down by the MEMCACHE attribute.

b.t.w.1 If you didn’t specify MEMCACHE="NO" and you want the webpage to be updated, you can do the following trick.

go to the MMBase editors.
Select the N in the right top of the editor, the N will change in a R. (N means No reload, R means Reload).
Reload the webpage with your browser, the updated information will be showed.

b.t.w.2 The attribute NODE informs the list multilevel command about the starting point of the chain. In the above example we used object number 123 this indicates that the Pinkpop event is the starting point of the query. If you want to use more starting points, you can specify the starting points in the NODE attribute comma separated. e.g. NODE="123,234,345". If you want to use all events as a starting point you can use NODE="-1".

b.t.w.3 If you want to use two times the same object types in a multilevel you can index the object type:

<LIST MULTILEVEL type="bands1,bands2" node="-1" fields="bands1.name, bands2.name">

Sorting fields with list multilevel can be done in the same way as sorting with the list objects command. This are all the attributes of the list multilevel command:

<LIST MULTILVEL TYPE="(objectnames)" FIELDS="(fieldnames)"

[WHERE="where (sql where)"]

[DBSORT="fieldname" [DBDIR="(DOWN|UP)]]

[MAX="(number)"]

[OFFSET="(number)"]

[MEMCACHE="NO"]

[DISTINCT="YES"]

>

2.4 $ITEML & $ITEMP

Within your list tag you are able to use the following commands.

$ITEML

$ITEMP

</LIST>

In this example $ITEML shows the total amount of bands. $ITEMP shows the current position of the bands that are returned.

2.5 $PARAM

The previous paragraphs showed that some commands need the NODE attribute which specifies the starting point for the listing commands. Previous examples were using NODE="123" which indicated that the starting point was the Pinkpop event. Normally you don’t fill in the object number, but that value is given by a $PARAM. A parameter is a value that can be passed to a webpage as an attribute in the URL. e.g.

http://www.vpro.nl/pinkpop.shtml?123+param2+234 is an url with three parameters. If you request that page MMBase will evaluate that webpage. In the pinkpop.shtml webpage there will be three variables, namely: $PARAM1, $PARAM2 and $PARAM3. So instead of using NODE="123" you will use NODE="$PARAM1" in this way the node variable is filled in dynamically. And in that way the template can be used for different festivals and not only the festival starting with NODE="123".

2.6 Shorted

When using the list commands you can get the word $SHORTED in your webpage. $SHORTED means that the list command does not give you the value you asked for. This is done to prevent that very large objects are loaded in MMBase. The next list command will show this.

The text of the newsarticlewith item2: $ITEM2 <BR>

The test of the newsarticle with mod: $MOD-MMBASE-FIELD-$ITEM1 <BR>

</LIST>

This list command can result in the next output:

The text of the newsarticlewith item2: $SHORTED

The test of the newsarticle with mod: Pinkpop is een jaarlijks terugkerend event. Het ……………

2.7 Where

The WHERE attribute can have two forms. The ‘normal’ form is an own created form. The second one gives the possibility to specify a SQL like constraint. This first example shows the ‘own’ created where.

<LIST OBJECTS TYPE="bands" FIELDS="name,description" WHERE="name=EProdigy">

Information about the band Prodigy

$ITEM2

</LIST>

WHERE="name=EProdigy" means that the name of the band has to be Equal to Prodigy. Another operator that can be used is ‘=N’ which means ‘is not equals to’.

If ‘where’ is added in the WHERE attribute a SQL like syntax can be used. The following example shows this.

<LIST OBJECTS TYPE="bands" FIELDS="name,description"

WHERE="where name=’Prodigy’">

Information about the band Prodigy

$ITEM2

</LIST>

Be careful, you can never use a > (greater than) sign in your where statement. MMBase evaluates the ‘>’ sign as if it is the end of the list command. So instead of using A > B use B < A. This of course is a bug.

2.8 Listloop

The listloop commands allows you to create headers and footers for list output. It defines the block to handle when iterating through a list. All other statements in a LIST are scanned only once.

The following list command:

<LIST MULTILEVEL TYPE="event,bands" NODE="123" FIELDS="bands.name">

These list shows all bands performing at Pinkpop

<LISTLOOP>

$ITEM1

</LISTLOOP>

This is the end of the list.

</LIST>

3 IF statement

The ‘if’ statement enables you to use conditions in templates. e.g. According to the amount of bands that are related to an event a different layout can be used. The following example will show this.

<IF $MOD-MMBASE-GETRELATIONCOUNT-123-bands^=L10>

There are less than 10 bands related, so show this layout.

<ELSE>

There are more than 10 bands related, so show this layout.

</IF>

The values to compare can consists of other SCAN commands (as the example above), typed text and numerical values. While creating an IF statement you can also use the boolean operators OR an AND.

Numerical operators:

=E, equals

=N, not equals

=H, Higher than

=L, Less than

=A, Greater or Equal than

=M, Less or Equal than

String operators:

=E, equals

=N, not equals

=C, equals (case insensitive)

The next example shows an if statement in a list command. If an if statement is used within a list command the first IF words is changed to LIF, the ending IF stays an IF!

<LIST OBJECT TYPE="bands" FIELDS="name" MAX="20">

Bandname: ITEM1

<LIF $ITEMP=E$ITEML>

next 20 bands

</IF>

</LIST>

4 PART

A part includes another .shtml page into the template. In this way you can keep your templates small. Another useful function of PART if when you want to nest list commands. Nesting of list commando’s in one .shtml page is not possible. By using a PART within a list commando you can achieve nesting of listings. The following example will show this.

pinkpop.shtml

<LIST MULTILEVEL TYPE="event,bands" NODE="123" FIELDS="bands.number,bands.title">

The band $ITEM2 has the following artists:

<PART /showArtistsOfABand.shtml?$ITEM1>

</LIST>
showArtistsOfABand.shtml

<LIST MULTILEVEL TYPE="bands,artists" NODE="$PARAM1"

FIELDS="artists.name">

$ITEM1

</LIST>

5 Field-formatting commands

The following formatting commands can be useful within your $MOD-MMBASE-FIELD-... command. You also can use these commands in the FIELDS-list within your LIST MULTILEVEL, LIST RELATIONS or LIST OBJECTS. Don't use these commands inside the WHERE-clause of a LIST. It won't work.

Here are two examples of how the commands work. These two will output exactly the same thing.

Example 1:

<LIST OBJECTS TYPE="mmevents" NODE="-1"

FIELDS="number,shorted(name),date(start),date(stop)">

$ITEM2

$ITEM3

$ITEM4

</LIST>
Example 2:

<LIST OBJECTS TYPE="mmevents" NODE="-1" FIELDS="number">

$MOD-MMBASE-FIELD-$ITEM1-shorted(name)^

$MOD-MMBASE-FIELD-$ITEM1-date(start)^

$MOD-MMBASE-FIELD-$ITEM1-date(stop)^

</LIST>

5.1 Date/Time

All of the Date/Time formatting commands need a "fieldname" as function parameter. Be sure to fieldname which contains an integer (epoch-time number in seconds since 1970).

Date/Time formatting commands are:

date(<fieldname>)

Formats the specified field of the specified object to a date in the format hh:mm:ss dd/mm/yyyy

time(<fieldname>)

Formats the specified field of the specified object to a time in the format hh:mm

timesec(<fieldname>)

Formats the specified field of the specified object to a time in the format hh:mm:ss

longmonth(<fieldname>)

Formats the specified field of the specified object to the name of month.

monthnumber(<fieldname>)

Formats the specified field of the specified object to the number of month.

month(<fieldname>)

Formats the specified field of object to the abbreviation of month.

weekday(<fieldname>)

Formats the specified field of the specified object to name of the day of the week

shortday(<fieldname>)

Formats the specified field of the specified object to an abbreviation of the name of the day of the week

day(<fieldname>)

Formats the specified field of the specified object to the number of the day of the week

shortday(<fieldname>)

Formats the specified field of the specified object to an abbreviation of the name of the day of the week

shortyear(<fieldname>)

Formats the specified field of the specified object to a two-digit abbreviation of the year

year(<fieldname>)

Formats the specified field of the specified object to a four-digit representation of the year

thisdaycurtime(<fieldname>)

Formats the specified field of the specified object to the beginning of that day (00:00). Output is (again) epoch-time. (!) Tested this one in the Netherlands, where we are 1 hour ahead (summertime), my test resulted in (01:00).

5.2 Text

All of these text conversion and formatting commands need a "fieldname" as function parameter. Be sure to use a fieldname which contains a text string.

Text conversion and formatting commands are:

wap(<fieldname>)

Formats the specified (text)field in a special way to support WAP.

html(<fieldname>)

Formats the specified (text)field in a special way for html-support. html() substitutes one newline by <br /> and two newlines by <p> </p>.

shorted(<fieldname>)

Just displays the first 32 characters of the specified text field, and appends "..." to the result.

uppercase(<fieldname>)

Formats the specified field to uppercase characters.

lowercase(<fieldname>)

Formats the specified field to lowercase characters.

hostname(<fieldname>)

Strips the hostname (e.g. www.mmbase.org) from the specified field. This will *only* work if the specified text field is of the format http://<hostname>/<whatever>.

wrap(<fieldname>;<width>)

Will output the specified text field wrapped to the specified width. <width> is the maximum number of characters on a line. Wrap just inserts newlines all through the text to fit the text to the desired width. So,

using wrap in your html-template will not have the desired effect. In this case you will need to combine

the html() and wrap() command.

substring(<fieldname>,<length>[,filler-string])

substring() will take a substring of the specified length from the beginning of the specified textfield. The end of the substring will be replaced by the optional fillerstring.

5.3 Other
age()

Will return the age of the specified object. No function parameters are needed. Example: $ MOD-MMBASE-FIELD-777-age()^

gui([fieldname])

gui() should return the gui-name of the field that is specified. If no field specified, gui() will return the gui-name of the node. I tried to test this one, but I couldn't get it working :-(

6 Problem solving
Your template gives an incorrect result

Maybe the information in your page is cached. The list multilevel caches it’s information or if you use cache henk your information will be cached.

How can I update an out of date webpage if I used CACHE HENK or no MEMCACHE="NO"

Open the MMBase editors
Click on the N in the right top of your screen. It will change to a R.
Open the webpage you want to update and reload the page (maybe with shift-reload).

The template does not work

Is the extension of the template ‘.shtml’ and does your template begin with the <PROCESSOR MMBASE> tag?

If you use list commands check your logfile, you probably made a typing error.

WHERE in the listing does not work

You can never use a > (greater than) sign in your where statement. MMBase evaluates the ‘>’ sign as if it is the end of the list command. So instead of using A > B use B < A. This of course is a bug.

7 Modules
7.1 INFO Module

The INFO module supplies SCAN with the possibilities to query the underlying server for data concerning the system or the current user. Most of its functions have their counterparts in other scripting languages (with a few exceptions). Information retrieved include system colors, server settings, user properties, or various miscellaneous functions such as retrieval of time or random numbers.

This document describes the INFO commands.

LIST commands:

$MOD commands:

$MOD-INFO-BROWSER

$MOD-INFO-DECODE

$MOD-INFO-ENCODE

$MOD-INFO-ESCAPE

$MOD-INFO-EXISTS

$MOD-INFO-MEMORY

$MOD-INFO-MOVE

$MOD-INFO-OS

$MOD-INFO-RANDOM

$MOD-INFO-RELTIME

$MOD-INFO-STRING

$MOD-INFO-STRINGCMP

$MOD-INFO-TIME

$MOD-INFO-TIMEFORMAT

$MOD-INFO-TIMEFORMATSEC

$MOD-INFO-USER

7.1.1 LIST commands

The syntax of a INFO list command is : <LIST command PROCESSOR="INFO" parameters >.

The lists supplied by INFO return lists of colors, numerical ranges, and file dates.

This command returns a list of colors and their corresponding RGB values. It's syntax is:

<LIST COLOR[-(SPECTRUM|BASIC)] ITEMS="2" PROCESSOR="INFO">

SPECTRUM (the default) returns a list of primary and secondary colors (8 colors, including black and white).

BASIC returns a list of basic RGB colors (black, white, red, green, blue), as well as mint green and mint blue.

The list returned contains sets of two items each:

$ITEM1 : the color name

$ITEM2 : the RGB value

This command returns a list of values within a specified range.

It's syntax is:

<LIST RANGE[-start[-end[-step]]] ITEMS="1" PROCESSOR="INFO"> or

<LIST RANGE-ALPHA ITEMS="1" PROCESSOR="INFO">

If 'ALPHA' is requested, the list returns the characters of the alphabet ('A' through 'Z').

Otherwise, it will return a list of numerical values, starting at [start], and ending on [end], with a [step] interval.

For instance, RANGE-0-20-5 returns 0,5,10,15,20.

The defaults for start, end and step are 1, 10, and 1.

The list returned contains only singular values:

$ITEM1 : the character or numerical value

This command returns the creation dates of all directories with a length of 10 characters that can be found within a given path, and whose creation date falls within a specified range.

It's syntax is:

START, END, STARTINCLUDED and ENDINCLUDED limit the range of dates to return. REVERS affects the sort order of the dates (ascending if FALSE, descending if TRUE).

This command is very specific and use of it is encouraged, as it is unsure whether it will be supported in the future.

The list returned contains sets of four items each:

$ITEM1 : the date in YYYY-MM-DD format

$ITEM2 : the name of the month (in Dutch)

$ITEM3 : the day of the month

$ITEM4 : the day of the week (in Dutch)

7.1.2 $MOD commands

INFO's $MOD commands are very extensive, and return information on the system, the time, the user, anD the user's browser. It also hold a number of functions used for manipulating text or numbers.

Most of these functions have equivalents on other scripting languages.

$MOD-INFO-BROWSER

This command returns information on the type and properties of the user's browser.

It's syntax is:

NAME (the default) returns the name of the current browser. Equivalent to $MOD-BROWSER-HTTP-User-Agent. WANTEDHOST returns the host's name. Equivalent to $MOD-BROWSER-HTTP-Host. OS retrieves the operating system name (as $MOD-INFO-OS). HTTP returns the value of header in the HTTP-header of the user's request (i.e. Referrer or Pragma). NETSCAPE : returns YES if the current browser is Netscape navigator (NO otherwise). MSIE returns YES if the current browser is internet explorer.

The default command executed is NAME.

$MOD-INFO-DECODE

This command converts an URL-encoded string to its unencoded format.

It's syntax is:

$MOD-INFO-DECODE-string

Any sequence of the form %XX, with XX being an hexadecimal value, is converted into its corresponding ASCII value.

See $MOD-INFO-ENCODE below.

$MOD-INFO-ENCODE

This command converts an URL-encoded string back to its unencoded format.

It's syntax is:

$MOD-INFO-ENCODE-string

The value 'string' may contain any characters except the space. It is converted to a URL-endoced string, which can then be passed as an argument. This allows the system to pass arguments which contain otherwise illegal symbols such '+' (normally used to separate arguments), or URL-specific characters such as '#', '?', etc.

$MOD-INFO-ESCAPE

This command replaces single quotes (') in a string by an escape sequence.

It's syntax is:

$MOD-INFO-ESCAPE-string

Any occurrence of a single quote (') is replaced by two single quotes (''). This allows using a value within a single-quote string delimiter, such as in javascript or tag values.

Note though that the official way to delimit a tag value is by using double quotes (").

$MOD-INFO-EXISTS

This command tests whether a given file exists on the system.

It's syntax is:

$MOD-INFO-EXISTS-(DIR|PATH|FILE)-filename

DIR checks whether a given filename exists as a directory. FILE checks whether a given filename exists as a file. PATH checks whether a given filename exists as a path (either a directory or a file).

The value returned is YES if successful, NO if the check fails. Note that the filepath cannot include the '-' sign, which is used in the $MOD command syntax.

$MOD-INFO-MEMORY

This command retrieves free available memory.

It's syntax is:

$MOD-INFO-MEMORY[-(GETJVM|GETSYS)[-(B|KB|MB)]]

The command GETJVM retrieves the free memory in the Java Virtual Machine. The command GETSYS retrieves the free memory in the system. The commands B, KB, and MB determine

whether the free memory is shown in bytes, kilo bytes, or megabytes. The default is to get the JVM memory in bytes.

$MOD-INFO-MOVE

This command moves a file from one place on the system to another.

It's syntax is:

$MOD-INFO-MOVE-fromfilename-tofilename

The file with the path and name fromfilename is moved to the destination indicated by tofilename. Obviously this command should be handled with some care. Note that the filepaths cannot include the '-' sign, which is used in the $MOD command syntax.

$MOD-INFO-OS

This command returns the name of the user's Operating System.

It's syntax is:

$MOD-INFO-OS

This command takes no arguments.

$MOD-INFO-RANDOM

This command returns a random number.

It's syntax is:

$MOD-INFO-RANDOM-start-end

The command arguments are the start and end of the numerical range in which the random number should fall.

Not specifying either returns 0.

$MOD-INFO-RELTIME

This command returns a part of a given relative time value.

It's syntax is:

$MOD-INFO-RELTIME-(GET[TIME]|GETHOURS|GETMINUTES|GETSECONDS|GETMILLIS)-timevalue or

$MOD-INFO-RELTIME-COUNTMILLIS-HH-mm-ss-SSS

The first version of this command returns the time (HH:mm:ss:SSS), or the hours, minutes, seconds, or milliseconds part left in the indicated time value (the total of milliseconds that passed).

The second version converts an timeformat (HH:mm:ss:SSS) into the total nr of milliseconds.

$MOD-INFO-STRING and $MOD-INFO-STRINGCMP

Compares two strings.

It's syntax is:

This call tests two strings. The STRING command returns true if the test succeeds, and false if it fails.

STRINGCMP returns the same results as the values YES or NO.

The command requires one of the following commands :

EQUALS test whether string1 and string2 are the same.

STARTSWITH or LEFTSTRING test whether string1 starts with the contents of string2, using an optional value x as an offset for the search position in string1.

ENDSWITH or RIGHTSTRING test whether string1 ends with the contents of string2.

INDEXOF or CONTAINS test whether the contents of string2 is somewhere in string1.

$MOD-INFO-TIME

This command returns a part of the current time (or an offset thereof) in a specified format.

It's syntax is:

$MOD-INFO-TIME[-timevalue][-(NAME|ENGLISH|DUTCH|DUTCHNAME|NUMBER)][-timepart]

The command optionally takes a timevalue as input. The value is expected to be in seconds. By default, the current time will be used.

The next optional part determines the format in which certain elements are returned.

If NAME or ENGLISH are specified, months or weekdays are given in English. |

DUTCH or DUTCHNAME results in Dutch texts.

NUMBER (the default) returns months and weekdays as numeric values.

The last part of the command determines what part of the time is returned.

The specified timepart can be one of the following values:

Command	Result
TIME	the time in HH:MM format. (i.e. 12:30)
YEAR	the year including century part (i.e.2001)
SHORTYEAR	the year without century part (i.e. 01)
MONTH	The month in either numeric or 'long' format (i.e. 1 or January)
SHORTMONTH	The month in either numeric or 'short' format (i.e. 1 or jan)
MONTHS or SHORTMONTHS	Returns the number of months since the epoch (i.e. 370) The specified format should be NUMBER.
MONTHS-YEAR-x or SHORTMONTHS-YEAR-x	Returns the year in which the xth month falls, counting from 1970 (i.e. 1978) The specified format can not be NUMBER.
MONTHS-MONTH-x or MONTHS-x	Returns the (long) name of the xth month, counting from 1970 (i.e. March) The specified format can not be NUMBER
SHORTMONTHS-MONTH-x	Returns the (short) name of the xth month, counting from 1970 (i.e. Mar) The specified format can not be NUMBER.
SHORTMONTHS-x	Returns the (short) name of the xth month, counting from 1970, with the year following,( i.e. Mar 1971) The specified format can not be NUMBER
WEEK	The number of the week in the current year, not counting partial weeks.
PREVWEEK	Number of the previous week
NEXTWEEK	Number of the next week
WEEKDATE-x	Date of the xth day of this week (i.e. 18 November). For some reason this doesn't match.
NEXTWEEKDATE-x	Date of the xth day of the next week (i.e. 25 November)
WEEKCURTIME	Returns a timevalue in seconds, counted from the first day of the week
WEEKOFYEAR	The number of the week in the current year including partial weeks
WEEKOFMONTH	The number of the week in the current month
DAY or DAYOFMONTH	The number of the day in the current month
WEEKDAY or DAYOFWEEK	The number or the (long) name of the day of the week ( i.e. Tuesday)
SHORTDAYOFWEEK	The number or the short name of the day of the week ( i.e. Tue)
DAYOFWEEKINMONTH	The number or the ordinal day of the week in the month (i.e.5)
YDAY or DAYOFYEAR	The day of the year (i.e. 235)
HOUR	The hour of the morning or afternoon (i.e. 4)
HOUROFDAY	The hour of the day (i.e. 16)
MIN	The minutes
SEC	The seconds
CURTIME	The current time in seconds (timevalue and format are ignored)
DCURTIME	The current time in seconds (timevalue and format are ignored)
CURTIME10	The current time in sections of 10 seconds (timevalue and format are ignored)
CURTIME20	The current time in sections of 20 seconds (timevalue and format are ignored)
(none)	Not specifying a command returns the date and time using the default system settings.

$MOD-INFO-TIMEFORMAT and $MOD-INFO-TIMEFORMATSEC

Formats either the current or a given timevalue according to a specified format.

It's syntax is:

$MOD-INFO-TIMEFORMAT[-timevalue][-format]

$MOD-INFO-TIMEFORMATSEC[-timevalue][-format]

The timevalue is optional. If not given, the current time is used. The TIMEFORMATSEC command expects a timevalue in seconds, the TIMEFORMAT command expects a timevalue in milliseconds.

The format can contain the following symbols: h: hours, H:hour of the day, m: minutes, s: seconds, S: milliseconds, _ (underscore): space.

The default format is HH:mm:ss.

$MOD-INFO-USER

Retrieves information on the current user.

It's syntax is:

This call returns info from the user.

NAME (the default), returns the username.

HOSTNAME returns the name of the remote (visiting) host

IPNUMBER returns the ipnumber of the remote host

SECLEVEL returns the current security level

REQUEST_URI returns the path of the file requested.

BACK returns the URL of the page visited before the current page. Equivalent to $MOD-BROWSER-HTTP-Referrer.

COUNTRY returns the country of the remote host.

DOMAIN returns the domain name of the remote host.

INDOMAIN returns YES when the remote host has the same domain as the current one. Otherwise it returns NO.

7.2 SESSION Module

By using the SESSION module, you're able to remember information that belongs to a user who requests a certain page. For example, if someone tells you he likes jazz music, you can relate that information to that user.

The following command will set the value jazz by the session name FAVORATE_MUSIC.

<DO SESSION-FAVORATE_MUSIC=jazz>

If the same person goes to another page, you can display this information by using the command.

$SESSION-FAVORATE_MUSIC

The <DO SESSION-FAVORATE_MUSIC=jazz> remembers the information in the memory of the computer. If you want to save this information, you have to use the command:

<SAVE SESSION-FAVORATE_MUSIC>

A session variable can contain a set of variables. e.g. If you want to remember all persons selected by somebody. it's possible to create a SESSION variable called PERSONS that contains a set of persons. The following commands manipulate this set:

$MOD-SESSION-CLEARSET-PERSONS delete all persons from the set.

$MOD-SESSION-DELSET-PERSONS-HENK deletes HENK from the set PERSONS.

$MOD-SESSION-ADDSET-PERSONS-HENK adds the value HENK to the set PERSON, if HENK already exists nothing is done.

$MOD-SESSION-PUTSET-PERSONS-HENK adds the value HENK to the set PERSON, regardless if HENK already exists it will be inserted.

$MOD-SESSION-SETSTRING-PERSONS gives all elements of the set PERSONS (comma separated)

$MOD-SESSION-CONTAINSSET-PERSONS-HENK, return "YES" if HENK consists in the set PERSONS, otherwise "NO" will be returned.

$MOD-SESSION-SETCOUNT-HENK, will return the numbers of values in the set PERSONS.

$MOD-SESSION-AVGSET-HENK, will calculate the average of all values in the set (the values have to be numbers!).

By using the following FORM in your HTML page the session variables can be set. See the NAME attribute of the INPUT tag.

7.3 IMAGE Module

Images can be received form MMBase by placing the following tag in your template:

<IMG name="Blabla" SRC="http://www.mmbase.org/img.db?objectnumber>

The first time the image is requested it will take some time, because the image has to be rendered to the wanted format. The second time the image is requested the image in will be received from a cache.

The location of your internet browser will point at http://www.mmbase.org/img.db?1045+s(600x600)

This means that the image with object number 1045 will be displayed (MMBase logo) and that the size of the

image has to fit in a box of 600 by 600 pixels. Images can be rendered in a lot of ways. This paragraph will show some commands. Play with them and see what happens.

Scaling with one value:

http://www.mmbase.org/img.db?1045+s(100)

Scaling with two values:

http://www.mmbase.org/img.db?1045+s(60x50)

Resize:

http://www.mmbase.org/img.db?1045+s(380!x10!)

This will be the size of the image.

format:

http://www.mmbase.org/img.db?1045+f(gif)

The image will be displayed as gif, use e.g. jpeg if you don't want to display animated gifs.

modulate:

http://www.mmbase.org/img.db?1045+modulate(0,-100,0)

The modulate command is always followed by 3 numbers between brackets. The numbers stand for brightness [-100,100], saturation [-100,100] and hue [-100, 100]. Here are a few examples; try your own combinations.

border:

http://www.mmbase.org/img.db?1045+bordercolor(000000)+border(3x20)

part:

http://www.mmbase.org/img.db?1045+part(0x0x150x150)

This is the same as the crop filter. The first two numbers are coordinates for a beginning point (y,x), the other two for the end point.

roll:

http://www.mmbase.org/img.db?1045+roll(60x20)

This is just like Photoshop's wrap filter. The number indicates the horizontal value, the second gives the vertical value.

mirror:

http://www.mmbase.org/img.db?1045+flipx

http://www.mmbase.org/img.db?1045+flipy

rotate:

http://www.mmbase.org/img.db?1045+r(90)

some more:

http://www.mmbase.org/img.db?1045+wave(30)

http://www.mmbase.org/img.db?1045+swirl(200)

http://www.mmbase.org/img.db?1045+shear(30)

http://www.mmbase.org/img.db?1045+raise(20)

See the ImageMagic documentation for more possibilities.

7.5 CALC Module

By using the CALC module you are able to perform calculations. The module implements a simple LL(1)

grammar to calculate simple expressions with the basic operations +,-,*,/, and brackets.

The syntax is as follows:

$MOD-CALC-(expression)

Where expression can be something like (5+5)*8-3/5.

7.6 STATS Module

By using the STATS module, you're able to set markers in your HMTL pages. Each time the page is requested the marker will be increased by one.

You can set a marker in your HTML page by using the command:

$MOD-STATS-ADDCOUNT-[number of your marker].

To get the number of page views just use the command:

$MOD-STATS-GETCOUNT-[number of your marker]

7.7 CACHE HENK

By placing <CACHE HENK> in your ‘.shtml’ page, the page will be cached and not recalculated each time.

Syntax <CACHE HENK n>: n not specified expires in 6 hours, n as number expires in n seconds, n as NOEXPIRE does not expire

Before you can use the <CACHE HENK> tag, the CACHE module has to be installed.