data
Returns the value of the field in a database table, or from the session namespace.
Summary
| Parameter
|
Description
|
Default
|
| table |
The name of the database table that should be read or updated. |
None |
| base |
Alias for table. |
None |
| field |
The name of the column whose value you want to fetch. |
None |
| col |
Alias for field. |
None |
| column |
Alias for field. |
None |
| name |
Alias for field. |
None |
| key |
The key that identifies the row containing the column you want to fetch or modify. |
None |
| row |
Alias for key. |
None |
| code |
Alias for key. |
None |
| append |
Append the value to the existing column data. |
No
|
| filter |
Run the output through one or more text filters. |
None |
| foreign |
To select a data element based on a foreign key, specify the foreign key column in this parameter. |
None |
| hash |
Return results as a reference to a Perl hash, with column names as keys. |
None |
| increment |
Increment the existing data by the amount in value. |
No
|
| serial |
Serialise the value into a hash structure, if writing, or deserialise if reading. |
No
|
| value |
Set a new value. |
None |
| hide |
Suppress any output text that would ordinarily be returned from this tag.
(This universal parameter was introduced with Interchange version 5.5.2.) |
No
|
| interpolate |
Process any Interchange tags found in the text output from this tag. |
Yes
|
| safe_data |
Allow the "[" character to remain intact in returned data. |
No
|
Examples
Perl example
$Tag->data({
table => $table,
column => $column,
key => $key,
});
|
or similarly with positional parameters:
|
$Tag->data($table, $column, $key, $attribute_hash_reference);
|
Description
Given the name of a table, the name of a column and a key value to use,
this tag will return the value read from the specified column.
This tag can also be used to gain access to the following keys in the Interchange
$Session hash reference:
| Name
|
Description
|
| accesses
|
The number of pare requests performed for this session within
the last 30 seconds. |
| arg
|
The argument passed in an [area] tag. |
| browser
|
The identification value sent by the user agent. |
| carts
|
A reference to a Perl hash containing shopping carts.
See $Carts for
more information. |
| host
|
Interchange's note of the visitor's hostname
(possibly modified by DomainTail).
If the hostname could not be looked up
(HostnameLookups switched off or
DNS error etc.) then the visitor's IP address will be
stored here instead. |
| id
|
The current session ID. |
| last_error
|
The last error or status message from the error logging routine. |
| last_search
|
The last non-SQL Interchange search specification invoked. |
| last_url
|
The current Interchange path_info. |
| logged_in
|
Will be true if the user is logged in. |
| ohost
|
Interchange's note of the visitor's IP address when using
a non-SSL link.
Also see shost. |
| pageCount
|
Number of unique URIs generated by Interchange for this session. |
| payment_result
|
A hash of result messages from payment module
transaction attempts.
See examples in the
Interchange payment modules documentation. |
| prev_url
|
The previous path_info. |
| referer
|
HTTP_REFERER string. |
| ship_message
|
The last error messages from shipping. |
| shost
|
Interchange's note of the visitor's IP address when using
a SSL link.
Also see ohost. |
| spider
|
Will be true if the user is a search engine spider. |
| source
|
Source of original entry to Interchange. |
| teleport
|
Date and time (in
"%Y%m%d%H%M%S" format) for use with the PageTables
directive. |
| time
|
Time (seconds since 01 January 1970) of the last access. |
| user
|
The REMOTE_USER string. |
| username
|
Logged-in username.
See the Interchange user database page. |
|
Warning
Databases will hide session values, so don't name a table
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 table
Session, but it would be better not to use that name at all.
|
Parameters
table
The name of the database table that should be read or updated.
|
Note
If a DBM-based database is to be modified, it must be flagged
writable on the page calling the [flag] tag.
For example, use [flag write]products[/tag] to mark the
products table writable.
This must be done before any access to that table.
|
field
The name of the column whose value you want to fetch.
Required unless returning the entire row in combination with
the hash parameter.
key
The key that identifies the row containing the column you
want to fetch or modify.
append
The append attribute causes the content of the value
parameter to be appended to the existing column data.
filter
The filter parameter is a set of one or more Interchange
filters that are applied to the data either:
- after it is read, or
- before it is placed in the table.
See the
filters category for a list of filters.
foreign
To select a data element based on a foreign key,
specify the foreign key column in this parameter.
Allows selection of a data element or record based on a column that
is not the primary key.
If the key is not unique it returns the first selected element.
The rest of the text in this section refers to this table, which
is 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 optimised 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".
hash
The hash option causes the data tag to return its
results (the entire row, if you omit the column parameter)
as a reference to a Perl hash, with column names as keys.
An example:
my $row_hash = $Tag->data({
table => 'products',
key => 'os28004',
hash => 1,
});
|
You could then access desired values this way:
|
my $out = 'Price: ' . $row_hash->{price};
|
increment
If the increment parameter is present, the column data
will be atomically incremented with the value specified with
the value parameter.
If no value is specified then the column data will
be incremented by 1.
You can decrement the column value by specifying a negative number
with the value parameter.
serial
If the this parameter is true, and the column
contains a dot ("."), then the value will be automatically
serialised into a text representation of a Perl hash structure (if writing),
or deserialised from its text representation (if reading).
For example:
[data
table=sometable
column=hashcol.hashkey
key=whatever
value="foo bar baz"
serial=1
]
|
The above would store the following in the "hashcol" column,
in the "sometable" table:
|
{ 'hashkey' => 'foo bar baz' }
|
The following can be used to read, and deserialise, the data:
[data
table=sometable
column=hashcol.hashkey
key=whatever
serial=1
]
|
The above example would return the following data:
|
|
Warning
The above will only work if the column contains serialised
Perl hash data with no syntax errors.
If the data has a syntax error that prevents it from evaluating
to a text representation of a Perl hash,
then the specified hash key will be silently emptied.
|
value
If this parameter is given then the column data will be changed to
the specified value.
Also see the increment parameter.
safe_data
Setting "safe_data=1" allows return values containing the
"[" character.
|
|
Warning
You should not use "safe_data" unless you need it
and know what you are doing.
Read more about the philosophy behind safe_data
|
