|
7.2
PHP Interface Reference
This section describes
the commands available on the PHP interface to Turbine 7.
Initial
Scripts
We suggest
using this skeleton for starting your PHP scripts:
<?
# create the turbine object:
$turbine = new Turbine7();
#
assign a variable:
$turbine->setVariable("name", "some text");
#
select a Flash .swf template to use:
$turbine->load("template.swf");
# now generate the movie to the web browser:
$turbine->generateFlash();
#
alternatively we could generate a PDF document:
# Turbine->generatePDF();
%>
|
Alphabetical
List
Commands
|
addDataSetRow
Command
Description
Insert
a row into a DataSet created by the MakeDataSet command.
Syntax
$turbine->addDataSetRow("dataSetRow");
dataSetRow
is a coma-separated list of values to be assigned to respective
DataSet columns.
Errors
DataSetRow
parameter must be a comma-separated list of values
The specified row must be a comma separated list of values.
Remarks
Use
this command to insert values into an existing DataSet.
|
| addDataSetColumn
Command
Description
Insert
a DataSet column starting at a specified row.
Syntax
$turbine->addDataSetColumn("dataSetName",
"columnName", startRowNumber, "values");
dataSetName
is the name of the DataSet to define.
columnName is the name of an existing or new DataSet
column.
startRowNumber is the number of a new or existing DataSet
row where to start placing the column values.
values is a comma separated list of values to place on
successive rows.
Errors
Values
parameter must be a comma-separated list of values
The specified values must be a comma separated list of values.
Remarks
Use
this command to insert columns into an existing DataSet.
|
|
addDataSetValue
Command
Description
Insert
a DataSet entry on a specified column and row.
Syntax
$turbine->addDataSetValue("dataSetName",
"columnName", rowNumber, "value");
dataSetName
is the name of the DataSet to define.
columnName is the name of an existing or new DataSet
column.
RowNumber is the number of a new or existing DataSet
row.
value is the value to be insert into the DataSet.
Errors
Error
setting value
An error occurred when setting the value. Check if the DataSet
already exists.
Remarks
Use
this command to insert a value into an existing DataSet.
|
|
cache
Command
Description
Cache
or serve from cache the current media, uniquely identified by
the script URL (including query string) and media type.
Syntax
$turbine->Cache("expires"
[, "mediaType"]);
expires
is the expiration date for the media with the format YYYYMMDDHHMISS.
mediaType is the media format outputted by Turbine. Currently
"flash" for Macromedia Flash and "pdf" for
Adobe PDF are available. The default value is "flash"
if not provided.
Errors
Error
serving media
An error occurred when serving the media.
The
expires parameter has bad format
Check
the expires parameter format. It should be YYYYMMDDHHMISS.
Error preparing to cache media
An
error occurred when caching the media.
|
|
cacheMedia
Command
Description
Add
the generated media to the cache, identified by the given reference.
Syntax
$turbine->cacheMedia("reference",
"expires" [, "mediaType"]);
reference
is the unique id for the cached media.
expires is the expiration date for the media with the format
YYYYMMDDHHMISS.
mediaType is the media format outputted by Turbine. Currently
"flash" for Macromedia Flash and "pdf" fo
Adobe PDF are available. The default value is "flash"
if not provided.
Errors
The expires
parameter has bad format
Check
the expires parameter format. It should be YYYYMMDDHHMISS.
Error preparing to cache media
An
error occurred when caching the media.
Remarks
The
old command CacheMovie can still be used, but we recommend that
you use the CacheMedia command instead.
|
|
create
Command
Description
Creates
a media instance from the provided MML.
Syntax
$turbine->create("mmlTags"
[, "instanceName"]);
mmlTags
is a MML string to be interpreted and included into the media.
instanceName is the name of the instance created inside
the media for later reference. By default, Turbine assumes an
unique name if no value is provided.
Errors
Out
of memory
Memory
allocation error. Is your system running out of virtual memory?
Remarks
There
are no restrictions about the MML provided to this command -
you can do everything possible in MML with this simple command.
|
|
dataSetFromString
Command
Description
Create
a DataSet from a string formatted as a DataSet file or from
a well-formed XML string.
Syntax
$turbine->dataSetFromString("string",
"dataSetName" [, "rowTag", "columnTags"]);
string
is an well-formed XML string to be parsed into a Turbine DataSet
or is a string containing a DataSet definition, on the format
of a DataSet File.
dataSetName is the name of the Turbine DataSet to create.
rowTag is the name of the XML tag to use to start a new
DataSet Row - it must be a non empty tag, with other tags inside,
to be used for the rows.
columnTags is a comma separated list of tags and/or tag
parameters to use (once parsing inside a rowTag tag) to create
DataSet columns. Check remarks to see variations on using this
parameter.
Errors
DataSet
string has bad format
The
string is not well formatted. It must be formatted according
to a DataSet file.
DataSet XML string has bad format
The
string is not well formatted. It must be valid XML.
Remarks
If
rowTag and columnTags parameters are defined then Turbine assumes
that the format os the string passed is XML formatted. It assumes
the format of DataSet file otherwise.
The
XMLDataSetFromString command is still valid although we recommend
that you use the DataSetFromString command instead.
The
columnTag parameter can be specified in a few different ways
to allow different parsing of the XML document:
| columnTags |
Effect |
| ""
(empty) |
The
text immediately after the start of each rowTag will be
used for the only column in the DataSet, this column will
be named after the rowTag name |
| "tag1,
tag2, tag3,..". |
The
DataSet will feature the specified columns, composed by
the text immediately inside each of these tags, for each
rowTag |
| "tag1#attr1,
tag2#attr2" |
Each
tag marked with an hash will contribute with the text
of the attr1 or attr2 attribute inside the
respective tag, for example:
<tag1 attr1="some"/> <tag2 attr2="times"/>
would use the text "some" and "times"
for successive columns inside the created DataSet. The
created DataSet columns would be called "tag1#attr2"
and "tag2#attr2" |
| "tag1#attr1=alias1,
tag2#attr2=alias2" |
Just
like the above, but the columns will be defined on the DataSet
with the column name specified in alias1 and alias2.
This is important for some commands that depend on column
names like the AutoImage or AutoMovieClip |
XML
entity references like & and > will be accordingly
expanded on the read values.
Equivalent
MML
The
MML equivalent to this command is <DataSet>
|
|
include
Command
Description
Includes
a media file into Turbine. The media file can be a Macromedia
Flash file or a MML file.
Syntax
$turbine->include("location");
location
is an absolute or relative filename or a URI pointing to the
file to include.
Errors
Could
not access media or template
The
location specified could not be found.
Could not
load media or template
The
file was found but it could not be read.
Remarks
This
command includes the media but does not place its elements.
This is useful for including libraries of components for later
instantiation.
Equivalent
MML
The
MML equivalent to this command is <Include>
|
|
generate
Command
Description
After
all the content has been defined, it's time to actually generate
the media and send it into the web browser.
Syntax
$turbine->generate(["mediaType"]);
mediaType
is the media format outputted by Turbine. Currently "flash"
for Macromedia Flash and "pdf" for Adobe PDF are available.
The default value is "flash" if not provided.
Errors
Out
of memory generating media
Memory
allocation error while generating the file. Is your system running
out of virtual memory?
Could not
include debug window
The
Turbine Window could not be found.
Error
generating media
There
was an error generating media.
|
|
generateFlash
Command
Description
After
all the content has been defined, it's time to actually generate
the Flash movie and send it into the web browser.
Syntax
$turbine->generateFlash();
Errors
Out of
memory generating Flash
Memory
allocation error while generating the file. Is your system running
out of virtual memory?
Could not
include debug window
The
Turbine Window could not be found.
Error
generating Flash
There
was an error generating Flash.
Remarks
This
is a convenience command, equivalent of calling the command
generate with "flash" as its only argument.
|
| GenerateHTMLFirst
Command
Description
Generate
an HTML page with the HTML plug-in to embed the generated media.
This page will in turn load the generated media.
Syntax
$turbine->generateHTMLFirst(["pluginHTMLPage"]);
plugin_html_page
is the path to an HTML page with the media plug-in. The default
value is the HTML file "flashplugin.htm" located on
the Turbine installation directory.
Optionally this argument can be interpreted as a media type,
and as such it can be "pdf" or "flash".
In this case the default HTML page for the specified media will
be used.
Errors
Could
not open the HTML plugin page
The specified HTML plug-in page could not be found.
Remarks
The
GenerateHTMLFirst command detects if the request is the first
for this media and if so generates an HTML plug-in page that
in turn loads the requested media.
If an HTML plug-in page is not supplied then the default "flashplugin.htm"
file, on the Turbine installation directory is used instead.
The HTML plug-in page can use Turbine variables, as they will
be expanded accordingly. For a good example, please check the
supplied default "flashplugin.htm" file.
Please note that to use variables like {Media.Color} or {Media.Width},
this command should only be issued after one or more
Turbine.Load commands are executed, or they will not be defined.
|
|
generateToFile
Command
Description
Assemble
the Flash template and save the resulting media into a local
file.
Syntax
$turbine->generateToFile("filename"
[, "mediaType"]);
filename
is the relative or absolute location of the file to save.
mediaType is the media format outputted by Turbine. Currently
"flash" for Macromedia Flash and "pdf" for
Adobe PDF are available. The default value is "flash"
if not provided.
Errors
Out
of memory generating media file
Memory
allocation error while generating the file. Is your system running
out of virtual memory?
Could not
save file
Could
not create or overwrite the destination file. Check the directory/file
permissions, and if they're compatible with the running web server user
account.
Error
generating media to file
Could
not create or overwrite the destination file. Check the directory/file
permissions, and if they're compatible with the running web server user
account.
|
|
generatePDF
Command
Description
After
all the content has been defined, it's time to actually generate
the PDF document and send it into the web browser.
Syntax
$turbine->generatePDF();
Errors
Out of
memory generating PDF
Memory
allocation error while generating the file. Is your system running
out of virtual memory?
Could not
include debug window
The
Turbine Window could not be found.
Error
generating PDF
There
was an error generating PDF.
Remarks
This
is a convenience command, equivalent of calling the command
Generate with "pdf" as its only argument.
|
|
getDataSetColumnCount
Command
Description
Gets
the number of columns associated with a given DataSet.
Syntax
$turbine->getDataSetColumnCount("dataSetName");
DataSetName
is the name of the DataSet to get the number of columns.
Return
Values/Errors
Returns
the number of columns of the DataSet.
DataSet
not found
The
given DataSet was not found.
|
|
getDataSetRowCount
Command
Description
Gets
the number of rows associated with a given DataSet.
Syntax
$turbine->getDataSetRowCount("dataSetName");
DataSetName
is the name of the DataSet to get the number of rows.
Return
Values/Errors
Returns
the number of rows of the DataSet.
DataSet
not found
The
given DataSet was not found.
|
| HTTPGet
Command
Description
Fetch
an HTTP URL and returns the result formatted as a String.
Syntax
$turbine->HTTPGet("httpUrl");
httpUrl
might be an absolute(normal) HTTP URL or a relative (to the
current script). Relative URLs are in the form http://./relative_location
Return
Values/Errors
Returns
the result of the get in String format.
Could
not access http URL
The URL is not available.
The http
URL has a bad format
Check
the syntax of your URL.
Remarks
Useful
to fetch HTML pages or CGI results from other servers.
|
| IEOptimize
Command
Description
Avoid
Internet Explorer multiple request problem.
Syntax
$turbine->IEOptimize();
Errors
No
errors are raised by this command.
Remarks
Must
not be used on the same script as the GenerateHTMLFirst command.
|
|
injectData
Command
Description
Injects
data into an instance of a Flash component.
Syntax
$turbine->injectData("dataSetName",
"instanceName" [, "id"]);
dataSetName
is the Turbine DataSet to inject into the Flash component.
instanceName is the instance of the Flash component into
which to inject data.
id is the id of the Flash component. It may be necessary
if Turbine can't figure out the id by the instanceName argument.
Errors
Out of
memory
Memory
allocation error. Is your system running out of virtual memory?
Equivalent
MML
The
MML equivalent to this command is <InjectData>
|
| load
Command
Description
Loads
a media file into Turbine. The media file can be a Macromedia
Flash .swf file or an MML file.
Syntax
$turbine->load("location"
[, "instanceName"]);
location
is an absolute or relative filename or a URI pointing to the
file to load.
instanceName is the name of the instance created inside
the media for later reference. By default, Turbine assumes an
unique name if no value is provided.
Errors
Could
not access media or template
The
location specified could not be found.
Could not
load media or template
The
file was found but it could not be read.
Remarks
This
command loads and displays the external media - it should be
used to load a single template file - to load multiple external
files it's preferable to use an MML block with a series of MML
<MovieClip> tags, which avoids any confusions with the
relative depths at which the loaded media appears.
Equivalent
MML
The
MML equivalent to a <MovieClip>
command with the src parameter.
|
|
loadDataSet
Command
Description
Load
a Turbine DataSet from a local file or HTTP location.
Syntax
$turbine->loadDataSet("location",
"dataSetName" [, "rowTag", "columnTags"]);
location
is the absolute or relative local path, or HTTP location of
the file.
dataSetName is the name of the Turbine DataSet to create.
rowTag is the name of the XML tag to use to start a new
DataSet Row - it must be a non empty tag, with other tags inside,
to be used for the rows.
columnTags is a comma separated list of tags and/or tag
parameters to use (once parsing inside a rowTag tag) to create
DataSet columns. Check remarks to see variations on using this
parameter.
Errors
Could
not access DataSet file
The
location specified for the DataSet file can not be reached.
DataSet file has bad format
Check the contents of your file to make sure they are in the
right format.
Could not
access DataSet XML file
The
location specified for the XML file can not be reached.
DataSet
XML file has bad format
Check
the contents of your file to make sure they are in the right
format.
Remarks
If
rowTag and columnTags parameters are defined then Turbine assumes
that the the file is XML formatted. It assumes the format of
DataSet file otherwise.
The
LoadDataSetFile and LoadXMLDataSetFile commands are still valid
although we recommend that you use the LoadDataSet command instead.
The
columnTag parameter can be specified in a few different ways
to allow different parsing of the XML document:
| columnTags |
Effect |
| ""
(empty) |
The
text immediately after the start of each rowTag will be
used for the only column in the DataSet, this column will
be named after the rowTag name |
| "tag1,
tag2, tag3,..". |
The
DataSet will feature the specified columns, composed by
the text immediately inside each of these tags, for each
rowTag |
| "tag1#attr1,
tag2#attr2" |
Each
tag marked with an hash will contribute with the text
of the attr1 or attr2 attribute inside the
respective tag, for example:
<tag1 attr1="some"/> <tag2 attr2="times"/>
would use the text "some" and "times"
for successive columns inside the created DataSet. The
created DataSet columns would be called "tag1#attr2"
and "tag2#attr2" |
| "tag1#attr1=alias1,
tag2#attr2=alias2" |
Just
like the above, but the columns will be defined on the DataSet
with the column name specified in alias1 and alias2.
This is important for some commands that depend on column
names like the AutoImage or AutoMovieClip |
XML
entity references like & and > will be accordingly
expanded on the read values.
Equivalent
MML
The
MML equivalent to this command is <DataSet>
|
| loadDataSet*
Function
Description
Import
the results of a database query into a Turbine DataSet. Available
on the libraries/dataset_import.php library script.
Syntax
$turbine->loadDataSet*($turbine,
$recordSet, "dataSet");
*
is the database type - MySQL, ODBC, depending on the functions
defined on dataset_import.php
$recordSet contains the results of a query
dataSet is the name of the Data Set to define,
Errors
Using
this this command can cause the usual PHP row fetching errors.
Remarks
Fields
with a NULL value will translate to empty Data Set cells.
|
| loadVar
Command
Description
Load
Turbine variables from a local file or HTTP location.
Syntax
$turbine->loadVar("location");
location
is an absolute or relative filename or a URI pointing to the
Variables file to load.
Errors
Could
not access variables file
The
location specified could not be found.
Variables
file has bad format
The
file was found but it could not be read. Check the syntax of
your Variable file.
Remarks
The
old command LoadVariableFile can still be used, but we recommend
that you use the LoadVar instead.
Equivalent
MML
The
MML equivalent to this command is <Var>
|
| makeDataSet
Command
Description
Initialize
a DataSet with the supplied columns.
Syntax
$turbine->makeDataSet("dataSetName",
"columns");
dataSet
is the name of the DataSet to define.
columns is a coma separated list of column names the
DataSet will have.
Errors
DataSetRow
parameter must be comma-separated
The specified row must be a comma separated list of values.
Equivalent
MML
The
MML equivalent to this command is <DataSet>
|
|
publishVar
Command
Description
Publishes
Turbine variables to Flash Action Script (AS).
Syntax
$turbine->publishVar("varNames"
[, "toFormat", "arrayName", "instanceName"]);
varNames
is a comma separated string with the names of the variables
to publish into AS.
toFormat is the AS variable type where the variables
are going to be published.
arrayName
is the name given to the AS array.
instanceName is the name of the instance created inside
the media in where the AS variables will be defined. By default,
Turbine assumes an unique name if no value is provided.
Errors
Out of
memory publishing variables
Memory allocation error. Is your system running out of virtual
memory?
varNames
argument has bad format
Check the syntax of param varNames.
Remarks
The
default behavior for this command (when only the first param
is provided) is publishing to AS variables with the same name
as the Turbine variables.
Variable
names which contain the characters '.' or '$' will be translated
to '_'.
The
ToFormat param can have the following values:
| toFormat |
Effect |
| "array" |
the
variables are published to an AS array. The first variable
will be placed in the first position of the array, the second
in the second position and so on. |
| "namedArray" |
the variables are published to an AS named array, using
the original variable names as String indexes |
| ""
(empty) |
empty
string, means the variables are published individually
and will use their original names as AS variables |
This
command is only useful for Flash output.
Equivalent
MML
The
MML equivalent to this command is <PublishVar>
|
|
publishDataSet
Command
Description
Publishes
a Turbine DataSet to a Flash Action Script (AS) array or named
array.
Syntax
$turbine->publishDataSet("dataSetName"
[, "toFormat", "arrayName", "instanceName"]);
dataSetName
is the Turbine DataSet to publish into AS.
toFormat is the AS type where the DataSet is going to
be published.
arrayName
is the name given to the AS array.
instanceName is the name of the instance created inside
the media in where the AS variables will be defined. By default,
Turbine assumes an unique name if no value is provided.
Errors
Out of
memory publishing DataSet
Memory allocation error. Is your system running out of virtual
memory?
DataSet
not found
The DataSet provided wasn't found.
Error
publishing DataSet
There was a generic error when trying to publish.
Remarks
The
default behavior for this command (when only the first param
is provided) is publishing to individual AS variables.
The
ToFormat param can have the following values:
| toFormat |
Effect |
| "array" |
the
DataSet is published to an AS bi dimensional array, mapping
each row and column of the DataSet to the same row and column
of the array |
| "namedArray" |
identical to the previous format, except that the column
names of the DataSet will be used as one index for the AS
named array |
| ""
(empty) |
empty
string, means the DataSet is published to individual AS
variables using the syntax 'dataSetName_ColumnName_RowNumber' |
This
command is only useful for Flash output.
Equivalent
MML
The
MML equivalent to this command is <PublishDataSet>
|
|
reset
Command
Description
Clears
the memory of Turbine which causes the associated media to also
be cleared. Usually this command is used when generating several
files to disk where you must clear the previous media before
starting the new one.
Syntax
$turbine->reset();
Errors
No
errors are raised by this command.
|
|
script
Command
Description
Compiles
a Flash Action Script (ECMA-262 Script or JavaScript language)
block.
Syntax
$turbine->script("script");
script
is the Flash AS to insert into Turbine.
Errors
Out
of memory
Memory
allocation error. Is your system running out of virtual memory?
Script
compilation error
The script did not compile because it has syntactic errors.
Remarks
Accepts
scripts compatible with Flash MX scripting.
Equivalent
MML
The
MML equivalent to this command is <Script>
|
|
serveCached
Command
Description
Serve
media cached with the given reference.
Syntax
$turbine->serveCached("reference"
[, "mediaType"]);
reference
is the unique id for the cached movie. The movie must have been
cached by the Turbine.CacheMovie command.
mediaType is the media format outputted by Turbine. Currently
"flash" for Macromedia Flash and "pdf" for
Adobe PDF are available. The default value is "flash"
if not provided.
Return
Values/Errors
Returns
true if the media was served from the cache, false if no valid
media was found on the cache or if an error occurred.
Error
serving media
An error occurred when serving the media.
|
| setVariable/setVar
Command
Description
Sets/gets
a Turbine variable.
Syntax
$turbine->setVariable("name",
value);
$turbine->setVar("name", value);
name
is the name of the Turbine variable to set/get.
value is the value to set.
Errors
Variable
name is too big
The
variable name is too long. Use a shorter name.
Could not set value
An
error occurred when setting the value.
|
| showFrame
Command
Description
Causes
Turbine to display the current frame and start a new one.
Syntax
$turbine->showFrame(["numFrames"]);
numFrames
is the number of frames to show, by default 1.
Errors
No errors are raised by this command.
Remarks
Frames
are translated to PDF pages, so this command will add a new
page when outputting to PDF format.
|
Properties
The following
functions get and set Turbine properties:
| baseDirectory
Property
Description
Gets
the baseDirectory which is the location of the PHP script, which
serves as a base for any relative file locations.
Syntax
$baseDir
= $turbine->baseDirectory();
Errors
This
property raises no trappable errors.
|
| binDirectory
Property
Description
Gets
the binDirectory which is the directory where Turbine is installed
and where the configuration files are located.
Syntax
$binDir
= $turbine->binDirectory();
Errors
This
property raises no trappable errors.
|
| color
Property
Description
Sets/gets
the current background color of the media.
Syntax
$turbine->color("#RRGGBB");
$backgroundColor = $turbine->color();
color
is a string representing the background color of the media with
the format #RRGGBB.
Errors
Could
not set value
An
error occurred when setting the value.
|
| compress
Property
Description
Sets/gets
the compression rate of the output media.
Syntax
$turbine->compress($level);
$level = $turbine->compress();
compress
is the compress rate of the output media. A value of 0 means
that compression is switched off and a value of 9 means that
the media will be highly compressed.
Errors
Could
not set value
An
error occurred when setting the value.
|
| debug
Property
Description
Shows/hides
the Turbine Window for debugging and logging.
Syntax
$turbine->debug($debugSetting);
$debugSetting = $turbine->debug();
debug
set to true means that the Turbine Window will be shown.
Errors
Could
not set value
An
error occurred when setting the value.
|
| flashVersion
Property
Description
Sets/gets
the Flash version of the generated movie.
Syntax
$turbine->flashVersion("version");
$version = $turbine->flashVersion();
version
is the numeric version of the output Flash.
Errors
Could
not set variable
An
error occurred when setting the value.
Remarks
Useful
when one wishes to generate Flash with a specific version. For
instance, $turbine->flashVersion("6"), makes Turbine
output Flash MX.
|
| frame
Property
Description
Gets
or sets the current Flash movie frame or PDF page.
Syntax
$turbine->frame($frameNum);
$frameNum = $turbine->frame();
frameNum
is the zero-based current frame number.
Errors
This
property raises no trappable errors.
Remarks
Frames are
translated to PDF pages on PDF output.
|
| frameRate
Property
Description
Sets/gets
the movie framerate.
Syntax
$turbine->frameRate($fps);
$fps
= $turbine->frameRate();
fps
is the frame rate of the generated media in frames per second.
Errors
Could
not set value
An
error occurred when setting the value.
|
| height
Property
Description
Sets/gets
the native height of the media to be generated.
Syntax
$turbine->height($mediaHeight);
$mediaHeight
= $turbine->height();
mediaSize
is the native height of the media.
Errors
Could
not set value
An
error occurred when setting the value.
|
|
