include( "db_mysql.inc" );
include( "class.FastTemplate.php3" );
include( "class.rfkmap.php3" );
$tpl = new FastTemplate( "/path/to/templates" );
$tpl->define( array ( "main" => "main.tpl" ));
$cBooks = new RFKmap( $tpl, "Books",
array ( "view_list" => "booklist.tpl",
"view_item" => "bookitem.tpl",
"view_only" => "bookonly.tpl" ));
$tpl->assign(TITLE_A, "List of spanish's books.");
$cBooks->view_list( $tpl, "", "spanish", "", " LIMIT 0,5" );
$cBooks->view_list_parse( $tpl, "CONTENT_A" );
$tpl->assign(TITLE_B, "Details of a spanish book.");
$cBooks->view_only( $tpl, "2", "spanish" );
$cBooks->view_only_parse( $tpl, "CONTENT_B" );
$tpl->parse(CONTENT, "main");
$tpl->FastPrint(CONTENT);
What is a template?
A template is a text file with variables in it. When a template is parsed, the variables are interpolated to text. (The text can be a few bytes or a few hundred kilobytes.) Here is a simple template with one variable ('{NAME}'):
Hello {NAME}. How are you?
When are queries and templates useful?
Templates are very useful for CGI programming, because adding HTML to your PHP code clutters your code and forces you to do any HTML modifications. By putting all of your HTML in seperate template files, you can let a graphic or interface designer change the look of your application without having to bug you, or let them muck around in your PHP code.
Now, it's no necessary to make personalized PHP code for each dynamic's page to access a database queries. In a one sentence it's possible to do a complicated QUERY, mapping a SQL relationship from 1, 2 or 3 tables.
Why use RFKmap?
Speed
RFKmap executes joins, queries and parses in one step with a single regular expression.
Flexibility
The API is robust and flexible, and allows you to build very complex documents/interfaces from a database's queries. It is also completely written in PHP and work on Unix or NT. Also, it isn't restricted to building HTML documents -- it could be used to build any ascii based document (postscript, XML, email - anything).
These are outlined in detail in CORE METHODS below.
This is a constructor's class method. Requires three parameters; ref_template_var to use the global template variable; KEY which defines the map database object; and an array which it defines template filenames.
When the new() method is complete, the configuration
has been readed, and the instance is ready to use.
Maps a template filename to a (usually simpler) identify name.
$cBooks = new RFKmap( $tpl, "Books",
array ( "view_list" => "booklist.tpl",
"view_item" => "bookitem.tpl",
"view_only" => "bookonly.tpl" ));
The tags view_list, view_item and view_only are the names that RFKmap will use to refer to the templates
about the especific KEY mapping. If it isn't redeclared, the system uses the templates-files defined in table TemplatesDefinition.
Note: This is a required step and all parametres are not empty.
The method view_only() creates the query from the parameters and assigns ALL values for variables from fields of table's databases (complex queries) but only returns 1 or empty result.
In order for a variable in a template to be interpolated it must be assigned, but I use a timestamp flag
to prevent duplicated assigned variables.
$cBooks = new RFKmap( $tpl, "Books",
array ( "view_list" => "booklist.tpl",
"view_item" => "bookitem.tpl",
"view_only" => "bookonly.tpl" ));
$cBooks->view_only( $tpl, "2", "spanish" );
Definition RFKmap object:
| Table | Field | Value | Description |
|---|---|---|---|
| TypeDefinition | guid | 1 | |
| TypeDefinition | typename | Books | key |
| TableDefinition | guid | 1 | |
| TableDefinition | unique_table | BookUnique | Name of table 1 |
| TableDefinition | multiple_table | BookLanguage | Name of table 2 |
| TableDefinition | relation_table | Name of table 3 | |
| TableDefinition | unique_primary | id_book | select_unique parameter and field-identifier from table 1 |
| TableDefinition | multiple_select | language | select_multiple parameter and field-identifier from table 2 |
| TableDefinition | relation_select | select_retaltion parameter and field-identifier from table 3 |
Mapping example:
| Key | Table | Fields | RFKmap template variables | |
|---|---|---|---|---|
| Books | BookUnique | id_book | BOOKS_BOOKUNIQUE_ID_BOOK | select_unique identifier |
| Books | BookUnique | author | BOOKS_BOOKUNIQUE_AUTHOR | |
| ... | ... | ... | ... | |
| Books | BookLanguage | id_book | BOOKS_BOOKLANGUAGE_ID_BOOK | select_unique identifier |
| Books | BookLanguage | language | BOOKS_BOOKLANGUAGE_ID_LANGUAGE | select_multiple identifier |
| Books | BookLanguage | title | BOOKS_BOOKLANGUAGE_TITLE | |
| Books | BookLanguage | abstract | BOOKS_BOOKLANGUAGE_ABSTRACT | |
| ... | ... | ... | ... |
Now, the RFKmap template variables contain the data from specific database's table.
Template's file example:
| Internal use | Filename | Contents |
|---|---|---|
| view_only | bookonly.tpl |
<B>{BOOKS_BOOKLANGUAGE_TITLE}</B>
<BR>
{BOOKS_BOOKUNIQUE_DATEINS} - <U>{BOOKS_BOOKUNIQUE_AUTHOR}</U>
<BR>
{BOOKS_BOOKLANGUAGE_ABSTRACT}
|
NOTE: The function view_only() returns 0 if not element perfoms the query or 1 if one element is reached.
The method view_only_parse() is the main function in RFKmap to print the result of query
invocated with the previous function view_only().
$result = $cNews->view_only( $tpl, "2", "spanish" );
if ($result) {
$cNews->view_only_parse( $tpl, "CONTENT_B" );
}
NOTE: The HANDLE variable is optionally, and default uses the name of the RFKmap's key; at the example will be BOOKS
The append style allows you to append the parsed results to the target variable [HANDLE]. It uses the dot . philosophy from FastTemplate to append the parsed results of this template to the returned results. This is most useful when building dynamic zones that have multiples result queries - such as data from a 2 or more database query from RFKmap.
$result = $cTop->view_only( $tpl, "10", "lang_es", "section18" );
if ($result) {
$cTop->view_only_parse( $tpl, "CENTRAL_ZONE" );
}
$result = $cNews->view_only( $tpl, "15", "lang_es", "", " AND u.Activate='Y' " );
if ($result)
$cNews->view_only_parse( $tpl, "CENTRAL_ZONE" );
}
The method view_list() creates the query from the parameters and assigns ALL values for variables from fields of table's databases (complex queries).
In order for a variable in a template to be interpolated it must be assigned, but I use a timestamp flag
to prevent duplicated assigned variables.
Using the template assigned at the view_item variable in the constructor, this functions maps all results from the query to an internal variable named KEY_LIST, in the example will be BOOKS_LIST, which it will be present in the view_list filename template assigned.
$cBooks = new RFKmap( $tpl, "Books",
array ( "view_list" => "booklist.tpl",
"view_item" => "bookitem.tpl",
"view_only" => "bookonly.tpl" ));
$cBooks->view_list( $tpl, "", "spanish", "", " LIMIT 0,5" );
NOTE: This example searches 5 results from a query which select_multiple variable haves content 'spanish'.
Template's file example:
| Internal use | Filename | Contents |
|---|---|---|
| view_list | booklist.tpl |
<TABLE BORDER="1">
<TR>
<TH>Title</TH>
<TH>Author</TH>
<TH>Date</TH>
<TH>Details</TH>
</TR>
{BOOKS_LIST}
</TABLE>
|
| view_item | bookitem.tpl |
<TR>
<TD>{BOOKS_BOOKLANGUAGE_TITLE}</TD>
<TD>{BOOKS_BOOKUNIQUE_AUTHOR}</TD>
<TD>{BOOKS_BOOKUNIQUE_DATEINS}</TD>
<TD><a href="example.php3?id_book={BOOKS_BOOKUNIQUE_ID_BOOK}">Details</a></TD>
</TR>
|
Interesting: In release 1.4 added a internal sequential code using the next format KEY_ID. Is useful in HTML forms to make arrays or similar.
The method view_list_parse() is the main function in RFKmap to obtain a list result
of query invocated with view_list() method.
$cBooks = new RFKmap( $tpl, "Books",
array ( "view_list" => "booklist.tpl",
"view_item" => "bookitem.tpl",
"view_only" => "bookonly.tpl" ));
$result = $cBooks->view_list( $tpl, "", "spanish", "", " ORDER BY p.title GROUP BY r.id_sector " );
if ($result) {
$cBooks->view_list_parse( $tpl, "LIST_OF_BOOKS" );
} else {
$tpl->assign( "LIST_OF_BOOKS", "No books in spanish language" );
}
The HANDLE variable is optionally, and default uses the name of the RFKmap's key; at the example should be BOOKS
NOTE: The append style allows you to append the parsed results to the target variable [HANDLE].
The method view_only_fetch() returns the raw data from a parsed handle.
$cBooks->view_only( $tpl, "2", "spanish" );
$content = $cBooks->view_only_fetch( $tpl );
print $content; // print to STDOUT
fwrite($fd, $content); // write to filehandle
$tpl->assign( "CONTENT", $content ); // assign to another FastTemplate variable
The method view_list_fetch() returns the raw data from a parsed handle.
$cBooks->view_list( $tpl, "", "spanish" );
$content = $cBooks->view_list_fetch( $tpl );
print $content; // print to STDOUT
fwrite($fd, $content); // write to filehandle
$tpl->assign( "CONTENT", $content ); // assign to another FastTemplate variable
The method view_only_eval() evaluate code stored in register's database.
$cPhp = new new RFKmap( $tpl, "PHPCODE" );
$cPhp->view_only( $tpl, "2" );
-- First option --
$cPhp->view_only_eval( $tpl, "DATE" );
-- Second option [in RFKmap 1.3 or earlier] --
eval( $cPhp->view_only_fetch( $tpl ) );
$tpl->assign( "DATE", "$output" );
NOTE: View example2.php3 to see sample code about this new function.
This method will return the value of the variable that has been set via view_only_fetch() or view_only_parse(). This allows you
to easily pass variables around within functions by using the RFKmap class to handle parsed or assigned global variables. For example;
$cBooks->view_only( $tpl, "2", "spanish" );
$cBooks->view_only_parse( $tpl );
$author = $cBooks->get_assigned( $tpl, "BOOKS_BOOKUNIQUE_AUTHOR" );
The method get_assigned_unique() operates equal than get_assigned(), but it's useful when
you redefine, redeclare or recall one RFKmap object or function, and then uses the internal timestamp (GUID
unique by object and parsed variables) to select an assigned global variable.
The method internal_create_query() must not been called from you PHP code page. It's only for internal procedure.
The RFKmap classes has been tested using Apache 1.3.9 webserver, MySQL 3.22 database engine, FastTemplate 1.1.0, PHPLIB 6.2, and PHP 3.0.9 over Linux and Windows systems.
Using database access
Edit class.rfkmap.php3 and modify the class DBCORE() and put your database connectivity values (host, database, user and password)
In MYSQL exists the function SHOW FIELDS FROM tablename which it's necessary to run the RFKmap engine. If you are using another database engine search a similar method to obtain the name of the fields from table's databases and send me your results.
This version of RFKmap support a maximun of three relationated tables (see example 3) in an object, which a common field in all tables (3 tables)
| 1st table | 2nd table | 3rd table | |
|---|---|---|---|
| internal table | unique_table | multiple_table | relation_table |
| using in query plus | u. | p. | r. |
Example 1: One table
RFKmap key: ObjCompany
| Tablename | unique_select name | other fields |
|---|---|---|
| Company | id_company | name, address, phone, ... |
Example 2: Two tables
RFKmap key: ObjEmployeed
| Tablename | unique_select name | multiple_select name | other fields |
|---|---|---|---|
| Company | id_company | name, address, phone, ... | |
| Employeed | id_company | id_employeed | surname, activity, email, phone, ... |
Example 3: Three tables
RFKmap key: ObjSector
| Tablename | unique_select name | multiple_select name | relation_select name | other fields |
|---|---|---|---|---|
| Company | id_company | name, address, phone, ... | ||
| Activity | id_company | id_activity | activity, ... | |
| Sector | id_company | id_sector | sector_name, region, ... |
RFKmap example:
$cCompanyOnly = new RFKmap( $tpl, "ObjCompany",
array ( "view_list" => "companyA-list.tpl",
"view_item" => "companyA-item.tpl",
"view_only" => "companyA-only.tpl" ));
$cEmployeed = new RFKmap( $tpl, "ObjEmployeed",
array ( "view_list" => "employeed-list.tpl",
"view_item" => "employeed-item.tpl",
"view_only" => "employeed-only.tpl" ));
$cSector = new RFKmap( $tpl, "ObjSector",
array ( "view_list" => "none.tpl",
"view_item" => "none.tpl",
"view_only" => "sector-only.tpl" ));
$cCompanyOnly->view_list( $tpl, "", "", "", " ORDER BY u.name" );
$result = $cCompanyOnly->view_list_parse( $tpl, "CONTENT" );
$tpl->assign(TOTAL_COMPANY, "There are $result companys.");
$cSector->view_only( $tpl, "", "Engineering", "Manufacturer", " GROUP BY r.id_company " );
$id_activity = $cSector->get_assigned( $tpl, "OBJSECTOR_ACTIVITY_ID_ACTIVITY" );
$cEmployeed->view_list( $tpl, "", "", "", " AND p.id_activity = '$id_activity' ORDER BY u.name" );
$cEmployeed->view_list_parse( $tpl, "CONTENT" );
$cEmployeed->view_only( $tpl, "15", "Administrative", "", " AND p.id_activity = '$id_activity'" );
$result = $cEmployeed->view_only_parse( $tpl, "CONTENT" );
You're reading it.
Revision 1.4 - Aug 19, 2001 © RFK Solutions <rfksolutions@users.sourceforge.net>
1.4 Added support for predefined templates in database table, and added view_only_eval() for evaluating php code. Version released Aug 19, 2001.
1.3 Added get_assign() and get_assign_unique() methods to obtain internal assigned variables. Version released Jul 07, 2001.
1.2 Added view_only_fetch() method and view_list_fetch() method to obtain a PHP variable from an executed query-mapped. Version not released.
1.1 Added a new constructor class DBCORE() from support DB_Sql module. Version not released.
1.0 Initial public release
This program is free software; you can redistribute it and/or modify it under the GNU General Artistic License, with the following stipulations;
Changes or modifications must retain these Copyright statements. Changes or modifications must be submitted to the author.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details. This software is distributed AS-IS.
Address Bug Reports or Comments to RFK Solutions, rfksolutions@users.sourceforge.net.
The latest version of this class should be available from the following locations:
FastTemplate PHP3 module, available from CDI - http://www.thewebmasters.net