data — get or set value of a named field or row from a database table or user session
Attribute | Pos. | Req. | Default | Description |
---|---|---|---|---|
[ table | base | database ] | Yes | Yes | The name of the table to fetch from. | |
[ field | col | column | name ] | Yes | Yes |
The name of the field whose value you want to fetch.
Required unless returning the entire row in combination with
the hash= option.
|
|
[ key | code | row ] | Yes | The key that identifies the row to fetch. | ||
safe_data | 0 | Is data safe? | ||
value |
Set field to specified value. If increment= is true,
increment
the field by the specified value (negative increments can be used for
decreasing).
|
|||
filter | If reading a field, apply specified filter to the value before displaying. It setting a field, apply specified filter to the value before updating the database. | |||
increment | 0 |
Increment or decrement field content by value= ?
Unless value= is specified, increment by
1 .
|
||
append | 0 | Append the field instead of "truncating" before write? | ||
alter |
change , add or
delete .
|
|||
serial | 0 | |||
foreign | Select data element based on a specified foreign key. This allows selection of a field or row based on a column that is not the primary key in the database table. If the key is unique, first selected is returned. Foreign key can also be specified as a hash, see the section called “EXAMPLES”. | |||
hash | Return the result as a reference to a hash? Hash keys will correspond to column names. | |||
interpolate | 0 | interpolate output? | ||
hide | 0 | Hide the tag return value? |
The tag is primarily used for reading fields from database tables or user's session namespace. However, with appropriate options, whole rows can be returned, and the fields can be set, incremented, appended and filtered.
If a database with WRITE_CONTROL
enabled is to be written
(such as a DBM-based database, which has it by default), it must be flagged
writable on the page wishing to perform the update;
use [tag flag write]
to mark a database writable, and do this before any access to that table.
DATABASE_NAME
[/tag]
In addition, the [data]
tag can access values in users'
session namespace, using the special session
keyword.
Do not call your own database "session
" because it would
mask accesses to the actual sessions database.
Example: Dumping user session
To dump user session, see [dump_session]
. Once you do it, you can
learn the names of all the session keys you can use in the following example.
Example: Retrieving session values
In this example we produce a simple "report" about the user. We take the data from the user's session record.
[if session logged_in] User is logged in as [data session username]. [else] User is not logged in. [/else] [/if] <br /> [data session host] is user's IP. <br /> Browser used is [data session browser]. <br />
Example: Retrieving fields from a table using a foreign key
If we wrote [data products price 4595]
, we would retrieve
the price of the item SKU 4595
. The SKU column
is the primary key in the products
database, and that's why Interchange implicitly searches it for the specified
key=
.
To retrieve price of an item based on say, it's description field (which is not a primary key), we need to use the foreign key functionality:
[data table=products column=price foreign=description key="Nice Bio Test" ]
Example: Retrieving fields from a table using foreign key hash
To retrieve SKU of an item based on say, both it's description and price fields, we need to use the foreign key functionality with the hash argument:
[data table=products column=price foreign.description='Nice Bio Test' foreign.price=275.45 ]
TODO not working
Example: Retrieving fields from a table using foreign key array
Sometimes you want a query that is optimized in a particular order. To achieve that, use either your custom code, or an array-type foreign key:
[data table=products column=price foreign.0="price=275.45" foreign.1="description='Nice Bio Test'" ]
TODO not working
Example: Retrieving rows from a database
Here's a Perl example of retrieving complete table rows.
[perl tables=products] my $row_hash = $Tag->data({ table => 'products', key => '4595', hash => 1 }); my $out = "Item SKU " . $row_hash->{sku} . " has"; $out .= " price " . $row_hash->{price} . " and" . " description " . $row_hash->{description} . ". Cheers!"; $out [/perl]
Interchange 5.9.0:
Source: code/SystemTag/data.coretag
Lines: 22
# Copyright 2002-2007 Interchange Development Group and others # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. See the LICENSE file for details. # # $Id: data.coretag,v 1.4 2007-03-30 23:40:49 pajamian Exp $ UserTag data Order table field key UserTag data addAttr UserTag data attrAlias column field UserTag data attrAlias code key UserTag data attrAlias base table UserTag data attrAlias database table UserTag data attrAlias col field UserTag data attrAlias row key UserTag data attrAlias name field UserTag data Implicit increment increment UserTag data PosNumber 3 UserTag data Version $Revision: 1.4 $ UserTag data MapRoutine Vend::Interpolate::tag_data
Source: lib/Vend/Interpolate.pm
Lines: 887
sub tag_data { my($selector,$field,$key,$opt,$flag) = @_; local($Safe_data); $Safe_data = 1 if $opt->{safe_data}; my $db; if ( not $db = database_exists_ref($selector) ) { if($selector eq 'session') { if(defined $opt->{value}) { $opt->{value} = filter_value($opt->{filter}, $opt->{value}, $field) if $opt->{filter}; if ($opt->{increment}) { $Vend::Session->{$field} += (+ $opt->{value} || 1); } elsif ($opt->{append}) { $Vend::Session->{$field} .= $opt->{value}; } else { $Vend::Session->{$field} = $opt->{value}; } return ''; } else { my $value = $Vend::Session->{$field} || ''; $value = filter_value($opt->{filter}, $value, $field) if $opt->{filter}; return $value; } } else { logError( "Bad data selector='%s' field='%s' key='%s'", $selector, $field, $key, ); return ''; } } elsif($opt->{increment}) { #::logDebug("increment_field: key=$key field=$field value=$opt->{value}"); return increment_field($Vend::Database{$selector},$key,$field,$opt->{value} || 1); } elsif (defined $opt->{value}) { #::logDebug("alter table: table=$selector alter=$opt->{alter} field=$field value=$opt->{value}"); if ($opt->{alter}) { $opt->{alter} =~ s/\W+//g; $opt->{alter} = lc($opt->{alter}); if ($opt->{alter} eq 'change') { return $db->change_column($field, $opt->{value}); } elsif($opt->{alter} eq 'add') { return $db->add_column($field, $opt->{value}); } elsif ($opt->{alter} eq 'delete') { return $db->delete_column($field, $opt->{value}); } else { logError("alter function '%s' not found", $opt->{alter}); return undef; } } else { $opt->{value} = filter_value($opt->{filter}, $opt->{value}, $field) if $opt->{filter}; #::logDebug("set_field: table=$selector key=$key field=$field foreign=$opt->{foreign} \ value=$opt->{value}"); my $orig = $opt->{value}; if($opt->{serial}) { $field =~ s/\.(.*)//; my $hk = $1; my $current = database_field($selector,$key,$field,$opt->{foreign}); $opt->{value} = dotted_hash($current, $hk, $orig); } my $result = set_field( $selector, $key, $field, $opt->{value}, $opt->{append}, $opt->{foreign}, ); return $orig if $opt->{serial}; return $result } } elsif ($opt->{serial}) { $field =~ s/\.(.*)//; my $hk = $1; return ed( dotted_hash( database_field($selector,$key,$field,$opt->{foreign}), $hk, ) ); } elsif ($opt->{hash}) { return undef unless $db->record_exists($key); return $db->row_hash($key); } elsif ($opt->{filter}) { return filter_value( $opt->{filter}, ed(database_field($selector,$key,$field,$opt->{foreign})), $field, ); } #The most common , don't enter a block, no accoutrements return ed(database_field($selector,$key,$field,$opt->{foreign})); }
Source: lib/Vend/Interpolate.pm
Lines: 887
sub tag_data { my($selector,$field,$key,$opt,$flag) = @_; local($Safe_data); $Safe_data = 1 if $opt->{safe_data}; my $db; if ( not $db = database_exists_ref($selector) ) { if($selector eq 'session') { if(defined $opt->{value}) { $opt->{value} = filter_value($opt->{filter}, $opt->{value}, $field) if $opt->{filter}; if ($opt->{increment}) { $Vend::Session->{$field} += (+ $opt->{value} || 1); } elsif ($opt->{append}) { $Vend::Session->{$field} .= $opt->{value}; } else { $Vend::Session->{$field} = $opt->{value}; } return ''; } else { my $value = $Vend::Session->{$field} || ''; $value = filter_value($opt->{filter}, $value, $field) if $opt->{filter}; return $value; } } else { logError( "Bad data selector='%s' field='%s' key='%s'", $selector, $field, $key, ); return ''; } } elsif($opt->{increment}) { #::logDebug("increment_field: key=$key field=$field value=$opt->{value}"); return increment_field($Vend::Database{$selector},$key,$field,$opt->{value} || 1); } elsif (defined $opt->{value}) { #::logDebug("alter table: table=$selector alter=$opt->{alter} field=$field value=$opt->{value}"); if ($opt->{alter}) { $opt->{alter} =~ s/\W+//g; $opt->{alter} = lc($opt->{alter}); if ($opt->{alter} eq 'change') { return $db->change_column($field, $opt->{value}); } elsif($opt->{alter} eq 'add') { return $db->add_column($field, $opt->{value}); } elsif ($opt->{alter} eq 'delete') { return $db->delete_column($field, $opt->{value}); } else { logError("alter function '%s' not found", $opt->{alter}); return undef; } } else { $opt->{value} = filter_value($opt->{filter}, $opt->{value}, $field) if $opt->{filter}; #::logDebug("set_field: table=$selector key=$key field=$field foreign=$opt->{foreign} \ value=$opt->{value}"); my $orig = $opt->{value}; if($opt->{serial}) { $field =~ s/\.(.*)//; my $hk = $1; my $current = database_field($selector,$key,$field,$opt->{foreign}); $opt->{value} = dotted_hash($current, $hk, $orig); } my $result = set_field( $selector, $key, $field, $opt->{value}, $opt->{append}, $opt->{foreign}, ); return $orig if $opt->{serial}; return $result } } elsif ($opt->{serial}) { $field =~ s/\.(.*)//; my $hk = $1; return ed( dotted_hash( database_field($selector,$key,$field,$opt->{foreign}), $hk, ) ); } elsif ($opt->{hash}) { return undef unless $db->record_exists($key); return $db->row_hash($key); } elsif ($opt->{filter}) { return filter_value( $opt->{filter}, ed(database_field($selector,$key,$field,$opt->{foreign})), $field, ); } #The most common , don't enter a block, no accoutrements return ed(database_field($selector,$key,$field,$opt->{foreign})); }