Interchange Tags Reference: data

4.18. data

4.18.1. Summary

Main Parameters: table field key

Positional parameters in same order.

Additional parameters: hash foreign value

The attribute hash reference is passed to the subroutine after the parameters as the last argument. This may mean that there are parameters not shown here.

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    $Tag->data(
        {
         table => VALUE,
         field => VALUE,
         key => VALUE,
        }
    )

 OR

    $Tag->data($table, $field, $key, $ATTRHASH);

Attribute aliases

            base ==> table
            code ==> key
            col ==> field
            column ==> field
            database ==> table
            name ==> field
            row ==> key
    [data table field key other_named_attributes]

Parameters	Description	Default
base	Alias for table	DEFAULT_VALUE
code	Alias for key	DEFAULT_VALUE
col	Alias for field	DEFAULT_VALUE
column	Alias for field	DEFAULT_VALUE
database	Alias for table	DEFAULT_VALUE
field		DEFAULT_VALUE
hash		DEFAULT_VALUE
key		DEFAULT_VALUE
name	Alias for field	DEFAULT_VALUE
row	Alias for key	DEFAULT_VALUE
table		DEFAULT_VALUE

Attributes	Default
interpolate (reparse)	No

Other_Characteristics
Invalidates cache	no
Container tag	No
Has Subtags	No
Nests	Yes

Tag expansion example:

    [data table field key]
---
    TODO: (tag result)

ASP-like Perl call:

   $Tag->data(  { field => VALUE_field
                   key => VALUE_key
                   table => VALUE_table
});

or similarly with positional parameters,

    $Tag->data(table,field,key, $attribute_hash_reference);

4.18.2. Description

Returns the value of the field in a database table, or from the session namespace. If the optional value is supplied, the entry will be changed to that value. If the option increment* is present, the field will be atomically incremented with the value in value. Use negative numbers in value to decrement. The append attribute causes the value to be appended; and finally, the filter attribute is a set of Interchange filters that are applied to the data 1) after it is read; or 2)before it is placed in the table.

If a DBM-based database is to be modified, it must be flagged writable on the page calling the write tag. Use [tag flag write]products[/tag] to mark the products database writable, for example. This must be done before ANY access to that table.

In addition, the [data ...] tag can access a number of elements in the Interchange session database:

    accesses           Accesses within the last 30 seconds
    arg                The argument passed in a [page ...] or [area ...] tag
    browser            The user browser string
    cybercash_error    Error from last CyberCash operation
    cybercash_result   Hash of results from CyberCash (access with usertag)
    host               Interchange's idea of the host (modified by DomainTail)
    last_error         The last error from the error logging
    last_url           The current Interchange path_info
    logged_in          Whether the user is logged in (add-on UserDB feature)
    pageCount          Number of unique URLs generated
    prev_url           The previous path_info
    referer            HTTP_REFERER string
    ship_message       The last error messages from shipping
    source             Source of original entry to Interchange
    time               Time (seconds since Jan 1, 1970) of last access
    user               The REMOTE_USER string
    username           User name logged in as (UserDB feature)

Note: Databases will hide session values, so don't name a database "session". or you won't be able to use the [data ...] tag to read them. Case is sensitive, so in a pinch you could call the database "Session", but it would be better not to use that name at all.

4.18.2.1. field

The name of the field whose value you want to fetch. Required unless returning the entire row in combination with the hash option.

4.18.2.2. foreign

To select a data element based on a foreign key, specify the foreign key column in this field. Allows selection of a data element or record based on a column that is not the primary key.

If the key is not unique, returns the first selected element.

From this table named "foo":

  sku  name    partno  group   subgroup
  AB   Item 1  1       A       1
  AC   Item 2  2       A       2
  AD   Item 3  3       B       1
  AE   Item 4  4       C       1

These calls:

  [data table=foo col=name key=AB]
  [data table=foo col=name key=1 foreign=partno]

would both return "Item 1".

If the foreign parameter is a hash value, a single value matching the query-by-example set up by the hash is returned. For instance, from our example table "foo", the following

  [data table=foo col=name key=1 foreign.group=A foreign.subgroup=2]

would return "Item 2".

If the query needs to be optimized in a particular order, you need to use custom code or the array form of foreign. In our table "foo", the following

  [data table=foo col=name key=1 foreign.0="group=A" foreign.1="subgroup=2"]

also returns "Item 2".

4.18.2.3. hash

The hash option causes the data tag to return its results (the entire row, if you omit the field parameter) as a reference to a hash with column names as keys into the values of the row.

An example:

        $row_hash = $Tag->data({
                table => 'products',
                key   => 'os28004',
                hash  => 1,
        });

You could then access desired values this way:

        $out = 'Price: ' . $row_hash->{price};

4.18.2.4. key

The key that identifies the row containing the value(s) you want to fetch. Required.

4.18.2.5. table

The name of the Interchange-defined table you want to fetch data from. Required.