金桔框架文档
<![CDATA[# 简介
金桔框架是一个用于Xiuno BBS的主题/插件设置选项框架，开发人员和设计人员可以轻松地使用数组（Array/JSON）创建主题/插件选项。该框架减轻了很多管理设置选项的工作量，使您可以将更多精力放在主题/插件的开发上，而不必花费大量时间来创建和管理主题选项。
金桔框架包含所有默认的Xiuno PHP控件，并增加更多定制化的控件，大部分遵守Xiuno的编码要求。
如果你为自己或为你的客户制作主题，你可以使用这个框架。该许可证允许你在个人或商业主题中使用。
# 安装及配置
这个框架与GPL兼容，只需将其捆绑在插件中即可，无论你是开发免费的还是收费的插件。
-------------------------
1. 在plugin文件夹里，按照“作者名，下划线，插件名”的规则创建一个文件夹。文件夹的名字将会作为插件设置的名字。
2. 下载该框架的最新版本，然后将整个解压后的文件夹放在刚才新建的文件夹中。
3. 编辑conf.json，修改这些：
1. name——插件的名字（会出现在设置面板中）
2. breaf——插件的简介
3. username——换成你的名字
4. uid——把data-href里的内容换成你的网站网址
4. 编辑conf.php里的$data即可配置设置项。
5. 编辑hook/header_start.htm，搜索“your_plugin_name”，替换成刚才新建的文件夹的名字，并保存。
6. 别忘了替换掉icon.png图标文件。
本框架的配置文件与Acid WordPress Customizer Framework互通，可以直接使用。金桔框架只添加了'kumquat_config'部分。
# 面板与设置项配置
请务必按照层次规则写。
层次为：
```php
$data = [
'panels' => array [ /* 面板 */
'demo-panel' => [ /* 至少要有一个 */
'sections' => [ /* 部分 */
'demo-section' => [ /* 至少要有一个 */
'options' => [ /* 设置项 */
'demo-option' => [ /* 可以没有 */
],
],
],
],
],
],
'kumquat_config' => [ /* 金桔框架设置 */
],
];
```
## 面板
面板是设置页面中的Tab。
```php
'demo-panel' => [
'title' => '外观', /* 显示名称 */
'description' => '配色、字体等', /* 面板的介绍文字 */
'sections' => [ /* 部分 */
/* 见下一部分 */
]
],
```
## 部分
顾名思义。
```php
'demo-section' => [
'title' => '颜色设置', /* 显示名称 */
'description' => '在这里自定义颜色', /* 该部分的介绍文字 */
'_cols' => 1 /* 一行显示几个设置项，可选范围：1~4；可选；只作用于这个部分 */
'options' => [ /* 设置项 */
/* 见下一部分 */
],
],
```
## 设置项
顾名思义。
```php
'demo-color' => [
/* 以下为必填参数 */
'label' => '选择颜色', /* 显示名称 */
'type' => 'text', /* 设置项类型 */
'default' => '#cc0000' /* 默认值 */
/* 一些设置项可能会有更多的参数，详见下方“控件”部分。 */
],
```
在本文档中，每种控件的可能返回值用`@return`标记。你不需要在实际代码中用到`@return`。
## 针对框架本身的配置
```php
'kumquat_config' => [
'allow_delete_plugin_settings' => true, /* 允许删除插件设置 */
'allow_reset_settings' => true, /* 允许重置插件设置 */
'show_all_vars_table' =>true, /* 显示“全部变量”框，只在调试模式显示 */
],
```
## Flag
> ### 网上老说的flag是什么意思
> 其实flag这个词语的中文含义是“旗帜”的意思，也是编程代码里面经常会用到的一个词语，在编程代码里面主要指的是某一件事情的判定依据。也就是说flag指的是确定一件事情的结局的关键内容，是这个结局比较直接的相关事情，立flag也就是触发了关键事情的意思。
```php
'kumquat_flag' => [ /* 金桔框架——标志；除非有必要，否则勿动 */
'delete_plugin_settings' => false, /* 删除插件设置，若为true则会在卸载时删除插件设置 */
'reset_settings' => false, /* 重置插件设置，若为true则重置 */
],
```
# 调用设置项
有两种方式：
## 直接调用
设置项按照“面板ID/部分ID/控件ID”命名。调用时使用`kumquat_get_setting()`即可：
```php
echo( kumquat_get_setting('your_plugin_name', 'another-panel/demo-section/demo-text') ); //显示demo-text
if ( !empty(kumquat_get_setting('your_plugin_name', 'another-panel/demo-section/demo-text')) ) {
echo( kumquat_get_setting('your_plugin_name', 'another-panel/demo-section/demo-text') );/* 如果demo-text不为空，则显示demo-text */
}
```
## 将整个插件设置赋值给变量
设置项会是一个三维数组，层次分别是“面板、部分、控件”。不包含`kumquat_config`和`kumquat_flag`。
```php
$your_plugin_name_setting = kumquat_get_setting('your_plugin_name');
$your_demo_text = $your_plugin_name_setting['another-panel']['demo-section']['demo-text'];
echo( $your_demo_text ); //显示demo-text
if ( !empty($your_demo_text) ) {
echo( $your_demo_text );/* 如果demo-text不为空，则显示demo-text */
}
```
# 样例代码
```php
```
# 控件
## Xiuno BBS 内置表单控件
金桔框架完全兼容 Xiuno BBS 内置的表单控件（位于`model/form.func.php`）。
### 是/否 单选框
```php
/**
* @return int|bool
*/
'demo_radio_yes_no' => [
'label' => '是/否 单选框',
'description' => 'Yes/No radio box',
'type' => 'radio-yes_no',
'default' => 0,
],
```
### 单选框
```php
/**
* @return string
*/
'demo_radio' => [
'label' => '单选框',
'description' => 'Radio box',
'type' => 'radio',
'default' => 'red',
'choices' => [
'red' => 'Red',
'blue' => 'Blue',
'green' => 'Green',
'purple' => 'Purple',
]
],
```
### 单个复选框
```php
/**
* @return int|bool
*/
'demo-checkbox' => [
'label' => '复选框',
'description' => 'Checkbox',
'type' => 'checkbox',
'default' => true
],
```
### 多个复选框【+】
```php
/**
* @return array
*/
'demo_checkbox_multiple' => [
'label' => '多个复选框',
'description' => 'Multiple checkboxes',
'type' => 'checkbox_multiple',
'default' => [
'red',
'green'
],
'choices' => [
'red' => 'Red',
'blue' => 'Blue',
'green' => 'Green',
'purple' => 'Purple',
]
],
```
### 下拉选择框
```php
/**
* @return string
*/
'demo-select' => [
'label' => '下拉选择框',
'description' => 'Dropdown selection box',
'type' => 'select',
'default' => 'purple',
'choices' => [
'red' => 'Red',
'blue' => 'Blue',
'green' => 'Green',
'purple' => 'Purple',
],
],
```
### 文本框
```php
/**
* @return string
*/
'demo-text' => [
'label' => '文本框，不允许HTML',
'description' => 'Text box, HTML not allowed',
'type' => 'text',
'default' => lang('Created with Kumquat Framework')
],
'demo-text_html' => [
'label' => '文本框，允许HTML',
'description' => 'Text box, allowing HTML',
'type' => 'text_html',
'default' => '<strong>' . lang('Created with Kumquat Framework') . '</strong>'
],
```
### 多行文本框
```php
/**
* @return string
*/
'demo-textarea' => [
'label' => '多行文本框，不允许HTML',
'description' => 'Text area, HTML not allowed',
'type' => 'textarea',
'default' => lang('Created with Kumquat Framework')
],
'demo-textarea_html' => [
'label' => '多行文本框，允许HTML',
'description' => 'Text area, allowing HTML',
'type' => 'textarea_html',
'default' => '<strong>' . lang('Created with Kumquat Framework') . '</strong>'
],
'demo-html' => [
'label' => '所见即所得编辑器，允许HTML',
'description' => 'WYSIWYG editor, allowing HTML',
'type' => 'html',
'default' => '<h1>Hello, world!</h1>' . '<p><em>' . lang('Created with Kumquat Framework') . '</em></p>'
],
```
### 密码输入框
```php
/**
* @return string
*/
'demo-password' => [
'label' => '密码输入框',
'description' => 'Password input box',
'type' => 'password',
'default' => 'password'
],
```
### 隐藏项
少见。
```php
/**
* @return mixed
*/
'demo-hidden' => [
'label' => '隐藏项',
'description' => 'Hidden',
'type' => 'hidden',
'default' => lang('Created with Kumquat Framework')
],
```
## 金桔框架表单控件
### 扩展表单控件
#### 切换开关
和“是/否 单选框”一样，但更好看。
```php
/**
* @return int|bool
*/
'demo_toggle' => [
'label' => '切换开关 单选框',
'description' => 'Toggle Switch Radio box',
'type' => 'toggle',
'default' => false
],
```
#### 按钮组切换 单选框
和一般单选框一样，但更好看。
```php
/**
* @return int|bool
*/
'demo_radio-toggle' => [
'label' => '按钮组切换 单选框',
'description' => 'Button Group Toggle Radio box',
'type' => 'radio-toggle',
'default' => 'blue',
'choices' => [
'red' => 'Red',
'blue' => 'Blue',
'green' => 'Green',
'purple' => 'Purple',
],
],
```
#### 网址输入框
浏览器帮你校验。
```php
/**
* @return string
*/
'demo-url' => [
'label' => '网址输入框',
'description' => 'URL input box',
'type' => 'url',
'default' => isset($_SERVER) ? 'https://' . $_SERVER['HTTP_HOST'] : 'https://www.example.org/'
],
```
#### Email输入框
浏览器帮你校验。
```php
/**
* @return string
*/
'demo-email' => [
'label' => '电子邮件地址输入框',
'description' => 'Email input box',
'type' => 'email',
'default' => isset($user) ? $user['email'] : 'kurumichan0822@example.org'
],
```
#### 日期与时间输入框
浏览器帮你校验。
```php
/**
* @return string
* @example 2022-02-02
*/
'demo-date' => [
'label' => '日期输入框',
'description' => 'Date input box',
'type' => 'date',
'default' => date('Y-m-d')
],
```
```php
/**
* @return string
* @example 2022-W01
*/
'demo-week' => [
'label' => '周输入框',
'description' => 'Week input box',
'type' => 'week',
'default' => date('Y-\WW')
],
```
```php
/**
* @return string
* @example 12:34
*/
'demo-time' => [
'label' => '时间输入框',
'description' => 'Time input box',
'type' => 'time',
'default' => date('H:i')
],
```
```php
/**
* @return string
* @example 2022-01-01T12:34
*/
'demo-datetime' => [
'label' => '日期时间输入框',
'description' => 'Date and time input box',
'type' => 'datetime',
'default' => date('Y-m-d\TH:i')
],
```
#### 数字输入框
浏览器帮你校验。
```php
/**
* @return int|float
*/
'demo-number' => [
'label' => '数字输入框',
'description' => 'Number input box',
'type' => 'number',
'default' => 10,
'min' => 0,
'max' => 100,
'step' => 5
],
```
#### 滑竿输入框
```php
/**
* @return int|float
*/
'demo-range' => [
'label' => '滑竿输入框',
'description' => 'Slider input',
'type' => 'range',
'default' => 10,
'min' => 0,
'max' => 100,
'step' => 5,
'show_label' => 1
],
```
#### 带有图片的单选框
普通单选框的变体。
```php
/**
* @return string
*/
'demo-radio-image' => [
'label' => '带有图片的单选框',
'description' => 'Radio box with image',
'type' => 'radio-image',
'choices' => [
[
'label' => 'guy running',
'url' => 'https://via.placeholder.com/256',
],
[
'label' => 'couple',
'url' => 'https://via.placeholder.com/257',
],
[
'label' => 'gal running',
'url' => 'https://via.placeholder.com/258',
],
],
'default' => 1
],
```
#### 颜色选择框
浏览器帮你校验。带有“重置”按钮，可将颜色设置为默认值。
```php
/**
* @return string
*/
'demo-color-picker' => [
'label' => '颜色选择框',
'description' => 'Color selection box',
'type' => 'color',
'default' => '#66ccff',
],
```
#### 颜色选择 单选框
普通单选框的变体。
```php
/**
* @return string
*/
'demo-color-select' => [
'label' => '颜色选择 单选框',
'description' => 'Color selection radio box',
'type' => 'color-select',
'default' => 'blue',
'choices' => [
'red' => 'Red',
'blue' => 'Blue',
'green' => 'Green',
'purple' => 'Purple',
],
],
```
#### 配色方案 单选框
上一个的变体，可容纳任意数量的颜色。
```php
/**
* @return string
*/
'demo-colorschemes' => [
'label' => '配色方案 单选框',
'description' => 'Color scheme radio box',
'type' => 'color_schemes',
'default' => 'green',
'choices' => [
'red' => [
'label' => 'Red',
'colors' => ['#993300', '#CC3300', '#FF3333', '#FF6666']
],
'blue' => [
'label' => 'Blue',
'colors' => ['#0066FF', '#0099FF', '#00CCFF'],
],
'green' => [
'label' => 'Green',
'colors' => ['#009900', '#00CC66']
],
'purple' => [
'label' => 'Purple',
'colors' => ['#9933ff']
],
],
],
```
### 专用表单控件（复合控件）
#### CSS字体选择
可视化调整CSS字体属性。
```php
/**
* @return array
*/
'heading_typo' => array(
'label' => '标题字体',
'type' => 'css_typography',
'args' => array( /* 复写参数 */
'font-size' => 1.75 ,
'font-size_unit' => 'rem' ,
'line-height' => 1.2 ,
),
'default' => array( /* 默认值 */
'font-family'=>'sans-serif' ,
'font-style' => 'normal' ,
'font-weight' => 500 ,
'font-size' => 1.75 ,
'font-size_unit' => 'rem' ,
'line-height' => 1.2 ,
),
),
```
#### 背景图片选择
可视化调整背景图片展示方式。
```php
/**
* @return array
*/
'demo-bgimage' => array(
'label' => '背景图像 组合输入框，包含背景图片位置、重复方式、位置、尺寸、固定方式',
'description' => 'Background Image combination input box with background-url,background-repeat,background-position,background-size,background-attachment',
'type' => 'css_background_image',
'args' => array(
'choices' => array( /* 预设图片地址下拉框的内容，若不写此项，则不显示下拉框 */
'running' => [
'href' => 'https://via.placeholder.com/256',
'label' => 'guy running'
],
'couple' => [
'href' => 'https://via.placeholder.com/257',
'label' => 'couple'
],
),
),
'default' => array( /* 默认值 */
'choices' => 'couple',
'background-url' => 'https://via.placeholder.com/468x60?text=Visit+Blogging.com+Now',
'background-repeat' => 'repeat',
'background-position' => 'center center',
'background-size' => '100%',
'background-attachment' => 'scroll'
)
)
```
### Xiuno BBS 专用表单元素
这些控件专为Xiuno BBS设计。
#### 论坛板块选择
```php
'demo-forums' => [
'label' => '论坛板块选择 单选框',
'description' => 'Forum selection radio box',
'type' => 'forumlist',
'default' => 1, /* 默认值：填写板块ID */
],
'demo-forums_multi' => [
'label' => '论坛板块选择 多选框',
'description' => 'Forum selection checkbox',
'type' => 'forumlist_multi',
'default' => [1,2,3], /* 默认值：填写板块ID数组 */
],
'demo-forums_dropdown' => [
'label' => '论坛板块选择 下拉框',
'description' => 'Dropdown for each forum',
'type' => 'forumlist_dropdown',
'default' => 1,
],
'demo-dropdown_per_forum' => [
'label' => '每个论坛板块使用一种下拉框',
'description' => 'Use one dropdown box per forum board',
'type' => 'dropdown_per_forum',
'choices' => [
'red' => 'Red',
'blue' => 'Blue',
'green' => 'Green',
'purple' => 'Purple',
],
'default' => [1 => 'purple'],
],
```
#### 用户组选择
```php
'demo-usergroup' => [
'label' => '用户组选择 单选框',
'description' => 'User group selection radio box',
'type' => 'usergroup',
'default' => 101, /* 默认值：填写用户组ID */
],
'demo-usergroup_multi' => [
'label' => '论坛板块选择 单选框',
'description' => 'User group selection checkbox',
'type' => 'usergroup_multi',
'default' => [1, 101, 102, 103], /* 默认值：填写用户组ID数组 */
],
```
# 实用函数
## 获取指定插件的地址
在制作一些和前端页面打交道的插件（如主题）时很有用。
```php
<link rel="stylesheet" href="./<?= kumquat_get_setting('your_plugin_name', 'BASE_LOCATION_FRONTEND') ?>view/css/style.css" />
```
# 实用变量
## `$PLUGIN_PROFILE`
`conf.json`的PHP数组版。可在`setting.php`中使用。
# 注意
本框架使用了来自[字节跳动静态资源公共库](http://cdn.bytedance.com/)的 TinyMCE 编辑器，根据《字节跳动静态资源公共库用户协议》，您不应将本框架用于不符合中国现行法律、法规，有违公序良俗的使用场景。
因使用本框架导致的任何损失，框架作者概不负责。
# 作者
- Geticer - 主要作者
- Tillreetree - 开发协力
- 七濑胡桃 - 精神支持
# 许可
MIT Licence
# 鸣谢
1. Acid WordPress Customizer Framework - 灵感来源和设置项结构借鉴
]]>