MiniVend gives ready access to all objects associated with the catalog and
the user settings, with opcode restrictions based on the standard Perl
module Safe.pm.
There are some things you will need to know about programming with Minivend.
Under Safe, certain things cannot be used. For instance, this is not legal when
running Safe:
$variable = `cat file/contents`;
The backtick operator violates a number of the default Safe op code restrictions. You can not do direct file opens, either:
open(SOMETHING, "something.txt")
or die;
This will also cause a trap, and the code will fail to compile.
You can, however, use the Minivend equivalent routines:
# This will work if your administrator doesn't have NoAbsolute
# set
$users = $Tag->file('/home/you/list');
# This will always work, file names are based in the
# catalog directory
$users = $Tag->file('userlist');
The standard objects are:
This is a hash reference to %CGI::values, the value of user variables as submitted in the current page/form. To get
the value of a variable submitted as
<INPUT TYPE=hidden NAME=foo VALUE=bar>
use
<% $Document->write("Value of foo is $CGI->{'foo'}"); %>
Remember, multiple settings of the same variable are separated by a NULL character. To get the array value, use $CGI_array.
This is a hash reference to %CGI::values_array, arrays containing the value or values of user variables as submitted in
the current page/form. To get the value of a variable submitted as
<INPUT TYPE=hidden NAME=foo VALUE=bar>
<INPUT TYPE=hidden NAME=foo VALUE=baz>
use
<% = "The values of foo are", join (' and ', @{$CGI_array->{'foo'}}) %>
Remember, multiple settings of the same variable are separated by a NULL character. To get the array value, use $CGI_array.
A reference to the shopping cart hash
$Vend::Session->{carts}. The normal default cart is ``main''. An alias
for that is $Items in the normal course of events.
Shopping carts are an array of hash references. Here is an example of a
session cart array containing a main and a layaway cart.
{
'main' => [
{
'code' => '00-0011',
'mv_ib' => 'products',
'quantity' => 1,
'size' => undef,
'color' => undef
},
{
'code' => '99-102',
'mv_ib' => 'products',
'quantity' => 2,
'size' => 'L',
'color' => 'BLUE'
}
],
'layaway' => [
{
'code' => '00-341',
'mv_ib' => 'products',
'quantity' => 1,
'size' => undef,
'color' => undef
}
]
}
In this cart array $Carts->{main}[1]{'code'} is equal to 99-102. In the normal course of events, it would be equivalent to
$Items->[1]{'code'}.
A reference to the $Vend::Cfg array. Normally you should use this with a liberal dose of the MiniVend source code, but for simple things you can use something like:
# Turn off CyberCash for this user
$Config->{CyberCash} = 0;
Changes are not persistent except when running in the foreground (Debug mode or on Windows).
A hash of databases that you shared with the [mvasp tables="foo"] parameter to the tag call. Once you share the database, it is opened and
can be accessed by any of its methods.
ONCE AGAIN, this will not work with SQL unless AllowGlobal is set for your catalog.
To get a reference to a particular table, specify its hash element:
$ref = $Db->{products};
The methods available:
# access an element of the table
$field = $ref->field($column, $key);
# set an element of the table
$ref->set_field($column_name, $key, $value);
# atomic increment of an element of the table
$ref->inc_field($column_name, $key, 1);
# see if element of the table is numeric
$is_numeric = $ref->numeric($column_name);
# Quote for SQL query purposes
$quoted = $ref->quote($value, $column_name);
# Check configuration of the database
$delimiter = $ref->config('DELIMITER');
# Find the names of the columns (not including the key)
@columns = $ref->columns();
# Insert the key column name
unshift @columns, $ref->config('KEY');
# See if a column is in the table
$is_a_column = defined $ref->test_column($column_name);
# See if a row is in the table
$is_present = $ref->record_exists($key);
# Create a subroutine to return a single column from the table
$sub = $ref->field_accessor($column);
for (@keys) {
push @values, $sub->($key);
}
# Create a subroutine to set a single column in the database
$sub = $ref->field_settor($column);
for (@keys) {
$sub->($key, $value);
}
# Create a subroutine to set a slice of the database
$sub = $ref->row_settor(@columns);
for (@keys) {
$sub->($key, @values);
}
# Retrurn a complete array of the database (minus the key)
@values = $ref->row($key);
# Retrurn a complete hash of the database row (minus the key)
$hashref = $ref->row_hash($key);
# Delete a record/row from the table
$ref->delete_record($key);
A hash of
SQL databases that you shared with the
[mvasp tables="foo"]
parameter to the tag call. It returns the
DBI database handle, so you can do things like:
<%
my $dbh = $SQL{products}
or return HTML "Database not shared.";
my $sth = $dbh->prepare('select * from products')
or return HTML "Couldn't open database.";
$sth->execute();
my @record;
while(@record = $sth->fetchrow()) {
foo();
}
$sth = $dbh->prepare('select * from othertable')
or return HTML "Couldn't open database.";
$sth->execute();
while(@record = $sth->fetchrow()) {
bar();
}
%>
ONCE AGAIN, this will not work with unless AllowGlobal is set for your catalog. And full ``use strict'' checking is in force.
A search object which will search a database without
using the text file. It is the same as MiniVend's db searchtype. Options are specified in a hash and passed to the object. All
multiple-field options should be passed as array references.
Before using the $DbSearch object, you must tell it which
table to search -- to use the table foo it must have been shared with [mvasp foo].
There are three search methods -- array, hash, and list.
array Returns a reference to an array of arrays (best)
hash Returns a reference to an array of hashes (slower)
list Returns a reference to an array of tab-delimited lines
Example:
$DbSearch->{table} = $Db{foo};
$search = {
mv_searchspec => 'Mona Lisa',
mv_search_field => [ 'title', 'artist', 'price' ],
mv_return_fields => ['
};
my $ary = $DbSearch->array($search);
if(! scalar @$ary) {
return HTML "No match.\n";
}
for(@$ary) {
This is an object that has several routines associated with it.
HTML $foo; # Append $foo to the write buffer array
$Document->write($foo); # object call to append $foo to the write
# buffer array
$Document->insert($foo); # Insert $foo to front of write buffer array
$Document->header($foo, $opt); # Append $foo to page header
$Document->send(); # Send write buffer array to output, done
# automatically upon end of ASP, clears buffer
# and invalidates $Document->header()
$Document->hot(1); # Cause writes to send immediately
$Document->hot(0); # Stop immediate send
@ary = $Document->review(); # Place contents of write buffer in @ary
$Document->replace(@ary) # Replace contents of write buffer with @ary
$ary_ref = $Document->ref(); # Return ref to output buffer
Write $foo to the page in a buffered fashion. The buffer is an
array that is the results of all previous $Document->write() operations. If $Document->hot(1) has been set, the output immediately
goes to the user.
Insert $foo to the page buffer.
$Document->write("23");
$Document->insert("1");
$Document->send();
will output ``123'', while
$Document->write("23");
$Document->write("1");
$Document->send();
will output ``231''.
Add the header line $foo to the
HTTP header. You can use this to change the page
content type, cache options, or other attributes.
The below code changes the content type (MIME type) to text/plain:
$Document->header("Content-type: text/plain");
There is an option hash that can be sent, with the only valid value being ``replace''. The below code scrubs all previous header lines:
$Document->header("Content-type: text/plain", { replace => 1 } );
Once you have sent output with $Document->send(), this can no longer be done.
If the value of $foo is true (in a Perl sense), then all
$Document->write() operations will be immediately sent until a
$Document->hot(0) is executed.
Causes the document write buffer to be sent to the browser and empties the buffer. Any further $Document->header() calls will be ignored.
Can be used to implement non-parsed-header operation.
Returns the value of the write buffer.
@ary = $Document->review();
Completely replaces the write buffer with the arguments.
Returns a reference to the write buffer.
# Remove the first item in the write buffer
my $ary_ref = $Document->ref();
shift @$ary_ref;
Writes a string (or list of strings) to the write buffer array. The call
HTML $foo, $bar;
is exactly equivalent to
$Document->write($foo, $bar);
Honors the $Document->hot() setting.
A reference to the current shopping cart. Unless you have used a MiniVend
[cart ...] tag, it is normally the same as $Carts->{main}.
A reference to the scratch values ala [scratch foo].
<% $Scratch->{foo} = 'bar'; %>
is equivalent to:
[set foo]bar[/set]
A reference to the session values ala [data session username].
<%
my $out = $Session->{browser};
$Document->write($out);
%>
is equivalent to:
[data session browser]
You can also set values. If you wanted to change the value of
[data session source], for example, you could do:
<%
$Session->{source} = 'New_partner';
%>
Using the $Tag object, you can access any MiniVend tag
including user-defined tags.
IMPORTANT NOTE: If the tag will access a database that has not been previously opened, you must pass in the table name in the ASP call, i.e.:
# HTML style
<HTML MV="mvasp" MV.TABLES="products pricing">
or
# Named parameters
[mvasp tables="products pricing"]
or
# Positional parameters
[mvasp products pricing]
Any tag can be called.
<%
my $user = $Session->{username};
my $name_from_db = $Tag->data('userdb', 'name', $user );
$Document->write($name_from_db);
%>
is the same as:
[data table=userdb column=name key="[data session username]"]
If the tag has a dash (-) in it, use an underscore instead:
# WRONG!!!
$Tag->shipping-desc('upsg');
# Right
$Tag->shipping_desc('upsg');
There are two ways of specifying parameters. You can either use the positional parameters as documented (for an authoritative look at the parameters, trace the %Routine value in Vend::Parse), or you can specify it all with an option hash parameter names as in any named parameters as you would specify in a MiniVend tag. The calls
$Tag->data('products', 'title', '00-0011');
and
my $opt = {
table => 'products',
column => 'title',
key => '00-0011',
};
$Tag->data( $opt );
are equivalent for the data tag.
If you are using the option hash method, and the tag has container text,
you can either specify it in the hash parameter body or add it as the next argument. The two calls:
$Tag->item_list( {
'body' => "[item-code] [item-field title]",
});
and
$Tag->item_list( { }, "[item-code] [item-field title]")
are equivalent.
Parameter names are ALWAYS lower case.
A reference to the user form values ala [value foo].
<% $Document->write($Values->{foo}); %>
is equivalent to:
[value foo]
Send a message to the error log (same as ::logError in GlobalSub or global UserTag).
<%
Log("error log entry");
%>
It prepends the normal timestamp with user and page information. To supress
that information, begin the message with a backslash (\).
<%
Log("\\error log entry without timestamp");
Log('\another error log entry without timestamp');
Log("error log entry with timestamp");
%>