Package com.smartgwt.client.docs

# Interface VelocitySupport

public interface VelocitySupport

### Velocity context variables

The Smart GWT Server provides a number of standard context variables for use in the Velocity templates you write to implement `custom queries`, transaction chaining, `dynamic security checking` and `templated mail messages`. These are:

- $currentDate. The current date/time with millisecond precision
- $transactionDate. The date/time that this transaction started, with millisecond precision. If you are not using `queuing`, this value will be identical to $currentDate
- $servletRequest. The associated `HttpServletRequest`
- $dsRequest. The associated `DSRequest` (though of course this is a server-side `DSRequest` object, so please also see the server-side Javadocs)
- $primaryDSRequest. Only present on cache-sync operations, this is the original update `DSRequest` that caused the cache-sync request to be created
- $session. The associated `HttpSession`
- $httpParameters. This variable gives you access to the parameters Map of the associated `HttpServletRequest`; it is an alternate form of `$servletRequest.getParameter`
- $requestAttributes. This variable gives you access to the attributes Map of the associated `HttpServletRequest`; it is an alternate form of `$servletRequest.getAttribute`
- $sessionAttributes. This variable gives you access to the attributes Map of the associated `HttpSession`; it is an alternate form of `$session.getAttribute`
- $dataSources. This variable gives you access to Smart GWT `DataSource`s. You access a dataSource by suffixing its name to the `$dataSources` designation. For example, `$dataSources.supplyItem` refers to the DataSource object called "supplyItem". You can use this approach to execute any valid DataSource method. One especially useful method in this context is `hasRecord(fieldName, value)` - see the server-side Javadocs for more details.
- $util - A `DataTools` object, giving you access to all of that class's useful helper functions

All of these variables (other than the two dates) represent objects that can contain other objects (attributes or parameters or object properties). The variables based on the Servlet API (session, sessionAttributes, httpParameters, servletRequest and requestAttributes) all implement the `Map` interface, so you can use the Velocity "property" shorthand notation to access them. The following usage examples show five equivalent ways to return the value of the session attribute named "foo":

         $session.foo
         $session.get("foo")
         $session.getAttribute("foo")
         $sessionAttributes.foo
         $sessionAttributes.get("foo")

In the case of `$servletRequest`, the shorthand approach accesses the attributes - you need to use either `$httpParameters` or `$servletRequest.getParameter` to access parameters. These examples all return the value of the HTTP parameter named "bar":

         $httpParameters.bar
         $httpParameters.get("bar")
         $servletRequest.getParameter("bar")

When you use these Velocity variables in a `customSQL` clause or SQL snippet such as a `whereClause`, all of these template variables return values that have been correctly quoted and escaped according to the syntax of the underlying database. We do this because "raw" values are vulnerable to SQL injection attacks. If you need access to the raw value of a variable in a SQL template, you can use the $rawValue qualifier in front of any of the template variables, like this:
`$rawValue.session.foo`

This also works for the $criteria and $values context variables (see `CustomQuerying` for details of these variables). So:
`$rawValue.criteria.customerName`

Note that `$rawValue` is only available in SQL templates. It is not needed in other contexts, such as Transaction Chaining, because the value is not escaped and quoted in these contexts.

Warning: Whenever you access a template variable for use in a SQL statement, bear in mind that it is dangerous to use `$rawValue`. There are some cases where using the raw value is necessary, but even so, all such cases are likely to be vulnerable to injection attacks. Generally, the presence of `$rawValue` in a SQL template should be viewed as a red flag.

Finally, some example usages of these values. These `values` clauses set "price" to a value extracted from the session, and "lastUpdated" to the date/time that this transaction started:
`<values fieldName="price" value="$session.somePrice" />
<values fieldName="lastUpdated" value="$transactionDate" />`

This whereClause selects some users based on various values passed in the criteria and as HTTP parameters:
`<whereClause>department = $httpParameters.userDept AND dob >= $criteria.dateOfBirth</whereClause>`

This whereClause selects some users based on various values obtained from the servletRequest's attributes, using a number of equivalent techniques for accessing the attributes:

        <whereClause>
              department = $servletRequest.dept
          AND startDate >= $requestAttributes.dateOfBirth
          AND salary < $servletRequest.getAttribute("userSalary")
        </whereClause>