VTL reference

Plain keywords represent actual names of properties or methods, while keywords in italic stand for user variables and indicate their type.

The r and w tags mean that an attribute is readable and/or writable (in the sense of the Velocity template language, i.e. an attribute is read by referencing it, and modified using the #set directive).

All methods that take a values_map as argument are quite convenient to use with the $query variable (that contains all the HTTP query parameters) when coming from an HTML form : you only have to ensure that the names of HTML input fields map correctly to the names of the corresponding table columns.

1. Database attributes and methods :

$db.entity_name r : entity.

• #foreach($u in $db.user) user name : $u.name #end
• #set( $current_user = $db.user.fetch($query.user_id) )

$db.root_attribute_name r : root attribute or root action. The value of an action is the number of affected rows.

• Today, there are $db.today_events_count events.

$db.error r : last error message encountered. We generally know that an error has occured when one of the methods returns null or false.

• ## don't do this in a MVC app!
#if ( ! $db.user.insert($query) ) Error : $db.error #end

2. Entity attributes and methods :

$entity.order w : use this attribute to specify an order before issuing a #foreach directive on this entity. Reseted in every context. Pass it an empty string to reset it manually.

• #set( $db.user.order = "lastname" )
#foreach($u in $db.user) ... #end

$entity.refine("sql-condition") : use this method to specify an additionnal SQL condition before issuing a #foreach directive on this entity. Can be called several times. Reseted in every context.

• #set( $db.user.refine = " profile = 'admin' " )
#* loop on admins *#
#foreach ($u in $db.user) ... #end

$entity.clearRefinement( ) : clear any refinement clauses for this entity

#foreach ($instance in $entity) : loop on all (or a subset of - if refined) instances of this entity.

$entity.fetch(values_list) : returns the instance defined by the values of its primary key columns, or null otherwise.

• #set( $str = $db.localized_resource.fetch(['welcome_message','EN']) )

$entity.fetch(value) : returns the instance defined by the value of its unique primary key, or null otherwise.

• #set( $current_user = $db.user.fetch($query.user_id) )

The following entity methods are not advised in a MVC architecture.

$entity.update(values_map) : update a row in this entity's table. Velosurf will ensure all key columns are specified, to avoid an accidental massive update.

• #set( $success = $db.user.update($query) )

$entity.delete(values_map) : delete a row from this entity's table. Velosurf will ensure all key columns are specified, to avoid an accidental massive delete.

• #set( $success = $db.user.delete($query) )

$entity.insert(values_map) : insert a new row in this entity's table.

• #set( $success = $db.user.insert($query) )
#if ($success)
#set( $user = $db.user.fetch($db.user.lastInsertID) )
#else Error : $db.error
#end

$entity.lastInsertID : last inserted ID, for entities with only one primary key column, autoincremented.
See the above example.

3. Attribute attributes and methods :

Only multivalued attributes can be referenced from templates. Others are directly evaluated when referenced.

$multivalued_attribute.order w : use this attribute to specify an order before issuing a #foreach directive on this Attribute.

$multivalued_attribute.refine("sql-condition") : use this method to specify an additionnal condition before issuing a #foreach directive on this multivalued Attribute. Can be called several times. See Javadoc for additional details.

$multivalued_attribute.clearRefinement( ) : clear any refinement clauses for this attribute.

#foreach ($instance in $multivalued_attribute) : loop on all (or a subset of - if refined) instances returned by the evaluation of this multivalued Attribute.

4. Action attributes and methods :

An action has no attribute and no method. It is executed when referenced, and returns the number of affected rows.

5. Instance attributes and methods :

$instance.entity r : the name of this instance's entity, or null if it's a generic instance.

$instance.attribute r : refers to an Attribute of this instance.

$instance.action r : executes the specified action on this instance. The value of an action is the number of affected rows.

$instance.primaryKey r : returns a list of two-elements map, name and value, or each column in the primary key.

• #foreach($key in $instance)
  <input type="hidden" name="$key.name" value="$key.value">
#end

The writable form of the previous attribute, as long as the following methods, are not advised in a MVC architecture.

$instance.update(values_map) : update the row of this instance, from passed values. Velosurf will ensure all key columns are specified, to avoid an accidental massive update.

$instance.update() : update the row of this instance, from actual values. Velosurf will ensure all key columns are specified, to avoid an accidental massive update.

$instance.delete() : delete the row of this instance. Velosurf will ensure all key columns are specified, to avoid an accidental massive delete.

$instance.insert() : insert a new row .