Macros and methods

To organize your scripts, we offer Macros and Methods. Both contain small pieces of logic, comparable with functions in JavaScript, or Python.

They are useful to isolate pieces of logic that can be used in more than one context. Both can be managed from the backstage.

Macros

Macros can only be used in Velocity. A macro can be called with parameters, but does not return a value. The output from the macro can be printed or assigned to a variable. They are mainly used in templating. Suppose you have a macro like:

Name	myMacro
Parameters	$thing
Content	Hello $thing

 

You can call this macro from another script, like:

#myMacro('world')

The output will be:

Hello world

You can also do:

#set($output = "#myMacro('world')")
$output

The result will be the same, but in this case you can process $output any way you like.

Trailing whitespaces

When printing a macro a whitespace appears behind the output of the macro. This is due to the way the Velocity engines evaluates macro's. Often this isn't an issue. However, when you have a macro like this:

Name	reader
Parameters
Content	$record.get('reader')

When trying to use it in an e-mail like this:

Dear #readerMacro,

It will be evaluated to:

Dear CrossmarX ,

To fix this, simply append a Velocity comment to the end of the content of the macro as follows:

Name	reader
Parameters
Content	$record.get('reader')##

Some notes:

1. A macro has access to all variables in the current velocity context. So variables do not have to passed as parameters, but it is good practice to do so.
2. After execution of the macro the variables created in the macro remain available in the current velocity context. 
3. A macro can be called with less parameters than defined, the remaining parameters will be consiered as null 
4. Macros are automatically stored in a file called macros.pm. This file can not be edited.

 

Methods

Methods can be used in JavaScript and Velocity. A method can be called with parameters and returns a value. Methods are used when a single value must be calculated. There are two types of methods:

• static methods
  Do not belong to a class and can be called from any script.
  
  
• instance methods
  Belong to a class and can be called on a record of that class.

Static methods

Suppose you have a method like:

Name	myMethod
Parameters	$thing
Content	#set($return = "Hello $thing")

 

You can call this method from another script in Velocity, like:

$methods.myMethod("world")

In JavaScript this will be:

Methods.myMethod("world");

The output will be:

Hello world

You can also do:

#set($output = $methods.myMethod('world'))
$output

The output will be the same, but in this case you can process $output any way you like.

Instance methods

Suppose you have a method like:

Name	myMethod
Class	organisation
Parameters	$greeting
Content	#set($return = "$greeting $this.getLabel()")

 

You can call this method from another script on a record of the class 'organisation', like:

#set($organisation = $session.getRecord('organisation', 1))
$organisation.myMethod('Hello')

The output will be:

Hello CrossmarX

The value returned by a method can also be assigned to a variable by doing this:

#set($output = $organisation.myMethod('Hello'))
$output

The output will be the same, but in this case you can process $output any way you like.

It is not possible to overwrite existing methods of the class Record or any class that inherits from it. For instance, a new method called 'get' would conflict with the existing get() method of the class Record. Making a method that has the name of an existing method of Record will either make it impossible to save the method, or the new method cannot be called. See the Velocity API for the existing methods of Record and EditableRecord when using Velocity and the Scripting API for existing methods of Record when using JavaScript.

 

Permissions

Suppose you want to show a specific part of a Velocity page to a certain user group, but you don't want that other user groups see that part of the page. This part of the page might be related to a specific clazz that only specific users should see. In Velocity, it's possible to use the 'Permission' module to accomplish this task. 

 

To get the information about the permissions, you will need the "PermissionInfo" object:

#set($permissionInfo = $session.getPermissionInfo)

Suppose you have a Clazz named 'Shop' and in the backstage you have set the read permission for anonymous users to 'No', but the read permission for users of the usergroup 'Customer' is set to 'Yes'. The part of the page will be shown based on the user's session:

## ... other page components

#if($permissionInfo.getInsertPermission($shop).get().isPermitted())
    ## show shop page components...
#end

The method 'getInsertPermission' returns an 'ExplainedPermission' object. This object is a combination of a permission and an explanation. Using the method 'get' on this object will return a new object called 'Permission'. With the 'Permission' object you can call the method 'mightBePermitted' which will return true on every value except 'no'. The method 'isPermitted' will return true on the following values: 'yes', 'hidden yes', 'primary', 'secondary' and 'required'.

 

The ExplainedPermission class

The 'ExplainedPermission' class contains both a permission and an explanation of a permission. The class contains two methods:

• get
• getExplanationAsSingleString

The first method named 'get' returns the Permission object that the ExplainedPermission object contains. The second method named 'getExplanationAsSingleString' returns the explanation related to the 'ExplainedPermission' object. 

 

The Permission class

The 'Permission' class contains many permission values. All the available values are:

• no
• yes
• hidden yes
• cascading
• user_related
• helper
• read_only
• required
• primary
• secondary
• undefined

The 'Permission' class also consists of three methods. Those methods are:

• isNotPermitted
• isPermitted
• mightBePermitted

The first method, 'isNotPermitted', checks if the user does not have the specified clazz permission. Only the permission value 'no' returns true. The second method 'isPermitted' returns true on the following values: 'yes', 'hidden yes', 'primary', 'secondary' and 'required'. The third method 'mightBePermitted' is the opposite of the method 'isNotPermitted'. The method 'mightBePermitted' returns true on all values except 'no'.

 

Note: using !isPermitted and isNotPermitted do not give the same results. The method 'isNotPermitted' will only return true on the value 'no', but the method usage '!isPermitted' will return true on the values: 'no', 'cascading', 'user_related', 'helper', 'read_only' and 'undefined'.