data

ATTRIBUTES

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?

DESCRIPTION

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]DATABASE_NAME[/tag] to mark a database writable, and do this before any access to that table.

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.

BEHAVIOR

This tag does not appear to be affected by, or affect, the rest of Interchange.

EXAMPLES

Example: Basic example

Display price for the item SKU 4595:

[data products price 4595]

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]

NOTES

AVAILABILITY

data is available in Interchange versions:

4.6.0-5.9.0 (git-head)

SOURCE

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}));
}

AUTHORS

Interchange Development Group

Name