Tabilet Tutorial

URL设计

URL格式

URL遵守如下固定格式：


http://域名/HANDLER/登录角色名/MIME名/分量?action=执行指令&其它搜索参量

Genelet里总是固定一个 HANDLER（程序调用接口）。
登录角色名为各种用户群，比如电子商务网站里的管理群，供应商群，购物会员群等。Tabilet在线服务可帮助自动构建各类登录角色。字母 p 表示无需登录的外网公共访客群；字母 a表示可执行任何权限的管理员群。
MIME名 用于指示网站回复的内容为何种格式。取值 json 时即返回JSON格式的API，html 返回HTML网页内容，pdf 返回PDF文件档等。此行为可以设置。
分量是Genelet里基本编程单元。一个分量通常对应于一个数据库表格。在Genelet编程里，开发者的主要工作就是设计分量和指令。分量可以在水平方向上不断添加，而不影响软件系统的复杂性。
指令即表示对分量所做的执行指令。因为分量通常对应于数据库表格，指令即对应于数据库表格的一个SQL运算。指令作为分量的函数，可以不断定制。但在Genelet框架里，每个分量都自动继承了 RESTful 指令（见后）。
Genelet和许多REST服务一样，可以不输入 action=指令 而是通过 HTTP METHOD 来指明何种指令。为清楚起见，我们建议你总是输入具体指令名称。
某些时候，需要一个特殊指令调出空白表格供添加新内容用，或对分量做总结作为门户页面用。在Genelet里，此指令通常用 startnew 表示。

Vue.js

Genelet提供一个Javascript桥梁，通过Ajax去调用API，而与流行的Javascript网页编程框架相衔接。目前我们支持Vue.js。
Vue.js下，网站地址表达为
```
http://域名/app.html#/登录角色名/分量?action=执行指令&其它搜索参量
```
整个网站即表现为单个位于固定地址 app.html 上的H5网页。
Tabilet能自动生成前述普通动态网站，和这里基于Vue.js的单页H5网站。

系统起始配置文件

配置文件为JSON格式，通常取名 config.json，内含启动网站所需的所有参数。这里是常用的几个参数：

Document_root: 网站根目录
Project: 项目名称，第一个字母大写
Script: 动态接口（HANDLER）
Server_url: 服务器网址（不含动态接口）
Pubrole: 外网公众角色代号
Template: 动态网页存放的文字模板根目录,
Uploaddir: 上传文件的根目录
Db: 数据库链接字符串，用多元数组表达。
Log: {"Filename": 文件位置名称, "Level": 日志等级},
Chartags: MIME类别，通常自动生成
Roles: 登录角色，通常自动生成

编程基础

在Genelet框架里，开发工作就是添加各种分量和指令。编程基本流程如下。

每个项目都至少需要两个Classes，用两个文件表达。model.php 继承Genelet里的Model。Model就是MVC开发原则里面的M。因为Genelet只用一个动态接口，所以分量共享同一个 Controller。filter.php 继承Genelet里的Filter，它是瘦身了的Controller（所以取不同的英文名"Filter"）。
一个项目下可以有许多分量，每个分量放置在单独目录下。分量目录下有三个文件：component.json，它是定义分量参数和ACL条件等的JSON配置文件，model.php 是继承项目的Model，filter.php 是继承项目的Filter。
componser.json，Model和Filter完成后，此分量的编程工作即告结束。如果你只是调用 JSON API，那么不需要再做其它事。如果需要生成动态网页或H5应用，你还需要设计出 MVC 里面的 View。

component.json

此文件的举例格式如下：

{
  "actions" : {
    "startnew":{"options":["no_method", "no_db"]},
    "insert"  :{"validate":["question_id","choice_text","votes"]},
    "topics"  :{"groups": ["public"]},
    "edit"    :{"validate":["id"]},
    "update"  :{"groups":["public"],"validate":["id"]},
    "delete"  :{"validate":["id"]}
  },

  "fks" : {
    "m" : ["m_id", "m_md5", "id", "id_md5"]
  },

  "nextpages":{
    "topics":[
      {"model":"choice", "action":"topics", "relate_item":{"poll_id":"poll_id"}}
    ]
  },

  "current_table":"polls_choice",
  "current_key"  :"id",
  "current_id_auto" :"id"
  "insert_pars"  :["question_id","choice_text","votes"],
  "edit_pars"    :["question_id","choice_text","votes","id"],
  "topics_pars"  :["question_id","choice_text","votes","id"],
  "update_pars"  :["question_id","choice_text","votes","id"]
}

执行指令集 actions

格式为

	指令名: {"groups":[角色1，角色2 ...], "validate":[变量1, 变量2 ...], "options":["no_method"]}

groups 表示哪些登录角色可以执行此指令。
validate 表示执行此指令时，客户端必须提交的变量（否则将跳出数据库运算错误）
no_method 表示此指令跳过 Model，即不调用M里的函数。

签名认证 fks

格式为

	角色：[待验证输入ID，待验证签名变量，输出可验证ID，输出验证签名变量名]

当角色执行此分量里任何指令时，必须提交 待验证输入ID 和 待验证签名变量 的值。否则将被拒绝执行。
待验证输入ID 将被强制作为条件，出现在继承的RESTful运算SQL语句中。
角色执行此分量的 topics 或 edit 指令后，系统将自动对其中 输出可验证ID 计算其验证签名，放置在 输出验证签名变量名 这个新变量下。

调用其它分量 nextpages

Genelet一个强大功能，是在一个分量里自动调用其它分量的RESTful指令（类似于 GraphQL 的服务）。

格式是

	指令名: [
		{"model":另个分量, "action":另分量的指令, "relate_item":{本分量变量:另分量的变量}}
		...
	]

另个Model: 指调用的另一个分量的Model名称
另分量的指令: 指调用另分量的哪个指令
本分量变量:另分量的变量: 调用过程中，此分量下此变量的值将作为输入送到另分量的执行指令里。
当 relate_item 不存在时，独立调用此分量的指令。
一个指令可以调用多个另分量和指令。

数据库表格参数

current_table: 分量所用的数据库表格
current_key: 表格的主键
current_id_auto: 表格里自动计数栏（auto_increment）
insert_pars: 插入新记录时，哪些数据库栏目允许插入（通常是全部栏目）
topics_pars: 搜索多行时候，哪些栏目允许读出
edit_pars: 按照主键读取记录时，哪里栏目允许读出
update_pars: 按照主键更新记录时，哪些栏目允许更新
current_tables: （注意这里多了 s）用于JOIN在一起的多表格的 topics 指令
topics_hash: 定义多表格输出变量

model.php

此Class下每个函数，即为指令。例子：

<?php
declare (strict_types = 1);
namespace Sandy\Choice;
use Sandy;
class Model extends \Sandy\Model
{
	public function update(...$extra) : ?\Genelet\Gerror {
		if ($this->Get_rolename() == "p") {
			return $this->Do_sql(
"UPDATE poll_choice SET votes=votes+1 WHERE choice_id=?", $this->ARGS["choice_id"]);
		}
		return parent::update(...$extra);
	}
};

RESTful 继承

所有分量自动继承了Genelet系统的 RESTful 指令。即

插入一个新记录
```
public function insert (...$extra) : ?\Genelet\Gerror
```
数据来自 $_REQUEST，$extra 表示需要补充插入的数据
搜索多行记录
```
public function topics (...$extra) : ?\Genelet\Gerror
```
数据来自 $_REQUEST，$extra 表达WHERE里面的条件限制
按照主键调用行
```
public function edit (...$extra) : ?\Genelet\Gerror
```
数据来自 $_REQUEST，$extra 表达WHERE里面的条件限制
按照主键更新行
```
public function update (...$extra) : ?\Genelet\Gerror
```
数据来自 $_REQUEST，$extra 表达WHERE里面的条件限制
按照主键更新行，如果不存在就插入记录
```
public function insupd (...$extra) : ?\Genelet\Gerror
```
数据来自 $_REQUEST，$extra 表达补充插入的数据
按照主键删除行
```
public function delete (...$extra) : ?\Genelet\Gerror
```
数据来自 $_REQUEST，$extra 表达WHERE里面的限制

编写新指令

新添函数的格式必须是

public function 指令名称 (...$extra) :  ?\Genelet\Gerror {
}

当程序出错时，输出错误。而运算正确后，输出 null。运算结果存放在此面向对象下，名为 $LISTS 和 $OTHER的l两个数组变量里。
重新编写相同名称的RESTful函数，即覆盖Geneletc此缺省指令。
如果需要调用其它分量的 nextpages，可在最后输出
```
	return $this->process_after(本指令, ...$extra);
```
系统即自动在 component.json 自动寻找需要调用的 nextpages。

数据库函数

Genelet提供了一组高速执行数据库运算的程序库，供你在开发Model时使用。我们将另文介绍。

filter.php

样本：

Role_name;
  $action = $this->Action;
  $obj = $this->Component;

  return null;
}

public function Before(object $model, array &$extra, array &$nextextra)  : ?\Genelet\Gerror {
  $err = parent::Before($model, $extra, $nextextra);
  if ($err !== null) { return $err; }

  $ARGS =& $_REQUEST;
  $role = $this->Role_name;
  $action = $this->Action;
  $obj = $this->Component;

  return null;
}

public function After(object $model) : ?\Genelet\Gerror {
  $err = parent::After($model);
  if ($err !== null) { return $err; }

  $ARGS =& $_REQUEST;
  $role = $this->Role_name;
  $action = $this->Action;
  $obj = $this->Component;

  return null;
}

}

Preset()

数据准备阶段，常见功能有：

补充输入数据，如用户IP
再次查看是否遗失必须的栏目
其它Form Validation，如数据格式是否准确
生成新数据，如从用户输入的密码，生成SHA1签名作为新密码
定义分页参数（pagination）

Before(object $model, array &$extra, array &$nextextra)

链接数据库前，需在 $model 里做的准备工作：

添加SQL执行条件。如
```
$extra["firstname"] = "John";
```
即添加 firstname='John' 至SQL的WHERE语句里。具体使用另外介绍。
执行指令前，调用其它分量的预备数据
设置$nextextra 以便提供 nextpages 所需的附加数据。

After(object $model)

获取数据后，可在这里做进一步处理。常见功能有

处理和更改数据，以便获得期待的显示方式。如 timestamp 里年份去掉。
根据特殊情况，生成新的（不易在Model里产生的）可用数据
调用其它分量
生成为传送EMAIL，SMS等额外服务需要的数控块。

变量

除了输入变量外，你可以从下面引导出常用变量，以便编程。

$ARGS =& $_REQUEST: 客户端输入数组
$role = $this->Role_name: 角色名
$action = $this->Action: 指令名
$obj = $this->Component: 分量名
$tag = $this->Tag_name: MIME代号

网页显示模板

模板的根目录由 config.json 里 Template 参数定义。
当用户请求如下URL时（这里的 MIME名 缺省取值为 html）
```
http://域名/HANDLER/登录角色名/MIME名/分量?action=执行指令&其它搜索参量
```
模板为 根目录/登录角色名/分量/执行指令.MIME名。
登录页面为 根目录/登录角色名/login.MIME名。

tabilet指南

Genelet编程开发指南