为何使用它? 示例 下载 手册 支持 论坛 推荐 秀出你的站点 http://phpv.net/TBS_Manual.htm#html_automatic 网站: http://www.tinybutstrong.com/index.php?lang=fr 作者: [email protected], Pirjo Date: 2005-08-31 *.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.* TinyButStrong version 2.05 *.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.* 高亮显示新版本功能 2.02 2.05 应用于PHP4.0.6或更高版本的专业和易用模板引擎 译者：esayr & !oEL | 本页最后更新：2006-4-30 允许自由使用、分发、转载，但必须保留译者署名；详见：声明。 目录: 主题 描述 • 简介 基本原理 安装 小示例 • PHP 方面 • 开始 方法 LoadTemplate() 从文件加载模板内容 方法 MergeBlock() 将部分数据源合并入模板 方法 Show() 自动处理和显示结果 • 高级 方法 CacheAction() 为合并结果激活缓存系统 方法 GetBlockSource() 返回定义块的源数据 方法 MergeField() 把一个特定的字段和一个值合并(用一个值替换掉原模板里的值,后译) 方法 MergeNavigationBar() 合并入导航栏 方法MergeSpecial() 合并自动字段, PHP 变量, 和其它... 特性 Render 改变合并的结尾选项 特性 Source 返回这个结果的当然内容 特性 TplVars 返回模板变量 添加一个数据源类型 生成一个 TBS 认可的新数据库类型 面向对象编程 (OOP) 使 TBS 友好支持 OOP • HTML 方面 • TBS 字段 定义和语法 参数 Var 字段 特定 Var 字段 • TBS 块 定义和语法 参数 闭合的块 连续显示 (应用于栏) 动态查询 / 子块 显示导航条(分页?) • 混合 自动的字段和块 子模板 有条件的显示汇总 • 概要 TBS 字段的参数 TBS 块的参数 分页导航的字段和参数 特殊的字段名和块名 简介: TinyButStrong (TBS) 是一个PHP类,它能让你开发系统时能干净分离PHP脚本和HTML文件. 使用 TBS, HTML 页面是由模板合并数据后动态生成的. 这被称为模板引擎. 这个TBS的名字来源于本工具目前虽然只有8个函数,但却非常强大. 它允许您合并PHP变量,或者 MySQL, PostgreSQL, SQLite到HTML页面里. TBS 设计成你可以轻松的使用任何可视化 HTML 编辑软件 (像 Dreamweaver 和 FrontPage)开发 HTML 模板页. 你习惯于使用文本方式编辑HTML文件?没问题,TBS 同样能够让你创建 JavaScript 动态脚本. 正如它的名字一样, TBS 易用, 强大且快速. 它完全是 °~° 免费的°~°. 基本原理: 在HTML方面: 你设计页面时不需要包含任何PHP脚本和流程. 在页面里你只要将TBS 标签放在你想显示动态数据的地方. 这个页面称为 ‘模板‘. 有两种类型的标签: ‘字段‘ 显示动态的数据项目, ‘块‘ 则定义一个区域, 主要为了从数据源显示记录. 在PHP方面: 使用 TBS 的实例对象管理你的HTML模板. 在文档末, TBS 显示合并的结果. 安装: 1. 复制文件 tbs_class.php 到你网站的目录文件夹. 2. 在PHP程序的开头,加入下面这一行: include_once(‘tbs_class.php‘); $TBS = new clsTinyButStrong ; 备注: 如果 TBS 文件 tbs_class.php 在不同的目录, 你需要指定它的路径. 说明和技术细节: TinyButStrong 是PHP写的一个库, 你可以将它做为一个组件引入自己的 PHP 程序里. 技术用语来说, TinyButStrong 是一个 PHP ‘类‘ ; 类名就叫 clsTinyButStrong. 在你的PHP文件头部添加的变量 $TBS 让你能够把模板合并到你的 PHP 程序中. 技术用语来说, 变量 $TBS 是 clsTinyButStrong 类的实例. 小示例: 例 1: Html 模板 Php 程序 结果 <html> <body> [var.message] </body> </html> <? include_once(‘tbs_class.php‘); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate(‘template.htm‘) ; $message = ‘Hello‘ ; $TBS->Show() ; ?> <html> <body> Hello </body> </html> 示例 2: Html 模板 Php 程序 结果 <table> <tr><td>[blk.val;block=tr]</td></tr> </table> <? include_once(‘tbs_class.php‘); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate(‘template.htm‘) ; $list = array(‘X‘,‘Y‘,‘Z‘) ; $TBS->MergeBlock(‘blk‘,$list) ; $TBS->Show() ; ?> <table> <tr><td>X</td></tr> <tr><td>Y</td></tr> <tr><td>Z</td></tr> </table> PHP 方面: 模板和 PHP 程序的合并需要使用一个对象变量即 clsTinyButStrong 类. 声明示例: $TBS = new clsTinyButStrong ; 这个对象允许你加载模板, 以便合并入数据, 然后显示结果. PHP代码示例: include_once(‘tbs_class.php‘); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate(‘template.htm‘) ; $TBS->MergeBlock(‘ctry‘,‘mysql‘,‘SELECT * FROM t_country‘) ; $TBS->Show() ; 下面列出 TinyButStrong 对象的属性和方法: 方法 LoadTemplate(): 加载一个模板以便替换和处理. 文件全部内容将被保存于TBS 对象源中. 语法: $TBS->LoadTemplate(string File{, string HtmlCharSet}) 参数 描述 File 使用本地或绝对路径加载文件. HtmlCharSet 可选. 指定Indicates the character encoding (charset) to use for Html conversion of the data when they will be merged. It should be the same as the charset of the template. The default value is ‘‘ (empty string) which is equivalent to ‘ISO-8859-1‘ (Latin 1). 假如模板使用一个特殊的字符集,那么你需要给这个字符集指出html值. 在 Html 页面中, 字符集往往放在文件的开头处, 属于<Meta>标签的‘content‘ 部分. TBS 支持PHP 函数 htmlentities() 所支持的所有字符集. 例如: ‘BIG5‘ (繁体中文) 或‘EUCJP‘ (日文). 不转换Html: 假如你使用False 做为 HtmlCharSet 的参数, 当合并数据时将不进行转码. 使用函数: 假如你使用了尚未被 PHP 支持的字符集, 你可以指出自定义函数来完成Html 转换. 在这里, 参数 HtmlCharSet 使用语法 ‘=用户自定义函数名‘. 用户自定义函数必需包含一个字符串参数[像这样abc($string="");], 并能返回一个转换后的字串. 在当前模板末添加文件: 你可以使用‘+‘代替字符集将文件添加在当前模板文件后,字符集参数与第一个模板一样. 方法 MergeBlock(): 从一个数据源合并一个或几个 TBS 块 . 返回最后显示的记录数(从1开始计数[而不是0]). TinyButStrong 天生就支持的几个数据源类型: Php 数据: 一个数组, 字串, 数字. 数据库: MySQL ; PostgreSQL ; SQLite. 当然,你也可以自己添加数据源类型: ‘添加数据源类型‘. 要使用‘By Page‘模式, 参见下述. 语法: int $TBS->MergeBlock(string BlockName, mixed Source{, string Query}{, int PageSize, int PageNum}{, int RecCount}) 参数 描述 BlockName 指定合并时TBS 块 名. 一个数据源可以复制为几个块,只要使用逗号分隔块名. Source 指定合并时的数据源. 根据数据源类型,显示下表中可能出现的值. Query 可选. 指定返回合并记录的 SQL 声明.(原文:Indicates the SQL statement which returns the records to merge.) 根据数据源类型,显示下表中可能出现的值. PageSize 可选. 此参数仅在定义分页模式后才可用. 指定一页显示多少条记录. PageNum 可选. 此参数仅在定义分页模式后才可用. 指定显示哪一页. 第一页是 1. 如果指定为-1 将显示最后一页. RecCount 可选. 此参数仅在定义分页模式 后才可用. 他允许调整MergeBlock()方法返回的数字结果.(原文:It allows to adjust the calculation of the number of records returned by the MergeBlock() method.) RecCount 方法 MergeBlock() 的返回值 0 : 默认值. 此方法返回最后记录数显示在需要的页面上.(原文:The method returns the number of the last record displayed in the required page.) -1 : 此方法读取返回的所有记录一直到最后的总数,然而, 仅在被要求的页面上显示记录. >0 : 方法返回的RecCount 值. 然后, 假如RecCount这个值超过自定值,它将返回需要页面的最后记录数.(原文:it will return the number of the last record in the required page if it‘s higher than .) 使用此参数为了计算和保存记录总数. 例子: if (isset($_POST[‘nbr_rec‘])) { $nbr_rec = $_POST[‘nbr_rec‘] ; } else { $nbr_rec = -1 ; } $nbr_rec = $TBS->MergeBlock(‘blk1‘,$cnx_id,‘select * from t_country‘,$p_size,$p_num,$nbr_rec); 块与返回之间的连结: 方法MergeBlock() 在模板内搜索你指定的TBS块名,然后, 然后块将根据数据源内记录的次数反复显示. 为了显示一个数据记录,你需要使用一个 TBS 链接域. 要链接到一个TBS域,这个TBS域的名字应试是这样构成的: 块名.记录集键名(或者行名) 有点像这样 [block1.field1] . 另外,TBS 链接域必须在指定的块内. 示例: 块名是: block1 从查询返回行: field1,field2,field3 连接 TBS 字段: [block1.field1], [block1.field2], [block1.field3] 假如在模板内没有找到定义的块, MergeBlock() 方法将合并首个记录尽管所有连接字段在模板内可找到. 你同样可以定义更多高级的块. 想了解更多, 参见TBS Blocks章节. 从相同的数据中同时合并多个块: 你可以在 BlockName 参数中标示多个块以便同时合并他们,每个块间需要一个逗号分割. 这样一来, 查询(query)只被执行一次,返回块的记录将被缓冲. 示例 : $TBS->MergeBlock(‘block1,block2,block3‘,‘mysql‘,‘SELECT * FROM MyTable‘); 统计记录数: 要显示记录数, 你需要使用一个链接到virtual column ‘#‘ 的TBS域. 如果你把这个域放在块外, 它将显示记录总数. 示例: [block1.#] 如果数据源是一个PHP数组, virtual column ‘$‘ 将显示它的键值. 示例: [block1.$] 数据源类型与资源&请求参数对照表: 数据源类型 Source Query Text (*) 关键字 ‘text‘ A text Number (*) 关键字‘num‘ A number or a special array (see below) Clear (*) 关键字‘clear‘ - Conditional (*) 关键字‘cond‘ - PHP Array (*) 一个PHP数组 - 关键字‘array‘ A Php Array 关键字‘array‘ A string that represents an array contained or nested in a PHP global variable (see below) MySQL 一个 MySql 连接标识符或关键字 ‘mysql‘ An SQL statement 一个 MySql 结果标识符 - PostgreSQL 一个 PostgreSql 连接标识符 An SQL statement 一个 PostgreSql 结果标识符 - SQLite 一个 SQLite 连接标识符 An SQLite statement 一个 SQLite 结果标识符 - custom A keyword, an object or a resource identifier not mentioned in this table. See the chapter ‘adding a data source type‘. An SQL statement or something else. (*) 参见以下章节的解释. Php 数据源: Text 数据源参数必须设定为 ‘text‘. 整个块被文本 (必须为字串string) 替代为 Query 参数. 除了 ‘#‘ 返回 1或 0 (假如 Query 是一个空的字串string)其它链接域将不被处理. Number 数据源参数必须设定为‘num‘. 参数 Query 可以是一个数字或者数组. arg Query 返回记录集 Number: 数字必须大于等于0. 返回记录集由数列 ‘val‘ 从1至指定数字组成. Array: 这个数组须由 ‘min‘, ‘max‘ 和 ‘step‘组成. 返回记录集将由数列 ‘val‘ 从 ‘min‘到‘max‘的值组成. 示例: array(‘min‘->101,‘max‘->150) 将显示从101至150的50个块. Clear 数据源参数必须设定为‘clear‘. 所有块和部分都将删除,与合并一个空数组效果一样. Conditional 数据源参数必须设定为‘cond‘. 块将被视为 有条件的显示块 加载(onload) 和 显示(onshow). 这个块不与数组合并, 所有它不能出现任何 TBS 链接域. 每个块都需要一个参数 when 或 default. 参阅 有条件的显示块 了解更多细节. Array 数据源参数必须为一个PHP数组或设定为 ‘array‘. 假如你用关键词 ‘array‘, 那么 查询(Query) 参数必须是一个PHP数组或者一个代表数组的字串包含或者嵌套在一个全局变量里. 字串语法: ‘globvar[item1][item2]...‘ ‘globvar‘ 是一个全局变量 $globvar 的名字,且必须是一个数组. ‘item1‘ 和 ‘item2‘ 是$globvar 项的键值或者它的子项名. 示例: $TBS->MergeBlock(‘block1‘,‘array‘,‘days[mon]‘); 将把 ‘block1‘ 和 $day[‘mon‘] 数组合并. 你也可以不使用项名. 示例: $TBS->MergeBlock(‘block1‘,‘array‘,‘days‘); 使用字串代表数组有两个优势: -> 项可以直接从数组而不是复制的项中读取,这样可以提高性能. -> 你可以使用动态的查询. 显示当前记录的键值: 欠可以使用virtual column ‘$‘ 来显示当前记录的键值. 这在你使用 动态查询与子块(dynamic queries and sub-blocks) 时将派上大用场. 示例: [block1.$] 支持的数组结构: 数组的项可以有两种: 1.有关联键值的简单值 2.数组值本身就是与键值关联的简单值. 1: 示例: [‘key1‘]=>value1 [‘key2‘]=>value2 ... 返回的记录集由包含键值的数列 ‘key‘ 和一个包含值的数列 ‘val‘ 组成. 2: 示例: [0] => ([‘column1‘]=>value1-0 ; [‘column2‘]=>value2-0 ; ...) [1] => ([‘column1‘]=>value1-1 ; [‘column2‘]=>value2-1 ; ...) [2] => ([‘column1‘]=>value1-2 ; [‘column2‘]=>value2-2 ; ...) ... 返回的记录集由数列 ‘column1‘, ‘column2‘,... 与他们关联的值组成. 分页模式: 当你赋一个非零参数给 PageSize 时,分页模式将被激活. 数据的显示将被所指定的 PageNum 限制. 假如 PageNum 的值为 -1, 那么将显示最后一页. 重要备注: 尽管分页模式非常简单实用, 但它并末对读取大量数据记录作优化处理. 假如你使用它后感觉页面显示很慢或者你的数据库负载很大, 那么你可能需要考虑使用数据库系统自带的限制query数功能(假如有的话). 比如: 在 MySQL 里你可以使用 LIMIT 子句. 说明: 考虑到各种不同的 SQL 语法, TinyButStrong 无法修改一个可以返回定量记录集的查询(query). 例如, 它不能将一个 LIMIT 子句添加进一个 MySQL 查询(query). 这就是为什么 TinyButStrong 必须访问原始查询(query), 然后忽略之前的页面设置从头开始一个个地读取记录.尤其是在页数很多时显示速度将会非常慢, 当页面被选定,TinyButStrong 就会不顾记录集结尾地释放查询(query) 方法 Show(): 结束合并. Syntax: $TBS->Show({int Render}) Show 方法将执行以下操作: - 合并 Var 字段, - 合并 [onshow] 字段, - 显示结果(原文:can be cancelled by Render property), - 结束脚本 (可以使用Render特性取消). Render 特性允许调整 Show() 方法的行为. 参数Render 同样允许调整Show() 方法但仅能调用一次. 方法 CacheAction(): 调用TinyButStrong缓存系统的一个动作. 此缓存系统允许你手动或自动操作,将合并结果备份在一个被称为"缓存" 文件的临时文件. CacheAction() 依据调用动作的成功或失败返回 true 或 false. 语法: bool $TBS->CacheAction(string CacheId {, int Action/MaxAge}{, string Dir}) 参数 描述 CacheId 缓存文件的Unic id. 必需是一个字符, 它将被做为文件名使用. Action/MaxAge 让action执行的操作. 必需是 TinyButStrong‘s 定义的值. 参见下表了解更多可用指令的细节. 默认值为 3600 ,与之对应的是1小时内自动备份(译不准,原文:wich correspond to an automatic backup with a max age of 1 hour) Dir 可选. 指定缓存文件保存的路径. 默认为执行脚本的目录 即./ 管理缓存文件: 缓存系统使你可以创建,加载,更新或者删除以 CacheId 标识的缓存文件. 根据设定的缓存文件最大寿命，也可以让系统自动操作 缓存文件. 显示缓存: 假如你开始使用"显示缓存", 那么合并后的结果将在第一次使用Show() 方法时自动保存在缓存文件. 显示结果之后就记录这个步骤. 请注意 Show() 方法默认情况下会导致程序结束.假如想在"显示缓存"后继续一些操作, 那么你需要设置 Render 特性以避免程序在不应该的时候意外停止. 下面列出了 Action/MaxAge 参数可能用到的一些值, 它可以是 TinyButStrong 预定义的常数或者一个正整数. 动作 描述 x >=0 (正数) 最大寿命自动模式(Automatic Mode with max-age): - 假如缓存文件存在并创建时间少于 x 秒, 那么将加载文件并执行 Show() 方法. 假如设置了Render 特性,程序将在显示结果后结束, 否则 CacheAction() 返回 true. - 假如缓存文件不存在或者文件创建时间超过 x 秒以前, 那么 "显示缓存" 已开始 (上述). 该程序继续正常 CacheAction() 返回 false. TBS_CACHENOW 保存当前合并结果到与 CacheId 相对应的缓存文件. CacheAction() 返回 false. TBS_CACHELOAD 以 CacheId 加载对应的缓存文件. 假如缓存文件存在并加载成功 CacheAction() 返回 true , 否则返回 false. TBS_DELETE 删除 CacheId 相对应的缓存文件. 你可以删除一个目录下的所有缓存文件,你只要指定 CacheId 为 ‘*‘. CacheAction() 返回 false. TBS_CACHEONSHOW 开始从 CacheId 相对应的缓存文件 "显示缓存" CacheAction() 返回 false. TBS_CANCEL 取消 "显示缓存" 无论是什么 CacheId. CacheAction() 返回 false. TBS_CACHEGETAGE 返回缓存文件寿命秒数.文件不存在则返回 false. TBS_CACHEGETNAME 返回与 CacheId 相对应的缓存文件名. 即使文件不存在也返回. TBS_CACHEISONSHOW 假如 "显示缓存" 可用,返回 true , 否则, 返回 false. 方法 GetBlockSource(): 返回 TBS 块的数据源. 只返回定义块的第一部分, 除非 Sections 参数设定为 True. 如果没有找到块, 方法将返回 False. 语法: string $TBS->GetBlockSource(string BlockName {, boolean Sections}) 参数 描述 BlockName 搜索的块名. Sections 可选. 默认值为 False. 如果参数设置为 True 方法将返回一个包含指定块所有部分定义的数组. 第一个部分将被返回到数组里的 item [1]. 此方法能让你获得块的来源信息以便手动控制合并过程. 在此之后, 假如你想用文本替代块, 你可以用 MergeBlock() 方法里的 ‘text‘ 参数. 方法 MergeField(): 使用一个固定值或调用用户函数替换一个或多个TBS Fields. 每个有指定 BaseName 的 TBS fields 将被合并. 语法: $TBS->MergeField(string BaseName, mixed X {, boolean FunctionMode}) 参数 描述 BaseName TBS Fields的基础名. 比如 ‘account‘. X 需要显示的值或代表一个用户函数的字串. FunctionMode 指定显示值由一个用户函数给出. 默认值为 false. 假如参数设为 true, X 必须为用户函数名的字串. 此函数必须存在且拥有以下描述的语法. 与一个值合并: X 可以是数字, 字串, 数组或一个对象. 如果是数组或对象, TBS Fields 名必须有像Var Fields 这样的后缀. 示例: $TBS->MergeField(‘account‘,array(‘id‘=>55,‘name‘=>‘Bob‘)); 本例中, fields [account.id] 和 [account.name] 将被合并. 与用户函数合并: TBS 在模板里搜索每个field调用此函数. 此函数必须拥有以下的语法: function fct_user($Subname [, $PrmLst]) {...} 当函数被调用, 参数 $Subname 拥有一个 field‘s 名的前缀 (如: 一个 field 名 ‘ml.title‘, $Subname 将拥有值‘title‘). 还有可选参数$PrmLst 含有一个相关联的数组和 field‘s 参数. 此函数必须返回合并的值. 示例: $TBS->MergeField(‘ml‘,‘m_multilanguage‘,true); ... function m_multilanguage($Subname) { global $lang_id; $rs = mysql_query("SELECT text_$lang_id AS txt FROM t_language WHERE key=‘$Subname"); $rec = mysql_fetch_array($rs); return $rec[‘txt‘] ; } 在此例中, 一个像 [ml.title] 的 field 将和m_multilanguage(‘title‘)返回值合并. 方法 MergeNavigationBar(): 显示一个基于指定 TBS block 和 TBS fields的导航栏. 关于如何建立一个导航栏的细节, 请参阅 ‘显示一个导航栏(Display a navigation bar)‘. 语法: $TBS->MergeNavigationBar(string NavName, mix Options, int PageNum [, int RecCount, int PageSize]) 参数 描述 NavName 导航栏的名字. 注意: 你可以通过使用逗号分隔多个名字以同时合并多个导航栏. Options 可以让你参强制运行一此导航栏选项. 这些选项同样可以定义在模板的块参数中. 但假如你将这此选项也放在 MergeNavigationBar(),他们也将被强制运行. 此参数可为空 (‘‘, 0 或者 null), 也可是一个数字或数组. 假如是一个数字, 表示显示的页数. 假如是一个数组, 表示包含如下项: 键 值 ‘navsize‘ 导航栏显示的页数. (默认 = 10). ‘navpos‘ Position of the navigation bar compared to the active page number. 使用下列一个键值: - ‘step‘ (默认) to have the bar progressing by step. - ‘centred‘ to center the bar on the active page number. ‘navdel‘ 当只有一页或者没有页面显示时,需要删除的 TBS 块. 这个 TBS 块必须属于导航栏. 假如有多个页面显示,那么只有 TBS 定义的块被删除. ‘pagemin‘ 第一页 (默认 = 1).(设置什么值为第一页?--esayr注) PageNum 当前显示的页面数值. 第一页为1. 要表示最后一页可以使用-1. RecCount 可选. 默认值为 -1. 设置记录总数. 但当你不知道这个数字时,请将它设为-1. 此参数仅用来计算导航栏的最后一页的值. PageSize 可选. 默认值为1. 表示每页的记录数. 它要配合 RecCount 使用,来计算导航栏的最后一页的值. 示例: $TBS->MergeNavigationBar(‘nav‘,‘‘,$page,$rec_nbr,$page_size); 方法 MergeSpecial(): 替换指定类型的 blocks 和 fields.语法: $TBS->MergeSpecial(string Type) Type 参数必须是以下的其中一个: 值 描述 ‘var‘ 替换所有Var fields. ‘onload‘ 替换所有onload fields. ‘onshow‘ 替换所有onshow fields. 备注: 默认情况下, Show() 方法会在显示合并结果前替换掉所有特殊的 fields 和 blocks. 这就是 MergeSpecial() 方法很少在程序中被用到的原因. 特性 Render: 表明合并在哪结束. 它的值必须是以下常量的组合. 默认值为 (TBS_OUTPUT + TBS_EXIT). 语法: int $TBS->Render 特性 Render 可以改变 方法 Show() 和 方法 CacheAction() 的行为. 常量 描述 TBS_NOTHING 表明在合并结束前不进行任何动作. TBS_OUTPUT 表明让TBS使用PHP的echo命令将合并结果显示出来. TBS_EXIT 表明脚本在合并结束后退出. 特性 Source: 获取或设定合并过程中应用的 HTML 源. 调用LoadTemplate() 方法后, 这个特性将包含模板的 HTML 源. 此特性方便你在代码里读取和修改合并结果. 语法: string $TBS->Source 特性 TplVars: 包含对应于当前模板的模板变量数组. 语法: array $TBS->TplVars 你可以使用参数tplvars在一个或多个onload automatic fields 定义模板变量. 当调用LoadTemplate()方法时,所有tplvars后的参数将被添加到 TplVars 特性里. 示例: [onload;tplvars;template_version=‘1.12.27‘;template_date=‘2004-10-26‘] 这个 TBS 标签将创建等同于以下PHP代码的项: $TBS->TplVars[‘template_version‘] = ‘1.12.27‘; $TBS->TplVars[‘template_date‘] = ‘2004-10-26‘; 备注: - 参数tplvars 仅工作于 onload automatic fields 里. - 在一个模板里你可以多次使用参数tplvars. 添加一个数据源类型: 你可以添加TinyButStrong自身不支持的其它数据源类型. 要实现这点,你需要用特定的声明编写三个函数(或方法), 然后对应添加的类型来命名. 你只需要将他们放在你自己的应用或者一个外部PHP文件上,而不必将函数添加到TBS源文件中. 你可以在TinyButStrong 的 站点 上找到附加的数据源类型. 你有两个选择,要么写函数要么写类. 如果你写函数, 他们必须使用一个特定于你使用数据源的 TBS 标识符来命名他们 (往下看). 如果你要写一个类的方法, 那么方法名必须是tbsdb_open, tbsdb_fetch 和 tbsdb_close. 示例: class clsTest { function tbsdb_open(...) {...} function tbsdb_fetch(...) {...} function tbsdb_close(...) {...} } TBS 标识符 (适用于用户函数): The $Source argument that you pass to the MergeBlock() method has a specific TBS identifier that you must use for the function naming. If $Source is an object, then the TBS identifier is the name of Php class. If $Source is a resource, then the TBS identifier is the resource type. If $Source is a string, then the TBS identifier is this string. The type of the $Source argument must not yet be supported in native by TinyButStrong, otherwise the functions will be ignored. The TBS identifier may be arranged by TBS to make it fit for a function name. 示例: 如果 $Source 是一个Sybase链接 (resource type = ‘sybase-db link‘), 那么TBS 标识符就是 ‘sybase_db‘. 函数或方法的声明: 添加到你程序里的三个函数必须遵循以下语法: 如果你决定写一个函数, 那么请用关键词‘customdb‘ 替换掉成数据源类型里的 TBS 标识符. 如果你想写成一个类, 请将函数的名字改为tbsdb_open, tbsdb_fetch 和 tbsdb_close. function tbsdb_customdb_open(&$Source,&$Query) {...} 这个函数必须打开一个必须的查询(query)然后返回一个记录标识符. 如果返回的是错误, 函数将返回一个False 值,并显示相应的信息. 参数 描述 $Source 与传递到 MergeBlock() 方法的参数相同. $Query 与传递到 MergeBlock() 方法的参数相同. 示例: function tbsdb_sybase_db_open(&$Source,&$Query) { return sybase_query($Query,$Source) ; } function tbsdb_customdb_fetch(&$Rs{,$RecNum}) {...} 这个函数必须返回一个包含columns‘ 名和值并与现有记录相关联的数组.当没有记录时,函数不得不返回一个 False 值. 参数 描述 $Rs 从tbsdb_customdb_open() 函数返回的记录集标识符. $RecNum 可选. 预期的记录数. 第一个是数字 1. 示例: function tbsdb_sybase_db_fetch(&$Rs) { return sybase_fetch_assoc($Rs) ; } 如果你的数据源需要知道预期的记录数, 你可以添加 $RecNum 参数到你的函数声明. 除此之外, 这个参数是可选的,因为所有记录都会被按顺序的调用. function tbsdb_customdb_close(&$Rs) {...} 这个函数不得不关闭或释放记录标识符. 它不一定需要返回一个值. 参数 描述 $Rs 从tbsdb_customdb_open() 函数返回的记录集标识符. 示例: function tbsdb_sybase_db_close(&$Rs) { return sybase_free_result($Rs) ; } 面向对象编程: 如果你是个 OOP 开发者, 你可能更喜欢 TBS 工作于对象方法而不是全局函数, 以及对象特性而非全局变量. 现在, 你首先要直接或间接的将 ObjectRef 特性指向一个存在的对象. 示例: $TBS->ObjectRef = &$MyObject; // Use ‘&‘ to define the property by reference. 或: $TBS->ObjectRef[‘key1‘] = &$MyObject; // Indirect reference 接着, 你仅需要在所有TBS函数名前加上字符‘~‘ 特性指出一个 ObjectRef 方法而非全局函数. 像对应的全局函数需要的一样,在类里编写的代码必须拥有相同的语法. 比如普通的 Var Fields, OOP 语法支持由点分隔开的子实体 (数组项, 特性, 方法). Var Fields 可以把 ObjectRef 对象指向给方法, 同时也指向给它的特性. 下列是支持‘~‘ 前缀的特征: 特征 示例 Var Fields [var.~prop1] ... [var.~.key1.prop1] ... [var.~meth1] ... [var.~prop2.subprop] Parameter ondata [blk1.column1;block=tr;ondata=~meth_ondt] Parameter onformat [blk1.column2;onformat=~meth_onfrm] MergeField() method $TBS->MergeField(‘fldname‘,‘~meth_MrgFld‘,true); Custom Data Functions (*) $TBS->MergeBlock(‘blk1‘,‘~mydb‘,‘SELECT * FROM t_table‘); Custom Html conversion function $TBS->LoadTemplate(‘mytemplate.htm‘,‘=~meth_htmlconv‘); (*) 三个方法,而不是三个函数, 必须用给出的关键词定义. 举例说关键词‘~mydb‘, 方法必须命名为 mydb_open(), mydb_fetch() 和 mydb_close(). 示例 (适用于 ezSQL): class mydb Extends db { function mydb_open(&$source,&$query) { $this->get_results($query) ; return $this ; } function mydb_fetch(&$db,$num) { $x = $this->get_row(null,ARRAY_A,$num-1) ; if (is_array($x)) { return $x ; } else { return false ; } } function mydb_close(&$db) { // not needed } } HTML 方面: You design your template by placing TBS tags in the places where data items should appear. There are two types of TBS tags: Fields and Blocks. A TBS Field is a TBS tag which has to be replaced by a single data item. It is possible to specify a display format and also other parameters. The syntax for TBS Fields is described below. A TBS Block is an area which has to be repeated. It is defined using one or two TBS fields. Most often, it is the row of an HTML table. The syntax for TBS Blocks is described below. TBS Fields: A TBS Field is a TBS tag which has to be replaced by a single data item. It has a name which enables you to identify it and parameters can be supplied in order to change the display behaviour. Syntax: HTML ... [FieldName;params] ... HTML Element Description FieldName The name of the Field. Warning: names that begin with var. , onload and onshow are reserved. They are respectively used for Var fields, and Automatic fields. params Optional. One or more parameters from the list below and separated with ‘;‘. Some parameters can be set to a value using the equal sign ‘=‘. Example: frm=0.00 If the value contains spaces or semicolons, you can use single quotes. Example: frm=‘0 000.00‘. It is possible to embed TBS fields. It means you can write this: [var.v1; if [var.v2]=1]. But: - for Var fields, you have to make sure that v2 will be merged before v1. - for block fields, you have to make sure that column v2 is before column v1. Field‘s parameters: Parameter Description htmlconv=val Enables you to force or prevent the conversion of the data item to Html text. The value val can be one of the following keywords: yes: (default value) Force the conversion to Html including new lines. no: Prevent the conversion to Html. Useful to modify Javascript code or to modify the Html source. nobr: Force the conversion to Html but new lines (useful for <pre> tags for example). wsp: Preserve white spaces (useful for spaces at the beginning of lines). esc: No Html conversion and double the single quote characters (‘). js: Convert the data item to a string that can be inserted between JavaScript text delimiters. look: Convert the data item to Html only if no Html entities are found inside the data item. You can specify several values using seperator ‘+‘. Example : htmlconv=yes+js . (dot) If the data item is empty, then an unbreakable space is displayed. Useful for cells in tables. ifempty=val If the data item is empty, then it is replaced with the specified value. magnet=tag Assign a magnet Html tag to the TBS field. A magnet tag is kept as is when the field has a value, and is deleted when the field is null or empty string. Example: (<a href="[var.link;magnet=a]">click here</a>) Result for $link=‘www.tbs.com‘: (<a href="www.tbs.com">click here</a>) Result for $link=‘‘: () By default, the magnet Html tag should be a pair of opening-closing tags (like <a></a>) which first tag is placed before the TBS fields. But this can be changed using parameter mtype (see below). Remark: the parameters if then else are processed before parameter magnet. mtype=val To be used with parameter magnet. Define the magnet type. Value Magnet behavior when field is null or empty string m*m That‘s the default value. Delete the pair of tags that surrounds the TBS field. Everything that is between them is deleted also. The field can be put inside one of the tags. Example: (<a href="[var.link;magnet=a]">click here</a>) Result for $link=‘www.tbs.com‘: (<a href="www.tbs.com">click here</a>) Result for $link=‘‘: () m+m Delete the pair of tags that surrounds the TBS field, but keeping everything else that is between the tags. Example: (<a href="mailto:[blk.email;magnet=a;mtype=m+m]">[blk.name]</a>) Result for $email=‘[email protected]‘: (<a href="mailto:[email protected]">MyName</a>) Result for $email=‘‘: (MyName) m* Delete the single tag that is before the field, and everything that is between the tag and the field. Example 1: <img href="[var.link;magnet=img;mtype=m*]"> Example 2: <br> [var.address;magnet=br] *m Delete the single tag that is after the field, and everything that is between the tag and the field. Example: [var.address;magnet=br;mtype=*m]<br> selected This parameter enables you to select an item for a List, Radio buttons or Checkboxes placed into a Html form. You have to ensure that items are created (merged) before the merge. Html List: Use the parameter selected without setting a value to it. The TBS Field has to be placed within the list of values. When the TBS field is merged it is deleted, but the item which has the same value as the field will be selected. If the value is not found, a new item is added. Example: BostonWashingtonNew York[town_id;selected] which will be after the merge: BostonWashingtonNew York Radio buttons and Checkboxes: Use the parameter selected with setting a value to it which is the name of the Radio buttons or Checkboxes to process. The TBS Field has to be placed within the form. When the TBS field is merged it is deleted, but the item which has the same value as the field will be selected. Example: Boston [town_id;selected=r_test] Washington New York which will be after the merge: Boston Washington New York In this example, the Radio button captioned ‘Washington ‘ has been selected because the name of the Radio button tag is ‘‘r_test‘ and its value is 2, and the TBS tag named ‘town_id‘ has been merged with the value 2. Multi-selection: For Lists, Radio buttons or Checkboxes, you can make a multi-selection by giving a Php array as the value of the TBS field. Bounds: By default the bounds for searching items to select are html tags <select> for List , and <form> for Radio buttons and Checkboxes. But you can change them using parameter selbounds (see below). selbounds=tag To be used with parameter selected. It enables you to change the search zone for items to select by indicating a Html tag type. By default, this value is select for a List, and form for Radio buttons and Checkboxes. Example: [town_id;selected=r_test;selbounds=div] In this example, items to select will be searched between <div> and </div> tags that surround the TBS field. comm This parameter enables you to widen the bounds of the TBS Field up to the bounds of the commentary Html tag which surround it. <!-- [myfield;comm] this is an example--> is strictly identical to [myfield] This is particularly useful for the template designing when you are using a Visual HTML Editor (such as Dreamweaver or FrontPage). noerr Avoid some of the TBS Error messages. When a message can be cancelled, it is mentioned in the message. file=filename Replace the field with the contents of the file. Filename can be a string or an expression built with Var fields that returns the file path. How to use this parameter is detailed in the chapter Subtemplates. script=filename Execute the Php script just before replacing the locator. Filename can be a string or an expression built with Var fields that returns the file path. * Take care that in your script variables are not global but local. This is because the script is called from a TBS method. In order to define or reach global variables in your script, you have to use the Php instruction global or the array $GLOBAL. * TBS gives to you predefined local variables that can be used in your script: - $CurrVal refers to the current value of the field. It can be modified. - $CurrPrm refers to the array of field‘s parameters. - $this refers to the current TBS instance. (See parameter subtpl for good usage) * Parameter script is sensible to the if parameter. If there is a parameter if in the field, then the script is executed only if the condition is verified. See chapter ‘Subtemplates‘ for more details about how to use this parameter in subtemplate mode. subtpl To be used with the parameter script or parameter onformat. Activate the subtemplate mode during the script or function execution. See chapter ‘Subtemplates‘ for more details. once To be used with the parameter script. Cancel the script execution if it has previously been called. getob This parameter is deprecated because it can be replaced with parameter subtpl. To be used with the parameter script. Indicates that the text displayed using the echo() command in the Php script replaces the value of the TBS Field. if expr1=expr2 Display the data item only if the condition is verified, otherwise display nothing unless parameter then or else are used. Supported operators are: = or == equal != not equal +- greater than +=- greater than or equal to -+ less than -=+ less than or equal to Both expr1 and expr2 must be string or numerical expressions. You can use the keyword [val] inside the expressions to represent the data item. The expressions may contain TBS fields, but you have to make sure that they are merged before the containing field. See parameters then and else for some examples. then val1 If the parameter if is defined and its condition is verified, then the data item is replaced with val1. Example: [var.image;if [val]=‘‘;then ‘image0.gif‘] else val2 If the parameter if is defined and its condition is not verified, then the data item is replaced with val2. Example: [var.error_id;if [val]=0;then ‘no error‘;else ‘error found‘] onformat=fct_name Indicates the name of a user Php function that will be executed before the merge of the field. The function fct_name must have the following syntax: function fct_name($FieldName,&$CurrVal,{&$CurrPrm,{&$TBS}}) { ... } Argument Description $FieldName Gives the name of the current field (read only). $CurrVal Refers to the value of the current field (read/write ; don‘t forget the & character in the statement). $CurrPrm Optional. Refers to the array of parameters for the current field (Don‘t forget the & character in the statement). $TBS Optional. Refers to the current TBS instance. (Don‘t forget the & character in the statement). Use this argument with lot of care. It is provided for the subtemplate mode. See chapter ‘Subtemplates‘ for more details about how to use this arguments in subtemplate mode. protect=val Enables you to protect or unprotect the data item to be merged by replacing the characters ‘[‘ with their corresponding Html code ‘[‘. The value val can be one of the following keywords: yes: (default value) data item is protected. no: data item is not protected. By default, all data merged with a template is protected except if it‘s a file inclusion. It is strongly recommended to protect data when it comes from free enter like on a forum for example. max=val Indicates the maximum number of characters to display. Beyond this limit, the data item is cut and an ellipsis (...) is added at the bottom. frm=format Specify a format to display a data item of type date/time or numeric. For a numeric item, it is possible to use a conditional format which changes depending on the sign of the value. Date-time format: It is a VisualBasic like format. The following keywords are recognized: d, dd, ddd, dddd: number of the day, number of the day in two digits, short name of the day, full name of the day. Use parameter locale to display locale names. xx displays st, nd, rd or th depending to the number of the day. m, mm, mmm, mmmm: number of the month, number of the month in two digits, short name of the month, full name of the month. Use parameter locale to display locale names. yy, yyyy: year in two digits, full year. hh, nn, ss: hour, minutes, seconds in two digits. Other characters are kept. It is possible to protect the strings inside by putting them between single or double quotes. Examples: [fld;frm=mm/dd/yyyy] will display 12/21/2002 [fld;frm=‘yyyy-mm-dd hh:nn:ss‘] will display 2002-12-21 15:45:03 Numeric format: To define the decimal part, use an expression like ‘0x0...‘ where ‘x‘ is the decimal separator , and ‘0...‘ is a continuation of zeros corresponding to the number of decimals. If there is no decimal, use the format ‘0.‘ (with a dot). To define a thousand separator, use an expression like ‘0z000x...‘ where ‘z‘ is the thousand separator. If there is no decimal, use the format ‘0z000.‘ (with a dot). If the format contains the character ‘%‘, then the value to display will be multiplied by 100. The character ‘%‘ is displayed too. The numerical format may contain other strings. But only the expression with one or more zeroes placed to the right will be taken as a format, other characters will be kept. Examples: Value Field Display 2456.1426 [fld;frm=‘0.000‘] 2456.143 [fld;frm=‘$ 0,000.00‘] $ 2,456.14 [fld;frm=‘$ 0,000.‘] 2,456 0.2537 [fld;frm=‘0.00 %‘] 25.37% [fld;frm=‘coef 0.00‘] coef 0.25 Conditional formats: You have the possibility to define up to 4 conditional formats when the value is respectively positive, negative, zero or null (or empty string). Conditional formats must be separated by a ‘|‘ character. Each conditional format is optional. Examples: Value Field Display 2456.1426 [chp;frm=‘+0.00|-(0.00)|*|empty‘] +2456.14 -156.333 [chp;frm=‘+0.00|-(0.00)|*|empty‘] -(156.33) 0 [chp;frm=‘+0.00|-(0.00)|*|empty‘] * null [chp;frm=‘+0.00|-(0.00)|*|empty‘] empty -8.75 [chp;frm=‘+0.00|-(0.00)‘] -(8.75) locale To be used with the parameter frm. Indicates that the format specified with frm must display locale day and month‘s names. Locale informations can be set using the PHP function setlocale(). tplvars Enables you to define variables in the template that you can retrieve in the Php programm using TplVars property. Works only with onload automatic fields. Var fields: Var field 是一个显示PHP变量的TBS区域. 它的名字必须有一个关键词‘var.‘ 后面跟着变量的名字. 标准TBS区域和参数同样适用于Var fields. 例如 [var.php_version] 将被 "4.2.3" 替代. 用户变量和预定义变量可以被合并,但是必须是全局变量.源变量(Resource)将被忽略 你可以利用点‘.‘指定项来合并一个数组变量. 例如: [var.myarray.item] 同样你也可以靠它来合并一个对象变量. 例如: [var.myobject.property] 内嵌 Var Fields 放在 file, script, if, when (TinyButStrong2.02后还支持then 和 else) 里的内嵌 Var Fields总是能被处理,其它情况下, 你需要确定这个内嵌区域是否已合并. 其它内嵌 Var Field 将被忽略. Var fields 会在什么时候被合并? Var fields 将在使用方法 Show() 时被合并,意思就是在显示合并结果前. 但你可以在任何时候使用 MergeSpecial() 方法来强制合并. 安全: 如何限制 Var fields 在模板中使用? 当你创建TBS对象时,可以定义一个允许变量前缀来限制 Var fields. 例子 : $TBS = new clsTinyButStrong(‘‘,‘x1_‘); 在这个例子里, 只有拥有前缀‘x1_‘ PHP全局变量可以放在模板里. 而其它的Var fields 将在合并时产生一个错误信息. [var.x1_title] 将合并存在的 $x1_title. [var.x2_title] 将产生一个错误信息. NB: 在上面例子中第一个参数 ‘‘ 被用来定义TBS标签定界符.但是相关的信息在此手册中不做描述. 特殊的 Var fields: 一个特殊的 Var field 是TinyButStrong 系统中显示数据的 TBS Field . 它必须以 ‘var..‘ 开头, 后面跟一个下面列出的关键词. TBS区域的参数同样适用于特殊Var区域. 例子: Date of the day : [var..now;frm=‘mm-dd-yyyy‘] 名称 描述 var..now 服务器当前时间. var..version TinyButStrong当前版本号. var..script_name 当前执行的PHP文件名. var..template_name 最后加载的模板文件名. 它来自于 LoadTemplate() 方法. var..template_date 最后加载的模板文件的创建时间. var..template_path 最后加载的模板文件的路径. 来自于 LoadTemplate() 方法. var..tplvars.* 此值用在 TplVars 特性项中. (‘*‘ 必须是数组中存在项的键值) 特殊 Var fields 什么时候被合并? 特殊 Var fields 与普通 Var fields一样. 在调用 Show() 方法后合并, 意思就是在显示合并结果前. 但你可以在任何时候使用 MergeSpecial() 方法来强制合并. TBS 块: 一个 TBS 块允许你从记录源显示数据. 合并数据和块的流程由方法 MergeBlock() 完成. 合并时, TBS 块的重复次数对应记录数;同时相关联的TBS fields 被 columns 值代替. 一个 TBS field 关联到 Block1 以及显示 ColumnA 的值必须命名为 Block1.ColumnA 例如: [Block1.ColumnA;frm=‘mm-dd-yyyy‘] 两个拥有相同名称的块将被视为一个块的两个部分 (参见 sections of blocks). 块的语法: 共有三种定义 TBS 块的语法: 外部语法: 使用两个 TBS 标签. 一个放块前一个放块后. 例如: HTML...[BlockName;block=begin;params]...HTML...[BlockName;block=end]...HTML 用于块定义的 TBS 标签将在合并时被删除. 关联语法: 块被一对配对的HTML标签定义. 只需要一个TBS标签. 例如: HTML...<tag_name...>...[BlockName;block=tag_name;params]...</tag_name...>...HTML 用于块定义的TBS标签必须在HTML标签里. 这个 TBS 标签也将在合并时被删除. 简化语法: 一个相关联的TBS field 被用来定义块(参见上面的关联语法). 例如: HTML...<tag_name...>...[BlockName.ColumnName;block=tag_name;params]...</tag_name...>...HTML 用于块定义的TBS 标签必须在HTML标签之间. 但它不一定是在块中首位的 TBS field. 元素 描述 BlockName TBS 块名. block=begin 指定块首. block=end 指定块尾. block= tag_name 指定块被一对配对的HTML标签包含 <tag_name...>....</tag_name...> . HTML标签内容都属于块的内容. - row 可以使用它来指定表格的行. block=row 等同于 block=tr. - opt 可以使用它来指定HTML列表中的项. block=opt 等同于block=option. params 可选. 一个或多个下列参数. 用 ‘;‘ 隔开. 使用何种语法? ‘absolute‘ 语法很少会被使用到,因为TBS标签通常被放置在两个HTML标签之间.. 另一方面,它便于应用在文本编辑器上. ‘关联‘ 语法使你可以仅使用一个TBS标签即可指定块.此外,没有必要去隐藏TBS标签,因为他们将在显示时被删除.这是相当实用的语法 ‘简化‘ 语法非常简单.它使你可以仅使用一个TBS标签来定义一个TBS块和 TBS Field . 这是最主流最实用的语法. 提示: 你可以使用 ‘关联‘ 或 ‘absolute‘ 语法来完成 Html 标准的自定义标签. 例如: <custom_tag>Hello [blk1.column1;block=custom_tag], how are you?</custom_tag> 块的参数: 参数 描述 extend=n extend=tag1,tag2,... 为块定义更多的扩展标签.这个参数仅适用于关联语法或简化语法中.比如:它让你可以定义在一个两行表格上的块. 语法 1: 使用数字 n (正负都行) 为块定义 n 个下一对扩展标签. 标签名与参数 block 相同. 如果 n 为负数, 那么块将被反扩展,即扩展到前一对标签. 语法 2: 使用一个标签列表 为块定义下一对扩展标签. 标签为列表提供 . encaps=num 指定参数 block 对应HTML标签的TBS标签的封装等级.默认值为 1. 例如: [block1.field1;block=tr;encaps=2] [block1.field2] 上例中, 蓝色行在合并时将被复制,因为 ‘encaps=2‘. 如果 ‘encaps=1‘ 或者参数没值, 那么在合并时被复制的将是桃红色行. comm 这个参数使你能加宽TBS标签的范围到包含它的HTML注释标签里. <!-- [block1;block=tr;comm] 这是个例子--> 等同于 [block1;block=tr] 此参数非常适用于使用可视编辑器进行模板设计. nodata 指定一个仅当没有数据合并时才显示的部分. 例如: [block1.field1;block=tr] [block1.field2] [block1;block=tr;nodata]There is no data. 更多信息, 参见 ‘Sections of blocks‘章节. headergrp=colname 指定一个每次 colname 值变动时显示的 header 部分. colname 必须是一个由数据源返回的有效 column 名. 你可以使用不同columns定义若干 headergrp 部分. 放置次序 headergrp 部分在块可以修改结果. 更多部分, 请参见 ‘Sections of blocks‘. footergrp=colname 指定一个每次 colname 值变动时显示的footer部分. 参见 headergrp. splittergrp=colname 指定一个每次 colname 值变动时显示的splitter部分. 参见 headergrp. parentgrp=colname 指定一个每次 colname 值变动时显示的parent部分. 不同于其它的部分,一个 parentgrp 部分允许普通部分存在与其内.这是一个可以同时定义header 和 footer 部分的方法. serial 指定块为连续主块. 更多信息, 参见章节 ‘serial display (in columns)‘. p1=val1 用于动态查询. 所有在 MergeBlock() 方法形成的字串 ‘%p1%‘ 将被值 val1 代替. 了解更多, 参见章节 ‘dynamic queries / sub-blocks‘. ondata=fct_name 指定在块合并时需要执行的用户函数.函数会在每次获取数据源的时候被调用.你可以使用参数在记录合并前编辑.函数必须使用如下语法: function fct_name($BlockName,&$CurrRec,$RecNum) { ... } 参数 描述 $BlockName 返回调用函数的块名 (只读). $CurrRec 返回相关联包含当前记录的数组 (读/写 ; 别忘记函数以&开头 ). 假如你将变量设置为 False, 它将会停止合并,如同停止的地方就是记录集结尾. $RecNum 返回当前记录的数据(只读, 第一个记录是1). 例子: function f_add_column($BlockName,&$CurrRec,$RecNum) { $CurrRec[‘len‘] = strlen($CurrRec[‘text‘]); } onsection=fct_name 小心使用此参数,因为有可能它将不再被将来的版本所支持. 它被用作兼容性用途,所以你应该使用更快的 ondata 参数. onsection 与 ondata 一样工作, 除了他的用户函数将在合并时每次去调用. So if your block contains header sections or conditional sections, then the function may be called several times for the same record. 函数语法: function fct_name($BlockName,&$CurrRec,&$DetailSrc,$RecNum) { ... } 参数 $DetailSrc 返回当前部分源 (读/写 ; 别忘记函数以&开头 ).. 假如此值为 ‘‘, 它将取消显示此记录. when expr1=expr2 标记此部分为条件部分,当条件被核实,一个条件部分才会被显示. 支持如下算式: = or == 等于 != 不等 +- 大于 +=- 大于或等于 -+ 小于 -=+ 小于或等于 expr1 和 expr2 必须是一个字串或数值表达式. 表达式可以为一个包含 Var fields 的automatic block,或者为已合并块的链接 fields. default 如果在有条件显示部分中没有满足的条件,将显示此部分. several 如果在有条件显示部分有多个满足的条件,将显示此部分. 原文:Indicates that several conditional sections of the block can be displayed if several conditions are true. By default, conditional sections are exclusive. 块的部分: 拥有相同名称的不同块将被视为一个相同块的不同部分. 部分可以用来: - 轮流显示 (普通部分), - 显示空数据 (NoData 部分), - 当每次一个column 更改,显示一个 header (分组部分). 普通部分: 当你定义若干普通部分时,他们会被每个记录轮流使用. 例如: [b1.caption;block=tr] [b1.caption;block=tr] 上例中, 块名 ‘b1‘ 包含两个普通部分. 记录会轮流一个绿色背景和蓝色背景. NoData部分: NoData 部分仅用在数据源没有任何记录时.一个块中只能有一个 NoData 部分. NoData 部分由参数 nodata 定义. 例如: [b1.caption;block=tr] There is nothing. [b1;block=tr;nodata] 分组部分: 每当记录集中 column‘s 值变化时,分组部分才得以显示.你可以使用参数 headergrp, footergrp, splittergrp, 和 parentgrp 来定义heaser. 参见 block‘s parameters 了解更多细节. 例如: Year: [b1.year;block=tr;headergrp=year] [b1.caption;block=tr] [b1.amount] 条件部分: 条件部分的显示需要他们的条件被核实.显示条件由参数 when 定义. 当一个部分拥有这个参数,它就变成需要条件的部分. 参见 Conditional display了解更我细节. 例如: [b1.name;block=tr] [b1.address;block=tr;when [b1.add_ok]==1] 序列显示 (in columns): The serial display enables you to display several records inside a block. For this, you have to use a main block and secondary blocks. Example: Rec 1 Rec 2 Rec 3 Rec 4 Rec 5 Rec 6 Rec 7 Rec 8 Rec 9 ... ... ... In this example, main blocks are the blue lines of the table, the secondary blocks are the pink cells. Syntax: The main block and its secondary blocks are merged using only one call to the MergeBock() method. The main block must be defined using the parameter serial. The secondary blocks must be nested into the main block. The secondary block‘s names must be the name of the main block followed by "_" and a number indicating display order. Example: [bx;block=tr;serial][bx_1.txt;block=td] [bx_2.txt;block=td] [bx_3.txt;block=td] [bx_4.txt;block=td] The corresponding PHP is: $TBS->MergeBlock(‘bx‘,$cnx_id,‘SELECT txt FROM t_info ORDER BY txt‘) Empty secondary block: You can specify a special secondary block that will be used to replace unused secondary blocks (without records). This "Empty" secondary block must have the index 0. It can either be placed inside the main block with the normal secondary block, or alone inside another serial block. The "empty" secondary block is optional. Example: [bx;block=tr;serial][bx_1.txt;block=td] [bx_2.txt;block=td] [bx_3.txt;block=td] [bx_4.txt;block=td] [bx;block=tr;serial][bx_0;block=td] No records found. Remark: The serial display also works with sections of block and dynamic queries. Dynamic queries / sub-blocks: Principles of the dynamic queries: It is possible to use the MergeBlock() method with a dynamic query. In your template, you have to define a block by adding the parameters p1, p2, p3,... with their values. The query given to the MergeBlock() method has to contain marks such as %p1%, %p2%, %p3%, ... in order to welcome the values of the parameters p1, p2, p3,... . Each section of the block to be merged that contains a parameter p1 will be computed as a separate block for which the dynamic query is re-executed. The sections of the block that have no parameter p1 are combined with the previous section with a parameter p1. Example: Country: France [blk.town;block=tr;p1=‘france‘] [blk.country] Country: USA [blk.town;block=tr;p1=‘us‘] [blk.country] Corresponding PHP code: $TBS->MergeBlock(‘blk‘,$cnx_id,"SELECT town,country FROM t_geo WHERE (country=‘%p1%‘)") Result of the merge: Country: France Paris france Toulouse france Country: USA Washington us Boston us Use with sub-blocks: Dynamic queries enable you to easily build a system of a main-block with sub-blocks. Here is how you can do it: - Create a main block, and then a sub-block inside the main block. - Link them by adding to the sub-block a parameter p1 whose value is a field from the main block. - At the PHP side, merge the main block first, and then the sub-block. Example: Country: [main.country;block=table] [sub.town;block=tr;p1=[main.cntr_id]] Corresponding PHP code: $TBS->MergeBlock(‘main‘,$cnx_id,‘SELECT country,cntr_id FROM t_country‘) $TBS->MergeBlock(‘sub‘,$cnx_id,‘SELECT town FROM t_town WHERE (cntr_id=%p1%)‘) Result of the merge: Country: France Paris Toulouse Country: Germany Berlin Munich Country: Spain Madrid Barcelona Remarks: - The parameter htmlconv=esc enables you to pass protected string values to the query. - The dynamic queries also work with sections of block and serial display. Display a navigation bar: TinyButStrong is able to display a navigation bar using the MergeNavigationBar() method. It is quite similar to merging a block using MergeBlock() except that there are page numbers instead of data, and you can use specific fields to display extra info, and options to arrange the navigation bar. Blocks and fields: Use a normal TBS block to display the page numbers. This block will be merged with a virtual data source having as much records as pages to display, and with the following columns: Name Description page Returns the number of a common page, reachable from the navigation bar. curr Returns the number of the active page. first Returns the number of the first page (1 by default). prev Returns the number of the previous page. next Returns the number of the next page. last Returns the number of the last page if it‘s known, otherwise returns -1. page is the only value that changes and its linked field must be placed inside the block. Others columns have always the same value and can be placed inside the block as well as outside the block. Those fields support the parameter endpoint. It will replace the value of the field with an empty string (‘‘) when the active page is equal to first page or last page. This enables you to manage display exceptions with parameter magnet for example. Example: <a href="script.php?page=[nav.first;endpoint;magnet=a;mtype=m+m]">Beginning</a> In this example, the link will be deleted when the active page is the first page. The block can contain a special section to display the active page differently. This section is defined using parameter currpage on the block definition. Example: Template: |< < [nav.page;block=td] [nav.page;block=td;currpage] > >| Php code used: $TBS->MergeNavigationBar(‘nav‘,10,17) ; Result of the merge: |< < 11 12 13 14 15 16 17 18 19 20 > >| Remark: this example doesn‘t display links. Options The block definition can contain parameters that are specific to the navigation bar. Those options can also be defined as a parameter of the MergeNavigationBar() method. Parameter Description navsize=num Number of pages displayed in the navigation bar. (default = 10). navpos=keyword Position of the navigation bar compared to the active page number. Use one of the following keywords: - ‘step‘ (by default) to have the bar progressing by step. - ‘centred‘ to center the bar on the active page number. navdel=blockname Name of a TBS block to delete when there is only one page or no page to display. This TBS block must surroud the navigation bar. If there are several pages to display then only TBS definition tags of this bloc are deleted. pagemin=num Number of the first page (default = 1). Automatic fields and blocks: onload and onshow are reserved names for TBS fields and blocks that are automatically merged when the template is loaded by the LoadTemplate() method and when the result is shown by the Show() method. Automatic fields are merged with an empty value. They accept all TBS field‘s parameters. They are useful for subtemplate and template variables. Example: [onload;file=header.htm] Automatic blocks are not merged with data. They can have only conditional sections. Examples: [onload;block=tr;when [var.status]==1] Status 1 [onload;block=tr;when [var.status]==2] Status 2 See conditional sections for more details. Subtemplates: There are two ways to instert subtemplates in your main template. Primary insertion using parameter file: This is the best way to simply insert a part contained in another file, like usually done for headers and footers. The value given to parameter file must be the name of a file existing on the server. You can use an expression with Var Fields and the [val] keyword which represent the value of the field. Examples: [onload;file=header.htm] [onload;file=[var.file_header]] [var.sub1;file=[val]] Contents of the file is inserted at the place of the field, without no Html conversion and no TBS protection. [onload] tags contained in the file are not processed at the insertion. [onshow] tags and Var fields will be merged on the Show() method because they became part of the main template. The subtemplate can contain any TBS fields, including Var fields and blocks to be merged. If you intend to merge data with a block defined into a subtemplate, then it‘s suggested to use parameter file in an [onload] field in order to ensure that the subtemplate is inserted before you call MergeBlock(). Contents of the subtemplate can be a full HTML page, because TinyButStrong will search for <body> tags and retain only Html part between those two tags if they‘re found. This enables you to work with WYSIWYG subtemplates. If your main concern is high speed merging, you can avoid this feature by explicitly defining parameter htmlconv=no in the TBS field. Parameter file is processed before other field‘s parameters, and the contents of the file will make the current value of the field. Take this in account if you want to use other parameters in the TBS field. Insertion driven with Php code using parameter subtpl: Parameter subtpl is useful to manage subtemplate insertion with Php code. Parameter subtpl is active only when used with a parameter script or onformat. It turns the current TBS instance in Subtemplate mode during the script or function execution and can act on a new template without deteriorating the main template. The Subtemplate mode presents the following characteristics: * Php outputs are displayed at the field‘s place instead of being immediately sent to the client. For example, using the Php command echo() will insert a text in the main template instead of be directly output it. Using the Show() method will also insert the result of the sub-merge into the main template. * A reference to the TBS instance is provided by local variable $this or $TBS, whether you use parameter script or onformat. This variable be used for new submerges without deteriorating the main template. The Show() method won‘t stop any script execution during the Subtemplate mode like it does by default in normal mode. When the script or the function ends, the TBS instance returns in normal mode with the main TBS template. Example with parameter script: HTML: [var.file;script=specialbox.php;subtpl] PHP script: <?php echo(‘* Here include a subtemplate *‘); $this->LoadTemplate($CurrVal); $this->MergeBlock(‘blk1‘,$GLOBALS[‘conn_id‘],‘SELECT * FROM table1‘); $this->Show(); ?> Remarks: $CurrVal is a local variable provided by TBS when using parameter script ; this variable is a reference to the value of the field currently merged. In the example above, $CurrVal has the value of the global variable $file. You can replace it, for example, by the name of the subtemplate to load (for example: ‘mysubtpl.htm‘). See parameter script for more information. Example with parameter onformat: HTML: [var.user_mode;onformat=f_user_info;subtpl] PHP user function: function f_user_info($FieldName,&$CurrVal,&$CurrPrm,&$TBS) { if ($CurrVal==1) { // User is logged in $TBS->LoadTemplate(‘user_info.htm‘); $TBS->MergeBlock(‘blk1‘,$GLOBALS[‘conn_id‘],‘SELECT * FROM table1‘); $TBS->Show(); } else { // User not logged in echo(‘You are not logged in.‘); } } Remarks: $CurrVal is a variable declared as an argument of the function. It‘s TBS that is in charge to call this function making $CurrVal referring to the value of the fields currently merged. In this example above, $CurrVal is equal to the global variable $user_mode. In the same way, variable $CurrPrm is a reference to the array of parameters of the field currently merged, and $TBS is a reference to the TinyButStrong instance currently used. See parameter onformat for more information. 有条件的显示汇总: TinyButStrong 为字段和块的有条件的显示提供几个工具. 有条件的显示字段 在任何 TBS 字段里你可以使用以下参数控制字段是否显示, 以下是所有参数. 参数 描述 . (点) 显示 Html 不可破损空间,假如字段值为空. ifempty=value2 假如字段值为空,显示value2. magnet=tag 假如字段值为空,删除一个或一对标签. if condition then value1 else value2 根据条件真或假显示 value1 或 value2 . frm=format1|format2|format3|format4 改变数字格式或日期/时间格式.不管其值为 正,负,零或空.. 示例: [var.error_id;if [val]=0;then ‘没有错误‘;else ‘发现错误‘] 有条件的显示代码部分 You can use conditional sections any TBS block. A conditional section is a normal section which has a parameter when defining a condition, or parameter default. At the block‘s merging, each when condition of conditional sections is evaluated until one is verified. As soon as one when condition is verified, its conditional section is kept and other conditional sections are deleted. If no when condition is verified, then the default section is displayed if it exists. By default conditional sections are exclusive inside a block. It means only one conditional section of a block can be displayed. But this can be changed using parameter several. See below for more details. 有条件的显示正常块的代码部分: Normal blocks are those that you merge with data using the MergeBlock() method. Normal blocks can have conditional sections. Conditions are evaluated for each record of the data source, and they can be expressions containing linked fields or Var fields. 示例: Name: [b1.Name;block=tr] 正常部分 Address: [b1.add_line1;block=tr;when [b1.address]=1] [b1.add_line2] [b1.add_zip] - [b1.add_town] 有条件的显示部分 No address.[b1;block=tr;default] 有条件的显示部分 有条件的显示部分应用于自动块: 自动块 are not merged with data ; that‘s why they cannot have normal sections and linked fields. Automatic blocks can have only conditional sections. Conditions are evaluated only once, and they be expressions containing Var fields. 示例: [onload_ligth;block=tr;when [var.light]=1] Light is ON. [onload_ligth;block=tr;when [var.light]=0] Light is OFF. [onload_ligth;block=tr;default] Light is ? This block will be automatically merged when the template is loaded. Non-exclusive conditional sections: If you want a block to have non-exclusive conditional sections, you can use parameter several on the first conditional section. With this parameter, all conditions are evaluated and each true condition makes its section to be displayed. 示例: [onload_err;block=tr;when [var.email]=‘‘;several] Your email is empty. [onload_err;block=tr;when [var.name]=0] Your name is empty. [onload_err;block=tr;default] All is ok. 概要: TBS 字段参数: 参数 概要 htmlconv Html 字段值转换模式. . (点) 假如值为空, 将显示一个不能破损的间隔. ifempty 假如值为空, 将显示其它值. magnet 假如值为空, 将删除周围的标签. mtype 配合 magnet 使用. if 假如条件为真, 将改变它的值. then 配合 if 使用. else 配合 if 使用. onformat 执行PHP函数来改变合并的字段. max 限制字符数字. frm 应用一个时间或者数字格式. locale 配合 frm 使用. 显示本地时间的天数和月名. protect 为字符 ‘[‘ 开启保护模式. selected 在 Html 列表中选择一条项目. selbounds 配合 selected 使用. 改变搜索项目默认范围. comm 扩展这个区域一直到注释标签(原文:Extends the field‘s bounds up to the Commentary tag that surround it.) noerr 消除一些 TBS 错误信息. file 指定文件内容.(即:载入一个模板文件) script (指定)执行PHP脚本. subtpl 配合 script 或者 onformat 使用. 运行 TBS 实例到子模板模式. once 配合 script 使用. 防止脚本从几处执行.(可能是说,只允许自己一个 script ) getob 不推荐. 配合 script 使用. 重新得到文本传送给 echo 和 puts them to the 字段空间. TBS 块参数: 参数 概要 block 定义块的范围. extend 扩展块的范围至几个连续的 Html 标签. encaps 扩展块的范围至几个压缩的 Html 标签.(原文:Extends the block‘s bounds upon several encapsulated Html tags.) comm 扩展块的范围至几个压缩的 Html 标签.Extends the block‘s bounds up to the Commentary tag that surround it. nodata 当数据源里有nodata时表明这个部分不显示. headergrp 当一个列的值改变,表明显示一个header 部分.(估计有误,原文如下:Indicates a header section that is displayed when the value of a column changes.) footergrp Indicates a footer section that is displayed when the value of a column changes. splittergrp Indicates a splitter section that is displayed when the value of a column changes. parentgrp Indicates a parent section that is displayed when the value of a column changes. serial 表明包含几个记录的连续部分(原文:Indicates a section that contains a series of several records.) p1 发送一个参数到源数据动态查询. ondata 执行一个 PHP 函数来修改记录当它来自这个数据源(原文:Executes a Php user function to modify the record when it has just been taken from the data source.) onsection 执行 Php 函数以达到改变当前合并的块. tplvars 只能配合 onload 字段使用. 定义模板变量. when 配合onload 或 onshow 使用. 当条件正确时显示此部分. default 配合onload 或 onshow 使用. 当都不符合条件时才显示此默认块. several 配合 when 使用. 指定组里的几个块可以显示. 分页导航的字段和参数: 字段 概要 nav.page 显示(总)页数. nav.curr 显示当前页数. nav.first 显示头一页(始终为 1). nav.prev 显示上一页. nav.next 显示下一页. nav.last 显示最终一页 (-1 假如末知). 参数 概要 currpage 指定部分那是显示仅是当前页.Indicates a section that is displayed only for the current page. endpoint 假如当前页为头页或尾页时返回空字串. navpos 指定导航条为当前页数Indicates how the navigation bar is positioned compared to the current page number. navsize 指定要显示第几页. pagemin 指定第几页开始显示(即从第几页开始计数). 特殊的字段和块: 名称 概要 val 关键词 [val] 可以放在字段参数内表示本字段的值. var.* 显示 Php 变量. var..* 显示关于 TinyButStrong 的系统信息. # 块的虚拟列名. 它显示返回记录数. $ 块的虚拟列名. 它显示源PHP数组的记录值. onload 自动字段或者块, 模板加载时合并. onshow 自动字段或者块, 模板显示时合并. .:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:
时间： 2024-10-14 05:10:31