Overview
Installation
VTL reference
Configuration
Architecture
Java reference
Velosurf FAQ

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

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

$entity.rows : returns a list of all the instances of this entity.


$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

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.

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

$multivaled_atribute.rows : returns a list of all the instances of this entity.

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



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


$instance.column_name r,w : gives the scalar value of this column for this row, or sets its value.

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 .