For more information... RTFM!
NAVIGATION
PAGES THAT LINK HERE
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

data

Returns the value of the field in a database table, or from the session namespace.

Summary

  • [data table column key]

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

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

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: 

  1. after it is read, or
  2. 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:

foo bar baz
Warning

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

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

Category:  Interchange tags
Last modified by: Gert van der Spoel
Modification date: Friday 19 June 2009 at 5:40 PM (CDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us