WebTools Templates: Page 2.1

2.1. Templates and INLINE/INPERL templates: Syntax comparison 

  With couple of words I will explain syntax of INLINE/INPERL templates and after that I will "copy" syntax of normal templates in this document :-)). "Common" style of templates will be with "purple" color.

INLINE syntax:

  
  <!--©INLINE©> inline functions </©INLINE©-->

  OR

  <!--©INPERL©> inline functions </©INPERL©-->

 If you want use alternative style of INILINE/INPERL:

  %%%INLINE%%% inline functions %%%/INLINE%%%

  OR

  %%%INPERL%%% inline functions %%%/INPERL%%%


  <!--©INLINE©></©INLINE©--> is used to excape HTML (and repectively PERL code), so code between these "tags" will be parsed from WebTools engine. However in normal templates we use "begin" and "end" parts to mark begin and respective end of every template. In "INLINE" version we don't use same tag, for example:

<©N®1®1®®©>
     My name is <§VAR§> and I'm <§VAR§> years old.

<˜©˜>


BUT we use:   <!--©INLINE©> inline functions </©INLINE©--> tag for all INLINE (and respective tag for INPERL)
These "separators" successfully escape perl/html context and parser engine of WebTools parse all INLINE/INPERL templates! Of course you can't use absolutly same syntax to convert "normal" templates in INLINE variant.

  Supported inline functions are:

<§TEMPLATE:number_of_templates_variable:$variable:§>

<XREADER:number_of_template_in_file:template_file.jhtml:$first_param,$second_param,...>

<S©L:number_of_SQL_query:"SQL query;":used_query:row_number:col_number:should_be_printed?:S©L>

<S©LVAR:number_of_template_variable:S©L>

<MENUSELECT:$html_source:"SQL query":$ref_DB:$ref_TEMPLATE:$ref_HTML:$dbh:>


NOTE: Every INLINE template after it's execution will be substituted with respective evaluated value in place of itself!
Every INPERL template after it's execution will be substituted with NULL value in place where it's being, BUT evaluated value will appear in default variable $_ Please remember this fact!



  If prefer you can use alternative syntax for all templates!


  Supported inline functions with alternative syntax (in any other aspect they are same):

%%TEMPLATE:number_of_templates_variable:$variable:%%

%%XREADER:number_of_template_in_file:template_file.jhtml:$first_param,$second_param,...%%

%%SQL:number_of_SQL_query:"SQL query;":used_query:row_number:col_number:should_be_printed?:SQL%%

%%SQLVAR:number_of_template_variable%%

%%MENUSELECT:$html_source:"SQL query":$ref_DB:$ref_TEMPLATE:$ref_HTML:$dbh:%%



 *  Now we look at INLINE templates in detail, so arm with patience.

<§TEMPLATE:number_of_templates_variable:$variable:§>

If you want to put some data directly in your HTML or Perl code, you can use this INLINE "function", so your data will appear in place of this template. This template you can look as normal "template variable"!
As I described before "
number_of_templates_variable" is symbolic number of current template.
More interesting part of this template is $variable because you can use some PERL variable name instead of constant value.
"Normal" style of this variable is: <§VAR§>



<XREADER:number_of_template_in_file:template_file.jhtml:$first_param,$second_param,...>

Excellence way to use normal templates with INLINE/INPERL is using of this "function"!
Normal form of xreader() function is shown below:

$result_data = xreader($number_of_template, $template_file.jhtml , @substitute_variables);

Result of XREADER execution will appear in perl/html document (on place of XREADER template).
number_of_template_in_file coincide with $number_of_template, template_file.jhtml is same as $template_file.jhtml and of cource you can consider any set of two or more scalars like one array:
($first_param,$second_param,...) is absolutely equivalent with meaning of @substitute_variables
NOTE: $first_param, $second_param and so on should be Perl variables!



<S©L:number_of_SQL_query:"SQL query;":used_query:row_number:col_number:should_be_printed?:S©L>

This template is absolutely equivalent to normal templates, so I will not lose any time.
"Normal" syntax:
<S©L:number_of_sql_query:"select_SQL_query;":used_sql_query:number_of_row:number_of_column:should_print?:S©L>
NOTE: In SQL_query you can use Perl variables, so this template get realy dynamic for you!



<S©LVAR:number_of_template_variable:S©L>

You can assume same fact, that SQL variables are absolutely same such "normal" one.
"Normal" syntax:
<S©LVAR:respective_number_of_SQL_query:S©L>



<MENUSELECT:$html_source:"SQL query":$ref_DB:$ref_TEMPLATE:$ref_HTML:$dbh:>

You may suppose that this "funcion" is new and specific for INLINE world, but you may want to use as normal function via follow syntax(this function is part of xreader.pl library):

$result = MenuSelect($html_source,"SQL_query",$ref_DB,$ref_TEMPLATE,$ref_HTML,$dbh);

You should notice that "normal" and INLINE form is equivalent, so I will explain only one of them. Also you see hard terms in one place (as SQL,DB,TEMPLATES,HTML) , so I suppose you understand that this function is hard to use (that is not true) but it make serious work for us.
    What is religion here?
Let imagine that situation: You have one check box in your $html_source (for example one HTML page loaded in $html_source variable) and this check box has 5 states (in fact 5 check boxes with same names but only one of them can be checked (selected)!) Also active state of this check box is saved in database and when you need to print that html page on browser's screen you should fetch from database active state of check box and you will need to mark respective check box as active. All my words can be illustrated with follow example:

How old are you? <input type="radio" name="years" value="1" <§TEMPLATE:10§>>1-14
<input type="radio" name="years" value="2" <§TEMPLATE:11§>>15-20
<input type="radio" name="years" value="3" <§TEMPLATE:12§>>21-30

<input type="radio" name="years" value="4" <§TEMPLATE:13§>>31-50
<input type="radio" name="years" value="5" <§TEMPLATE:14§>>51 or older

Let make balance of this example: We have 5 check boxes with name "years" and every check box can accept values (1,2,3,4 and 5), also we have `special`select template (
<§TEMPLATE:number_of_template§>) that should be used from MenuSelect function! Ok, let get closer to the bottom of things:

$ref_DB is a reference to array with possible values fetched from database. In our example that could be:
(1,2,3,4,5)
$ref_TEMPLATE is a reference to array with numbers of respective templates. In our case: (10,11,12,13,14)
$ref_HTML that is a reference to array, consist of two elements. First element should be string that mark given HTML element as active and second should be string that mark respective element as non-active element! In other words template on active check box will be substituted with string that mark element as active (for check boxes you should use "checked") and for not active elements WebTools will substitute with second array's element (for check boxes that should be empty string)
('checked','')
$dbh is database handler that will be used to select active state from DB table.
  Also this function can be used with multi-select menus (i.e. you can have two or more active elements)
SQL query should be SQL query that return as result one or more valid rows with acceptable values (specified from $ref_DB). That result will determinate state of given (check box, select menu, radio button and etc.)

NOTE: SQL query can be used in follow format: "!active_value1,active_value2,....", where "!" show that SQL query is not actualy query. active_value1 and etc. are values on active check boxex, this form of SQL query can be applied when you haven't DB or you don't like to save state of these "select menu" elements! Example: "!3"  i.e 21-30 years old :)
For multiple select menus this example can be: "!2,4" and so on...

Finaly our example could be parsed on follow way:

- Let SQL query has value "!3"
- Let $ref_DB point to array of (1,2,3,4,5) elements
- Let $ref_TEMPLATE point to array of (10,11,12,13,14) elements
- Let $ref_HTML point to array of ("checked","")
- Let $dbh is empty or has undef value

After parsing of follow inline template with our $html_source:
<MENUSELECT:$html_source:"SQL query":$ref_DB:$ref_TEMPLATE:$ref_HTML:$dbh:>
we will get follow result:

How old are you? <input type="radio" name="years" value="1" >1-14
<input type="radio" name="years" value="2" >15-20
<input type="radio" name="years" value="3" checked>21-30

<input type="radio" name="years" value="4" >31-50
<input type="radio" name="years" value="5" >51 or older




 INCLUDE a external file in WebTools perl/html files

If you dream ever to have "function" that could include html or perl code in your WebTools script, now you can stop dreaming and have a look at this easy to use feature!
Inlude syntax:

  <!--©INCLUDE©file_to_be_included.ext©-->

and alternative syntaxes:

  <!--%INCLUDE%file.ext%-->

OR

  %%%INCLUDE%file.ext%%%


This tag you can place wherever you want (no matter whether you are in perl code (<?perl ?>) or you are in HTML). However if you want to include Perl code in your HTML, your file should have "<?perl","?>" pair between every piece of Perl code! Just remember: This tag include file in place of INCLUDE tag, without care what exacly you put in and without care of file location (you can also include /etc/passwd !) Please remember that!


Time for example:
-------------------
At the end of Page 2 you can find complex example of INLINE/INPERL templates. Also example with common templates you can find at the end of Page 1. Don't missed!

At last I want to share with all of you that I'm realy happy to see you reading this "help", so ENJOY WebTools and I hope to see you again at www.proscriptum.com

Author: Julian Lishev (julian@proscriptum.com)