[docs] docs - heins modified ictemplates.sdf
docs@interchange.redhat.com
docs@interchange.redhat.com
Sun Jul 21 21:49:01 2002
User: heins
Date: 2002-07-22 01:48:54 GMT
Modified: . ictemplates.sdf
Log:
* Improve embedded Perl programming information slightly.
Revision Changes Path
1.41 +123 -48 docs/ictemplates.sdf
rev 1.41, prev_rev 1.40
Index: ictemplates.sdf
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
RCS file: /anon_cvs/repository/docs/ictemplates.sdf,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- ictemplates.sdf 15 Jul 2002 13:52:16 -0000 1.40
+++ ictemplates.sdf 22 Jul 2002 01:48:53 -0000 1.41
@@ -1,10 +1,10 @@
!init OPT_LOOK=3D"akopia"; OPT_STYLE=3D"manual"
-# $Id: ictemplates.sdf,v 1.40 2002/07/15 13:52:16 mheins Exp $
+# $Id: ictemplates.sdf,v 1.41 2002/07/22 01:48:53 mheins Exp $
=20
!define DOC_NAME "Template Guide"
!define DOC_TYPE ""
!define DOC_CODE "ictemplates"
-!define DOC_VERSION substr('$Revision: 1.40 $',11, -2)
+!define DOC_VERSION substr('$Revision: 1.41 $',11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://interchange.redhat.com/doc/ictemplates.html"
@@ -902,6 +902,11 @@
=20
H1: Interchange Perl Objects
=20
+.Interchange gives you access to the power of Perl with the [perl], [calc]=
, and
+.[mvasp] tags. They all support the same set of Perl objects and variables.
+
+H2: A note about Safe
+
You can access all objects associated with the catalog and the user settin=
gs with opcode restrictions based on the standard Perl module {{C[jump=3D"h=
ttp://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}}. There are =
some unique things to know about programming with Interchange.
=20
Under C<Safe>, certain things cannot be used. For instance, the following =
can not be used when running Safe:
@@ -927,6 +932,8 @@
$users =3D $Tag->file('userlist');
!endblock
=20
+H2: Standard objects and variables
+
The following is a list of Interchange Perl standard objects are:
=20
LI1: $CGI
@@ -940,7 +947,20 @@
.use
=20
!block example; listitem=3D2
- <% $Document->write("Value of foo is $CGI->{foo}"); %>
+ [perl]
+ return "Value of foo is $CGI->{foo}";
+ [/perl]
+!endblock
+
+Actually, you should not do that -- if someone sends you a value you should
+not output it willy-nilly for security reasons. Filter it first with the [=
filter]
+tag as accessed by the $Tag object:
+
+!block example; listitem=3D2
+ [perl]
+ my $val =3D $Tag->filter('encode_entities', $CGI->{foo});
+ return "Value of foo is $val";
+ [/perl]
!endblock
=20
.Remember, multiple settings of the same variable are separated by a NULL =
character. To get the array value, use $CGI_array.
@@ -1015,98 +1035,130 @@
=20
.A hash of databases shared with the C<[mvasp tables=3D"foo"]> parameter t=
o the tag call. Once the database is shared, it is open and can be accessed=
by any of its methods. This will not work with SQL unless AllowGlobal is s=
et for the catalog.
=20
+{{B:NOTE}}: This object is not present and the below will not work with [c=
alc].
+
.To get a reference to a particular table, specify its hash element:
=20
!block example; listitem=3D2
- $ref =3D $Db{products};
+ my $db =3D $Db{products};
!endblock
=20
.The available methods are:
=20
!block example; listitem=3D2
# access an element of the table
- $field =3D $ref->field($key, $column);
+ $field =3D $db->field($key, $column);
=20
# set an element of the table
- $ref->set_field($key, $column_name, $value);
+ $db->set_field($key, $column_name, $value);
=20
# atomic increment of an element of the table
- $ref->inc_field($key, $column_name, 1);
+ $db->inc_field($key, $column_name, 1);
+
+ # Return a complete hash of the database row (minus the key)
+ $hashref =3D $db->row_hash($key);
+
+ # Return some fields from a row
+ my @fields =3D qw/sku price description/;
+ $array_ref =3D $db->get_slice($key, \@fields);
+
+ # Set some fields in a row (slice)
+ my $key =3D 'os28004';
+ my @fields =3D qw/price description/;
+ my @values =3D (5.95, "Ergo Roller");
+ $array_ref =3D $db->set_slice($key, \@fields, \@values);
+
+ # Alternate way to set slice
+ my $key =3D 'os28004';
+ my %fields =3D ( price =3D> 5.95, description =3D> "Ergo Roller");
+ $array_ref =3D $db->set_slice($key, \%fields);
+
+ # Perform a SQL query, returning an array of arrays
+ # (the equivalent of DBI $sth->fetchall_arrayref)
+ $ary =3D $db->query($sql);
+
+ # Same as above, except receive=20
+ # hash reference of pointers to field positions and
+ # array reference containing list of fields
+ my $sql =3D 'select * from products';
+ ($ary, $index_hash, $name_ary) =3D $db->query($sql);
+ $fields_returned =3D join ",", @$name_ary;
+ $pointer_to_price =3D $index_hash->{price};
+
+ # Perform a SQL query, returning an array of hashes
+ $ary =3D $db->query({ sql =3D> $sql, hashref =3D> 1 });
=20
# see if element of the table is numeric
- $is_numeric =3D $ref->numeric($column_name);
+ $is_numeric =3D $db->numeric($column_name);
=20
# Quote for SQL query purposes
- $quoted =3D $ref->quote($value, $column_name);
+ $quoted =3D $db->quote($value, $column_name);
=20
# Check configuration of the database
- $delimiter =3D $ref->config('DELIMITER');
+ $delimiter =3D $db->config('DELIMITER');
=20
# Find the names of the columns (not including the key)
- @columns =3D $ref->columns();
+ @columns =3D $db->columns();
# Insert the key column name
- unshift @columns, $ref->config('KEY');
+ unshift @columns, $db->config('KEY');
=20
# See if a column is in the table
- $is_a_column =3D defined $ref->test_column($column_name);
+ $is_a_column =3D defined $db->test_column($column_name);
=20
# See if a row is in the table
- $is_present =3D $ref->record_exists($key);
+ $is_present =3D $db->record_exists($key);
=20
# Create a subroutine to return a single column from the table
- $sub =3D $ref->field_accessor($column);
+ $sub =3D $db->field_accessor($column);
for (@keys) {
push @values, $sub->($key);
}
=20
# Create a subroutine to set a single column in the database
- $sub =3D $ref->field_settor($column);
+ $sub =3D $db->field_settor($column);
for (@keys) {
$sub->($key, $value);
}
=20
# Create a subroutine to set a slice of the database
- $sub =3D $ref->row_settor(@columns);
+ $sub =3D $db->row_settor(@columns);
for (@keys) {
$sub->($key, @values);
}
=20
# Return a complete array of the database (minus the key)
- @values =3D $ref->row($key);
-
- # Return a complete hash of the database row (minus the key)
- $hashref =3D $ref->row_hash($key);
+ @values =3D $db->row($key);
=20
# Delete a record/row from the table
- $ref->delete_record($key);
+ $db->delete_record($key);
!endblock
=20
LI1: %Sql
=20
-.A hash of SQL databases that you shared with the C<[mvasp tables=3D"foo"]=
> parameter to the tag call. It returns the DBI database handle, so operati=
ons like the following can be performed:
+.A hash of SQL databases that you shared with the C<[perl tables=3D"foo"]>=
parameter to the tag call. It returns the DBI database handle, so operatio=
ns like the following can be performed:
+
+{{B:NOTE}}: This object is not present and the below will not work with [c=
alc].
=20
!block example; listitem=3D2
- <%
+ [perl products]
my $dbh =3D $Sql{products}
- or return HTML "Database not shared.";
+ or return "Database not shared.";
my $sth =3D $dbh->prepare('select * from products')
- or return HTML "Couldn't open database.";
+ or return "Couldn't open database.";
$sth->execute();
my @record;
while(@record =3D $sth->fetchrow()) {
foo();
}
$sth =3D $dbh->prepare('select * from othertable')
- or return HTML "Couldn't open database.";
+ or return "Couldn't open database.";
$sth->execute();
while(@record =3D $sth->fetchrow()) {
bar();
}
- %>
+ [/perl]
!endblock
=20
-.This will not work with unless AllowGlobal is set for your catalog.
-
LI1: $DbSearch
=20
.A search object that will search a database without using the text file. =
It is the same as Interchange's C<db> searchtype. Options are specified in =
a hash and passed to the object. All multiple-field options should be passe=
d as array references. Before using the $DbSearch object, it must be told w=
hich table to search. For example, to use the table C<foo>, it must have be=
en shared with C<[mvasp foo]>.
@@ -1143,7 +1195,30 @@
=20
LI1: $Document
=20
-.This is an object that has several routines associated with it.
+This is an object which will allow you to write and manipulate the output
+of your embedded Perl. For instance, you can emulate a non-parsed-header
+program with:
+
+!block example; listitem=3D2
+[perl]
+ $Document->hot(1);
+ for(1 .. 20) {
+ $Document->write("Counting to $_...<br>");
+ $Document->write( " " x 4096);
+ $Tag->sleep(1);
+ }
+ $Document->write("Finished counting!");
+ return;
+[/perl]
+!endblock
+
+Note the write of 4096 spaces. Because Interchange's link program is
+parsed by default, and your web server (and the link program) have
+buffers, you need to fill up the buffer to cause a write. You can do it
+without the extra padding if you set the link up as a non-parsed-header
+program -- see your web server documentation on how to do that.
+
+There are several methods associated with $Document:
=20
!block example; listitem=3D2
HTML $foo; # Append $foo to the write buffer array
@@ -1294,28 +1369,27 @@
=20
.Using the $Tag object, any Interchange tag including user-defined tags ca=
n be accessed.
=20
-Note[label=3D'IMPORTANT NOTE: '] If the tag will access a database that ha=
s not been previously opened, the table name must be passed in the ASP call=
For example:
+Note[label=3D'IMPORTANT NOTE: '] If the tag will access a database that ha=
s not been previously opened, the table name must be passed in the ITL call=
For example:
=20
.Named parameters:
!block example; listitem=3D2
- [mvasp tables=3D"products pricing"]
+ [perl tables=3D"products pricing"]
!endblock
=20
.or
=20
.Positional parameters:
!block example; listitem=3D2
- [mvasp products pricing]
+ [perl products pricing]
!endblock
=20
.Any tag can be called.
=20
!block example; listitem=3D2
- <%
+ [perl]
my $user =3D $Session->{username};
- my $name_from_db =3D $Tag->data('userdb', 'name', $user );
- $Document->write($name_from_db);
- %>
+ return $Tag->data('userdb', 'name', $user );
+ [/perl]
!endblock
=20
.is the same as:
@@ -1395,7 +1469,8 @@
%>
!endblock
=20
-.It prepends the normal timestamp with user and page information. To suppr=
ess that information, begin the message with a backslash (C<\>).
+.It prepends the normal timestamp with user and page information. To
+suppress that information, begin the message with a backslash (C<\>).
=20
!block example; listitem=3D2
<%
@@ -1445,8 +1520,8 @@
.Attribute aliases:
=20
!block example; listitem=3D2
- base =3D=3D> table
- database =3D=3D> table
+ base =3D=3D> table
+ database =3D=3D> table
!endblock
=20
H2: Time
@@ -1519,8 +1594,8 @@
.Attribute aliases:
=20
!block example; listitem=3D2
- base =3D=3D> table
- database =3D=3D> table
+ base =3D=3D> table
+ database =3D=3D> table
!endblock
=20
.Description:
@@ -1579,7 +1654,7 @@
.Attribute aliases:
=20
!block example; listitem=3D2
- arg =3D=3D> file
+ arg =3D=3D> file
!endblock
=20
H2: Header
@@ -3010,10 +3085,10 @@
Interchange honors the standard POSIX keys:
=20
!block example
- mon_decimal_point or decimal_point
- mon_thousands_sep or thousands_sep
- currency_symbol or int_currency_symbol
- frac_digits or p_cs_precedes
+ mon_decimal_point or decimal_point
+ mon_thousands_sep or thousands_sep
+ currency_symbol or int_currency_symbol
+ frac_digits or p_cs_precedes
!endblock
=20
See the POSIX setlocale(3) man page for more information. These keys will =
be used for formatting prices and approximates the number format used in mo=
st countries. To set a custom price format, use these special keys: