Skip to content

Commit

Permalink
TBS 3.13.0
Browse files Browse the repository at this point in the history
  • Loading branch information
Skrol29 committed Feb 7, 2022
1 parent 6079f2e commit 9dc63e5
Show file tree
Hide file tree
Showing 3 changed files with 169 additions and 24 deletions.
8 changes: 6 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,15 @@ All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)

## [3.12.3] - 2021-12-03
## [3.13.0] - 2022-02-07

### Enhancements

- PHP 8.1 compatibility
- Compatibility with PHP 8.1

### Added

- New methods SetVarRefItem() and GetVarRefItem() : uniformize and ensure compatibility to set a VarRef items.

## [3.12.2] - 2020-11-03

Expand Down
66 changes: 63 additions & 3 deletions tbs_class.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
*
* TinyButStrong - Template Engine for Pro and Beginners
*
* @version 3.12.3-beta-1 for PHP 5, 7, 8
* @date 2021-12-03
* @version 3.13.0 for PHP 5, 7, 8
* @date 2022-02-07
* @link http://www.tinybutstrong.com Web site
* @author http://www.tinybutstrong.com/onlyyou.html
* @license http://opensource.org/licenses/LGPL-3.0 LGPL-3.0
Expand Down Expand Up @@ -655,7 +655,7 @@ class clsTinyButStrong {
public $ExtendedMethods = array();
public $ErrCount = 0;
// Undocumented (can change at any version)
public $Version = '3.12.3-beta-1';
public $Version = '3.13.0';
public $Charset = '';
public $TurboBlock = true;
public $VarPrefix = '';
Expand Down Expand Up @@ -822,6 +822,66 @@ public function ResetVarRef($ToGlobal) {

}

/**
* Get an item value from VarRef.
* Ensure the compatibility with PHP 8.1 if VarRef is set to Global.
*
* @param string $key The item key.
* @param mixed $default The default value.
*
* @return mixed
*/
public function GetVarRefItem($key, $default) {

if (is_null($this->VarRef)) {

if (array_key_exists($key, $GLOBALS)) {
return $GLOBALS[$key];
} else {
return $default;
}

} else {

if (array_key_exists($key, $this->VarRef)) {
return $this->VarRef[$key];
} else {
return $default;
}

}

}

/**
* Set an item value to VarRef.
* Ensure the compatibility with PHP 8.1 if VarRef is set to Global.
*
* @param string $key The item key.
* @param mixed $value The item value. Use NULL in order to delete the item.
*/
public function SetVarRefItem($key, $value) {

if (is_null($this->VarRef)) {

if (is_null($value)) {
unset($GLOBALS[$key]);
} else {
$GLOBALS[$key] = $value;
}

} else {

if (is_null($value)) {
unset($this->VarRef[$key]);
} else {
$this->VarRef[$key] = $value;
}

}

}

// Public methods
public function LoadTemplate($File,$Charset='') {
if ($File==='') {
Expand Down
119 changes: 100 additions & 19 deletions tbs_us_manual.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,12 +169,15 @@
border: 1px dotted #6699CC;
}
.note {
background-color: #D9FFD9;
background-color: #D9FFD9; /* green */
border: thin solid #00EC9F;
padding: 2px;
margin-top: 3px;
margin-left: 20px;
}
.warning {
background-color: #f4dfdf; /* light red */
}
-->
</style>
</head>
Expand All @@ -188,13 +191,13 @@
</tr>
<tr>
<td>Date:</td>
<td>2021-08-27</td>
<td>2022-02-07</td>
</tr>
</table>
</div>
<div style="margin:auto; width:500px; text-align:center;">
<h1>TinyButStrong Documentation</h1>
<div class="txt-tiny">version 3.12</div>
<div class="txt-tiny">version 3.13</div>
<div style="margin-top:10px;">Template Engine for Pro and Beginners<br>
PHP 8<br>
PHP 7<br>
Expand Down Expand Up @@ -270,7 +273,19 @@ <h2>Table of Contents:</h2>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#php_getoption"><span class="txt-small">method</span> GetOption()</a></td>
<td>get TBS options</td>
<td>get TBS options</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#php_resetvarref"><span class="txt-small">method</span> ResetVarRef()</a></td>
<td>reset the VarRef property</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#php_getvarrefitem"><span class="txt-small">method</span> GetVarRefItem()</a></td>
<td>get an item in the VarRef property</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#php_setvarrefitem"><span class="txt-small">method</span> SetVarRefItem()</a></td>
<td>set an item in the VarRef property</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#php_replacefields"><span class="txt-small">method</span> ReplaceFields()</a></td>
Expand Down Expand Up @@ -1322,6 +1337,45 @@ <h3><a id="php_getoption"></a>Method GetOption():</h3>
<p class="versioning">Versioning: methods GetOption() is supported since TBS version 3.8.0. </p>
</div>

<h3><a id="php_resetvarref"></a>Method ResetVarRef():</h3>
<div class="norm">
<p>Reset the <a href="#php_varref" class="opt-name">VarRef</a> property.</p>
<p>By default, VarRef refers to the <a href="https://www.php.net/manual/en/reserved.variables.globals.php">PHP global variable $GLOBALS</a>.</p>
<p> Syntax: <span class="txt-code"><span class="opt-type">mixed</span> <span class="opt-name">$TBS</span>-&gt;ResetVarRef(<span class="opt-type"><span class="opt-value">boolean</span></span> <span class="opt-name">$to_globals</span>)</span></p>
<table border="0" cellpadding="5" cellspacing="0">
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td align="left" valign="top" class="opt-name"><span class="txt-code">$to_globals</span></td>
<td align="left" valign="top">Indicates if the property VarRef refers to $GLOBALS or is a new empty array.
<br>- if <span class="opt-name">$to_globals</span> is <span class="txt-code"><span class="opt-type">true</span></span> then VarRef refers to $GLOBALS.
<br>- if <span class="opt-name">$to_globals</span> is <span class="txt-code"><span class="opt-type">false</span></span> then VarRef is a new empty array.</td>
</tr>
</table>
</div>

<h3><a id="php_getvarrefitem"></a>Method GetVarRefItem():</h3>
<div class="norm">
<p>Get an item value in the <a href="#php_varref" class="opt-name">VarRef</a> property.</p>
<p>This function uniformizes the way to get a <a href="#php_varref" class="opt-name">VarRef</a> item, whether VarRef refers to <a href="https://www.php.net/manual/en/reserved.variables.globals.php">$GLOBALS</a> or not.</p>
<p> Syntax: <span class="txt-code"><span class="opt-type">mixed</span> <span class="opt-name">$TBS</span>-&gt;GetVarRefItem(<span class="opt-type"><span class="opt-value">string</span></span> <span class="opt-name">$key</span>, <span class="opt-type"><span class="opt-value">mixed</span></span> <span class="opt-name">$default</span> = <span class="opt-value">null</span>)</span></p>
<p>If VarRef if a dedicated array, then this function is the same as doing <span class="txt-code">$TBS->VarRef[$key] ?? $default;</span></p>
<p class="versioning">Versioning: methods GetVarRefItem() is supported since TBS version 3.13.0.</p>
</div>

<h3><a id="php_setvarrefitem"></a>Method SetVarRefItem():</h3>
<div class="norm">
<p>Set an item value in the <a href="#php_varref" class="opt-name">VarRef</a> property.</p>
<p>This function uniformizes the way to set a <a href="#php_varref" class="opt-name">VarRef</a> item, whether VarRef refers to <a href="https://www.php.net/manual/en/reserved.variables.globals.php">$GLOBALS</a> or not.</p>
<p> Syntax: <span class="txt-code"><span class="opt-type">mixed</span> <span class="opt-name">$TBS</span>-&gt;SetVarRefItem(<span class="opt-type"><span class="opt-value">string</span></span> <span class="opt-name">$key</span>, <span class="opt-type"><span class="opt-value">mixed</span></span> <span class="opt-name">$value</span>)</span></p>
<p>If VarRef if a dedicated array, then this function is the same as doing <span class="txt-code">$TBS->VarRef[$key] = $value;</span></p>
<p class="versioning">Versioning: methods SetVarRefItem() is supported since TBS version 3.13.0.</p>
</div>



<h3><a id="php_replacefields"></a>Method ReplaceFields():</h3>
<div class="norm">
<p>Replace a set of simple TBS fields in the template with new definitions prepared at the PHP side. Note than this function does not merges any field ; it only replaces the definition of fields.</p>
Expand Down Expand Up @@ -1388,7 +1442,7 @@ <h3><a id="php_getattvalue"></a>Method GetAttValue():</h3>
<li><span class="txt-code opt-value">null</span> if the TBS field is not found or if it has no parameter <a href="#html_field_prm_all" class="opt-name">att</a>,</li>
<li><span class="txt-code opt-value">false</span> if the target XML/HTML element is not found or if the asked attribute is not found.</li>
</ul>
<p class="versioning">Versioning: methods GetAttValue() is supported since TBS version 3.11.0. </p>
<p class="versioning">Versioning: methods GetAttValue() is supported since TBS version 3.11.0. </p>
</div>

<h3><a id="php_plugin"></a>Method PlugIn():</h3>
Expand Down Expand Up @@ -1416,29 +1470,56 @@ <h4>Installing a plug-in: </h4>
</ul>
<p class="versioning">Versioning: the method PlugIn() is supported since TBS version 3.0. </p>
</div>

<h3><a name="php_varref"></a>Property VarRef:</h3>
<div class="norm">
<p>This property enables you to set the scope of variables availables for <a href="#html_field_auto">automatic fields</a> ([onload], [onshow] and [var]).</p>
<p>By default, VarRef is a <a href="http://www.php.net/manual/en/language.references.whatare.php">reference</a> to the <span class="opt-name">$GLOBALS</span> PHP variable, which means all global PHP variables are available for automatic field.</p>
<p>Property VarRef is the array of the items that will be merged with <a href="#html_field_auto">automatic fields</a> ([onload], [onshow] and [var]).</p>
<p> Syntax: <span class="txt-code"><span class="opt-type">array</span> <span class="opt-name">$TBS</span>-&gt;VarRef</span></p>
<p>
By default <span class="txt-code">$TBS->VarRef</span> refers
to the special <a class="opt-name" href="https://www.php.net/manual/en/reserved.variables.globals.php">$GLOBALS</a> variable of PHP.
This is for compatibility reasons, but it is recommended to use another array instead (see below).
</p>
<p>You can set <span class="txt-code">$TBS->VarRef</span> to be a new empty array using the method <span class="txt-code">$TBS->ResetVarRef(false);</span></p>
<p>You can also set <span class="txt-code">$TBS->VarRef</span> to be a reference to your own array : <span class="txt-code">$TBS->VarRef =& $my_array;</span></p>

<div class="decal warning">
<strong>Warning</strong>
<br>As of TBS version 3.13.0, is not possible to access directly to the VarRef items when the property refers to $GLOBALS. This is because of the PHP restriction on $GLOBALS that occurs with PHP 8.1.
<br>In order to ensure the compatibility to any situation, you can manage the items of VarRef using the methods <a href="#php_setvarrefitem" class="txt-code">$TBS->SetVarRefItem()</a> and <a href="#php_setvarrefitem" class="txt-code">$TBS->GetVarRefItem()</a>.
</div>

<p>Notes:</p>
<ul>
<li> Method<span class="txt-code"> ResetVarRef(<span class="opt-name">$ToGlobal</span>)</span> is a shorthand for reseting property VarRef to <span class="opt-name">$GLOBALS</span> or to an empty array.</li>
<li> Method <a href="#php_resetvarref" class="txt-code">ResetVarRef(<span class="opt-name">$ToGlobal</span>)</a> is a shorthand for resetting property VarRef to <a class="opt-name" href="https://www.php.net/manual/en/reserved.variables.globals.php">$GLOBALS</a> or to an empty array.</li>
<li> If property VarRef is changed by a sub-template, the change is available only for the sub-template.</li>
</ul>
<p>Example for setting VarRef to global variables :</p>
<pre class="decal txt-code"><span class="opt-name">$TBS</span>-&gt;VarRef = &amp;<span class="opt-name">$GLOBALS</span>;

<p>Example when VarRef is a custom array (recommended): </p>
<pre class="decal txt-code"><span class="opt-name">$TBS</span>-&gt;ResetVarRef(false); <span class="opt-html">// VarRef is now a new empty array</span>
<span class="opt-name">$TBS</span>-&gt;VarRef['my_item'] = "my value";
<span class="opt-name">$TBS</span>-&gt;SetVarRefItem('my_item', "my value"); <span class="opt-html">// same as above but ensure the compatibility with any situation</span></pre>

which is the same as:
<p>Example when VarRef is attached to $GLOBALS (by default): </p>
<pre class="decal txt-code"><s><span class="opt-name">$TBS</span>-&gt;VarRef['my_item'] = "my value";</s> <span class="opt-html">// this will raise an error as of TBS version 3.13.0</span>
<span class="opt-name">$GLOBALS</span>['my_item'] = "my value";
<span class="opt-name">$TBS</span>-&gt;SetVarRefItem('my_item', "my value"); <span class="opt-html">// same as above but ensure the compatibility with any situation</span></pre>

<div class="versioning">
<p>Versioning:</p>
<ul class="list-mini">
<li>Property VarRef is supported since TBS version 3.8. Before this version, the scope of automatic fields was PHP global variables.</li>
<li>
Since TBS version 3.13.0, you cannot directly use the property <span class="txt-code">$TBS->VarRef</span> when it refers to $GLOBAL. This is because of a PHP 8.1 restriction. Use SetVarRefItem() and GetVarRefItem() instead.
<br>Before TBS version 3.13.0, property <span class="txt-code">$TBS->VarRef</span> used to be by default a PHP reference the $GLOBAL variable.
</li>
</div>

</div>


<h3><a id="php_assigned"></a>Property Assigned:</h3>

<span class="opt-name">$TBS</span>-&gt;ResetVarRef(true)<span class="opt-name"></span>;
</pre>
<p>Example for setting VarRef to a custome scope of variables: </p>
<pre class="decal txt-code"><span class="opt-name">$TBS</span>-&gt;ResetVarRef(false); <span class="opt-html">// VarRef is now a new empty array</span>
<span class="opt-name">$TBS</span>-&gt;VarRef['x'] = 'This is value X';</pre>
<p class="versioning">Versioning: property VarRef is supported since TBS version 3.8. Before this version, the scope of automatic fields was PHP global variables.</p>
</div>
<h3><a id="php_assigned"></a>Property Assigned:</h3>
<div class="norm">
<p>Enables you to define information for a subsequent merging which can be automatic or manual. </p>
<p> Syntax: <span class="txt-code"><span class="opt-type">array</span> <span class="opt-name">$TBS</span>-&gt;Assigned</span></p>
Expand Down

0 comments on commit 9dc63e5

Please sign in to comment.