Param

Parameters are used to pass values to commands.

<itm model="param" name="somedate" type="date"></itm>

Attributes

Required

• name - name of the parameter

Optional

• label - display name
• title - placeholder text
• scope - applies the parameter only to the matching command; comma-separated values are allowed
• element value (text) - default value
  • null - equals null
  • an empty value sent by the client equals null
  • server-side variables [[variable]] are available; see server-side variables; an unresolved [[variable]] equals null
• lg - show/hide on desktop
• sm - show/hide on mobile
• type - UI type / DB type; default is text
  • select - dropdown; the list is loaded from the command with the same name as the parameter (opts="pscope"); the first two columns are the key and the displayed value
  • multiselect - dropdown with multiple selection; the list is loaded the same way as for select
  • search - wide search box, minimum 3 characters
  • number decimal money numeric smallmoney / decimal
  • int bigint tinyint smallint integer / bigint
  • uniqueidentifier uuid / uniqueidentifier
  • date / date
  • datetime datetime2 smalldatetime / datetime
  • float / float
  • xml / xml
  • ansi / varchar
  • text password hidden color and any other type / nvarchar
  • checkbox - Yes/No buttons in the UI; value 1/0/null
  • any HTML input type can be used; see https://www.w3schools.com/tags/att_input_type.asp
  • a value that does not match a numeric, date or uniqueidentifier type stops the command with Parameter {name} not valid ...
• opts
  • server - server-side parameter; useful for predefined values that cannot be overwritten by the user
  • json-xml-root - takes the property and converts it to XML; supports arrays: an array is forced and elements are wrapped in a row; requires a JSON body (POST)
  • json-xml - takes the property and converts it to XML; throws an error if the JSON is an array; use json-xml-root for arrays or send JSON with a root element; requires a JSON body (POST)
  • body-xml-root - takes the body as is and converts it to XML; supports arrays: an array is forced and elements are wrapped in a row
  • body-json - takes the entire body as JSON and sends it as JSON; supports JSON objects and arrays
  • req - the parameter is required

Note

Deprecated aliases: json-xml-body → body-xml-root, json-body → body-json.

Note

Using the correct data type is important for proper data validation.

Parameter processing order

When the same parameter comes from several sources, the first one wins:

1. Server-side parameters (cannot be overwritten by the user)
2. Query string
3. Body parameters

When the SRS defines parameters, only those parameters are filled from the request. When it defines none, or only server-side parameters, every query string and body value is passed to the commands as a parameter.

Using parameters is safe from SQL injection and is recommended. To learn more, see OWASP SQL Injection.

Example of a server-side parameter:

 <itm model="param" name="username" opts="server">[[kv.v.user.username]]</itm>

Examples

All examples

Parameter UI

  <itm model="param" name="param1" type="checkbox">true</itm>
  <itm model="param" name="param2" type="checkbox">false</itm>
  <itm model="param" name="param3" type="number"></itm>
  <itm model="param" name="param4" type="date"></itm>

Dropdown

<srs label="Select Example">
 <def>
    <itm model="param" name="BillingCity" type="select"></itm>
    <itm model="command" name="data" >
<![CDATA[
  SELECT
    [InvoiceDate],
    [BillingCity],
    [Total]
  FROM [dbo].[Invoice]
  where 
    InvoiceDate >= @datefrom
    and InvoiceDate <= @dateto
]]>
    </itm>
    <itm model="command" name="BillingCity" opts="pscope">
        select city,cityname from city
    </itm>
  </def>
</srs>