TBS Plus! Manual

Important! This plugin does not make TBS easier to learn. It can simplify your template, or it can ruin them.
Usage of this extension will slow down merging; if complicated processing is needed, custom function / method or JavaScript may serve you better.

Upgrading from 1.0

Backup system and template.
Replace old plugin file / all-in-one file with new version.
Change plus parameters to new syntax, or add following PHP command before plugin installation:
define('TBS_PLUS_NON_OPE', true);
Test new system.

New syntax

The operation syntax let TinyButStrong parse fields faster, and reduces the chance of conflict with future versions.

Operations
Changing to new syntax is as simple as adding 'ope' before parameters, e.g.
From: [field; inv; abs]
To: [field; ope=inv,abs]

Simplified Magnets
Magnets have been simplified since version 1.03, e.g.
From: [field; zeromagnet; reversemanget; magnet=tag]
To: [field; ope=!zeromagnet=tag]

Multiple operations
Since comma is operation separator, operation parameter separator has been changed to colon for pair of numbers and pipe for string:
[field; ope=substring=1:2]
[field; ope=zebra=odd|even]
Most mathematical operations, however, can be repeated using comma:
[field; ope=+=1,2,3]

Backward compatibility
However, this also means individual operation parameter cannot be protected by quote.
If this functionality is required, defining 'TBS_PLUS_NON_OPE' to true will enable operations to be used without ope.
This does not complete restore the old syntax, for example zebra will use pipe as separator not comma, but ope is not necessary.

Requirements

Include the file "tbs_plugin_plus.php".
Alternatively, replace "tbs_class.php" with "doc/tbs_with_plugin.php", which contains TBS with Plus, Aggregate, and all standard bundle plugins in a compact form.
This plug-in requires TBS version 3.1 or higher.

Installation

Automatic on creation of the TBS variable when included before it.
If the plug-in file is included after creation of TBS object, install with following command:
$TBS->PlugIn(TBS_INSTALL, TBS_PLUS);

Commands

Output compression
$TBS->PlugIn(TBS_PLUS, TBS_COMPRESS_OUTPUT [, true|false]);
This will enable/cancel calling ob_gzhandler before show, if it is supported by server and by client and if it is not already enabled.
Trim template source on output
$TBS->PlugIn(TBS_PLUS, TBS_TRIM_OUTPUT [, true|false]);
This will enable/cancel trimming of template source before show. See below.
Trim template source immediately
$TBS->PlugIn(TBS_PLUS, TBS_TRIM_HTML [, Options]);
This will removes junks from template source to make it smaller, either immediately or before show (if TBS_TRIM_OUTPUT is defined).
Regular expression is used abusively, so unless the output is cached or sent through a slow/unreliable network the performance trade off may not worth it.

PHP 4 warning: TBS object must be assigned by reference for this command to work, i.e.
// $TBS = new clsTinyButStrong ; // As suggested in official TBS manual
$TBS = & new clsTinyButStrong() ;

This is not necessary in newer PHP version, which will trigger E_STRICT warnings if you do this.

<pre>, <script>, <style>, and rest of the stuffs (assumed to be normal html/xml) are treated differently.
The larger and more sections the source have, the longer it will take to trim.

This command cannot trim linked style, script, or image, which easily outgrown html content.
Thus, apart from "obfuscation", this is mostly a feel-good, everything-else-are-done feature.

Options
This command accepts any combination of the following options:
- TBS_TRIM_KEEP_LINE
  Preserve non-redundant line-breaks.
  By default most line-breaks will be removed. This may cause troubles for loose JavaScripts. Keeping line-breaks will solve most of them.
  Tidy up the scripts to improve their chance at surviving.
  
  Alternatively, preserve line-breaks for easier script debug in IE. All popular alternatives have usable JavaScript console / debugger.
  For HTML debug just use web developer toolbars / debuggers / features that show DOM tree and forget indents and line-breaks.
- TBS_TRIM_KEEP_COMMENT
  Preserve comments.
  The parser will try to detect and preserve conditional comments and wrapper comments, but sometimes false positives or copyright declarations need to be kept.
  This is a nothing-or-all switch, either all xml, script, and style comments are allowed or all will be removed.
- TBS_TRIM_EXTREME
  Aggressively remove spaces.
  This will removes commonly redundant white spaces, e.g. space between tags or commands, with an even higher chance to break the result.
  Use only if you need to feel really good.

Operations

It is possible to execute field operations from php side by calling the Operation static method, if an instant of the plugin is acquired, either by creation:
$Plus = new clsTbsPlugInPlus();
Or get from TinyButStrong:
$Plus = $TBS->_PlugIns['clsTbsPlugInPlus'];

Syntax:

mixed $Plus->Operation(mixed Value, string Operation [, string Parameter] );

Argument

Description

Value

"value to merge" in operations

Operation

Operation to perform. Must be a single operation not 'abs,sqrt,floor'.

(Optional) Parameter

Parameter of operation, in the same string form as in template.

(Return value)

Resulting "value to merge" after operation.

Example:
// Returns random story background
$Plus->Operation('background/story_*.jpg', 'randomfile');

It is possible to execute multiple operations by passing in an array of Operation and Parameter.

Example:
// Equals to [123; ope= abs, +=456, -=789]
$Plus->Operation(123, array('abs','+','-'), array(null,456,789));

Syntax

Operation syntax
The same with TinyButStrong operation, except that parameter is assigned by equal sign:

[nav.page; ope= -=1, *=[config.pagesize], negativemagnet=td ]
[onshow; ope= val=images/[product.image].jpg, filemagnet=tr ]

This is the default plugin syntax since 1.1. Operations are case sensitive.
Operation syntax can be disabled by defining TBS_PLUS_NO_OPE to true before plugin installation.

Extended field eter syntax
This is syntax of version 1.0, and now must be enabled by defining TBS_PLUS_NON_OPE to true before plugin installation
This syntax is easier to read and use, but make everything merge slower even when not used.

Usage: just use the operations as new field parameter, e.g.

[nav.page; -=1; *=[config.pagesize]; negativemagnet=td ]
[onshow; val=images/[product.image].jpg; filemagnet=tr ]

In 1.0, comma is the only parameter separator instead of pipe and colon.
For backward compatibility, field parameter is not case sensitive, and deprecated alias can be used. The alias are:
add, dec, multi, div, mod, power, neg, prepostfix, sizeof, reversemagnet, nonzeromagnet, nonemptymagnet, unequalmagnet, not, and 2space.

Mathematical operations

These operations work with numbers, and have undefined result when used on or with non-numbers. Some operations (+,-,*,/,etc.) can be chained in form of ope=+=1,2,3

Operation

Parameter(s)

Description

(None)

Negation.
Example: [2; ope=-] = -(2) = -2

Value to add

Addition. Same as standard operation 'add'.
Preserved for consistency and operation chaining.

Value to subtract

Subtraction.

Value to multiply

Multiplication. Same as standard operation 'mul'.

Divisor

Division. Same as standard operation 'div'. Division-by-zero returns NAN (0.0).

Divisor

Modulo. Same as standard operation 'mod'.

inv

Dividend

Invert division. Division-by-zero returns NAN (0.0)
Example: [2; ope= inv=8] = 8/2 = 4

Power

Power to. Accept negative power. NAN if zero.
Example: [2; ope= ^=8] = 2^8 = 256

sqrt

Root to find,
Default to 2

Squareroot / n^th root. If value is negative, returns complex number as string.
Example: [4; ope= sqrt] = 2
Example: [64; ope= sqrt=4] = 3

abs

(None)

Absolute value.
Example: [-2; ope= abs] = abs(-2) = 2

floor

(None)

Floor function (nearest integer to zero)

round

(None)

Round function (nearest integer)

(None)

Convert fraction to percent.
Example: [0.5; ope= %] = 0.5 * 100% = 50%

(None)

Convert percent to fraction.
Example: [50; ope= .%] = 50% / 100% = 0.5

(None)

Reverse percent.
Example: [0.8; ope= -%] = 100% - 80% = 20% = 0.2

Fraction / percent
to subtract

Subtract percent.
Example: [5; ope= -%=0.2] = 5 * (1 - 20%) = 5 * 0.8 = 4

Fraction / percent
to add

Add percent.
Example: [5; ope= +%=0.2] = 5 * (1 + 20%) = 5 * 1.2 = 6

min

Minimum of value

If value to merge is smaller then parameter, use parameter instead

max

Maximum of value

If value to merge is larger then parameter, use parameter instead
This differs from the 'max' standard operation in both syntax and functionality

range

Min:Max

If value to merge is outside range, fit it within given range.
Parameter order can be reversed.

random

(None)
Upper Limit
Limits (n:m)

Random number out of 1..value
Random number out of 1..parameter or value..parameter
Random number within boundary, inclusive
Example: [onload; ope= random=4:6] = 4, 5 or 6
Uses mt_rand() without seeding.

String operations

These operations works with strings, and have undefined result when used on or with non-string.

Operation

Parameter(s)

Description

lowercase

(None)

To lowercase

uppercase

(None)

To uppercase

titlecase

(None)

To titlecase. All words will have first letter uppercased, as ucwords().

prefix

Prefix

Add given prefix to value to merge

postfix

Postfix

Add given postfix to value to merge

prepost

Quote
Prefix|Postfix

Add given quote before and after value to merge
Add given prefix and postfix to value

plural

Select single and plural, and optionally nullar and dual:
If more then two, use Plural, default to 's'.
If two, use Dual, default to be same as Plural.
If one, use Single, default to empty.
If zero, use Nullar, default to be same as Plural, unless TBS_PLUS_SINGULAR_ZERO is defined and true, in which case Singlar will be used.
Example: The search found [count] [count; ope= plural=corpus|corpora].
Example: You got [mail.new] mail[mail.new; ope= plural]

substr

Start
Start:Length

Get part of value to merge
Example: [history; ope= substr=2] = story
Example: [enjoyment; ope= substr=2:3] = joy

replace

String to remove
Search|Replace

Remove all occurrence of parameter from value to merge
Replace all occurrence of Search with Replace from value

repeat

Times to repeat

Repeat value to merge by given number of times.
Example: [bd; ope= repeat=3] = bdbdbd

repeatstr

String to repeat

Repeat parameter by (value to merge) times.
Example: [3; ope= repeatstr=bd] = bdbdbd

size

(None)

Get length of value to merge.
Also works with array.

Magnet operations

Most of these operations can be used to replace TinyButStrong magnets.

Operation

Parameter(s)

Description

!magnet

(Optional) Manget

If value to merge is not empty, make it empty string and apply magnet, otherwise make it a space.

zeromagnet
!zeromagnet

(Optional) Magnet

If value to merge is (not) zero, make it empty string and apply magnet.

emptymagnet
!emptymagnet

(Optional) Magnet

If value is (not) empty, make it empty string and apply magnet.

boolmagnet
!boolmagnet

(Optional) Magnet

If value is (not) false, make it empty string and apply magnet.

equalmagnet
!equalmagnet

Value to compare

If value to merge (not) equals value to compare, make it empty string and apply magnet.
Example: [field; ope= equalmagnet=50; magnet=tr]

negativemagnet
!negativemagnet

(Optional) Magnet

If value to merge is numeric and (not) negative, make it empty string and apply magnet.

positivemagnet
!positivemagnet

(Optional) Magnet

If value to merge is numeric and (not) positive, make it empty string and apply magnet.

inarraymagnet
!inarraymagnet

Value to find

If value to merge (an array) (not) contains value to find, make it empty string and apply magnet.
Example: [field; ope= inarraymagnet=2; magnet=tr]

filemagnet
!filemagnet

(Optional) Magnet

If value to merge as filename (not) represents an existing file / folder, make it empty string and apply magnet.

Array operations

Operation

Parameter(s)

Description

explode

(Optional) Separator
Default to comma

Explode value to merge into array.

implode

(Optional) Glue
Default to comma

Stitch / implode value to merge into single string.

size

(None)

Size of value to merge. Also works with string.

Conversion operations

These operations turns value to merge into something else, sometimes with conditions.
Data would not be changed if condition is not meet.
See PHP's Boolean casting for more details.

Operation

Parameter(s)

Description / Result

htmlchecked

(None)

If value to merge is true, set value to merge to 'checked="checked"', otherwise to blank.

(None)

True if data is not true, false otherwise

(None)

A space if data is not blank

2bool

(None)

False if data is 0, '', null, 'n', 'no', 'false', or 'f',
True otherwise. Case insensitive.

between

Value1,Value2

True if value to merge is inclusively between the two (numeric) values, false otherwise

empty2zero

(None)

0 if data is empty

empty2blank

(None)

Blank if data is empty

empty2space

(None)

A space if data is empty

missingfile

Replacement

If value to merge as filename does not represent an existing file / folder, replace it with Replacement.

Other operations

Operation

Parameter(s)

Description

val

Value to set

Set value to merge

func

Function name

Assign function result to value to merge, the function should accept one parameter which is original value to merge.

randomfile

(None)
File pattern

Randomly pick from files matching given pattern, from parameter or value to match.
Example: [onshow; ope= randomfile=background/story_*.jpg ]

zebra

Values to rotate

Everytime the field is merged, rotate to next parameter value.
Zebra field with same field name and parameters share same counter.
Example: [row; block=_; ope= zebra=one|two|three ]

TBS Plus! Manual Version 1.1.0

TBS Plus! Manual
Version 1.1.0