AIYA-Framework 框架使用文档

此部分为 AIYA-CMS 主题核心 项目，有关 “framework-required”  目录下文件（框架本体）的说明。

本体部分只是一个提供给WordPress 主题创建设置选项表单的框架，支持的表单位置和类型如下：

• 单页设置表单
• 分类页 Meta 字段表单
• 文章 Meta 字段表单
• 文章快速编辑（Quick Editor）选项表单 （这个还没做）

支持的组件如下：

• 输入框
• 文本框
• 颜色选择器
• 复选框
• 单选框
• 单选抽屉
• 上传文件
• 数组模式
• 回调（callback）
• 开关（switch）
• TinyMCE编辑器
• Codemirror编辑器
• 设置组
• 设置组（自增）
• 插入文本
• 插入消息框（蓝色、绿色、红色、无色）
• 插入标题（两种样式）

---

如何使用

依赖 WordPress 版本 4.5 及以上，建议能上最新上最新。

将项目的framework-required整个目录复制到主题文件夹中，在主题的 functions.php 中添加：

require_once(get_template_directory() . '/framework-required/setup.php');
require_once(get_template_directory() . '/framework-required/sample-config.php');

此 sample-config.php 包含了所有组件的示例调用 ，其中也有每个组件的参数。

这里要说明的是，sample-config.php 只是框架开发过程时用于测试的模板，项目的启动文件（setup.php）中有封装好的创建和调用函数，以下是一些演示。

 

创建设置页面

接下来展示默认的设置页面创建方式：

AYF::new_opt(array(
    //页面标题
    'title' => 'AIYA-CMS',
    //页面描述
    'desc' => 'AIYA-CMS Theme',
    //页面slug
    'slug' => 'option_page_name',
    //页面选项表单
    'fields' => array(
        //提示
        array(
            'type' => 'message',
            'desc' => 'this is a field demo',
        ),
        //开关
        array(
            'title' => 'field name',
            'desc' => 'this is a field demo',
            'id'   => 'field_demo',
            'type' => 'switch',
            'default' => false,
        ),
        //输入框
        array(
            'title' => 'field name',
            'desc' => 'this is a field demo',
            'id'   => 'field_demo',
            'type' => 'text',
            'default' => 'input here',
        ),
    )
));

调用方式：

AYF::get_checked('field_demo', 'option_page_name');

或者

AYF::get_opt('field_demo', 'option_page_name');

两种调用的区别是， get_checked() 会检查并确保返回的数据是布尔型（true/false），而 get_opt() 会直接返回表单中的参数。

创建分类和文章的字段表单

在分类页面下创建：

AYF::new_tex(
    //添加选项表单
    array(
        //输入框
        array(
            'title' => 'category field',
            'desc' => 'this is a field demo',
            'id' => 'cat_keywords',
            'type' => 'text',
            'default'  => '',
        ),
    ),
    //分类法名称
    'category'
);

调用方式：

get_term_meta($tag->term_id, 'cat_keywords', true);

由于表单是存储在分类meta中的，所以使用WP的方法调用。

在文章下创建：

AYF::new_box(
    //添加选项表单
    array(
        //输入框
        array(
            'title' => 'post field',
            'desc' => 'this is a field demo',
            'id' => 'post_custom_keywords',
            'type' => 'text',
            'default'  => '',
        ),
    ),
    //Meta Box 参数
    array(
        'title' => 'Custom Box',
        'id' => 'post_custom_box',
        'context' => 'normal',
        'priority' => 'low',
        'add_box_in' => array('post'), //定义需要添加的文章类型例如array('post', 'page')
    )
);

调用方式同理：

get_post_meta($post->ID,'post_custom_box',true);

使用WP的方法调用。

内置的查询方法

checkbox组件、select组件和radio组件，额外支持一项参数： 'sub_mode'，

此参数支持的值有：'nav_menu'、'category'、'page'、'user'、'sidebar'。

分别用于列出当前站点的：菜单列表、分类列表、页面列表、用户列表、侧边栏位置列表。

组件兼容

其中设置单页支持所有组件，但是创建分类字段和文章字段时会过滤掉'group'、'group_mult'、'code_editor'、'tinymce'这几个组件。如果你使用'type'参数调用到了这几个组件，循环内部会直接跳过。

因为这几个组件方法需要额外的处理才能正常保存和输出，而且这几个组件都需要加载额外样式和JS，不是很好布局。

 

一些使用和增加功能的参考

框架本体仅需 setup.php 文件和 /inc 目录下的组件，如果你不需要项目外带的预置功能，其他的部分可以删除。

和CSF框架一样，本框架最终也是通过WP的 get_option() 方法保存设置内容的。

位于 setup.php 中有此框架的封装好的创建/调用函数 AYF:: ，但是这样调用可能不是最简化的，你可能需要二次封装或者干脆自己写一个新的。

项目的文件加载结构，位于 inc/framework-steup-action.php ，包含了框架的零件（fileds）和预置功能插件的加载方式，请见内部注释有详细说明。

框架生成的页面并不过滤HTML标签，这是为了方便在参数中使用<code>等标签调整文字样式，如果你要这样用的话应当注意检查标签封闭防止页面整段垮掉。

 

一些注意事项

这个框架兼容多站点模式，但不是很确定是不是真的兼容，WP 官方的文档对于一些钩子的说明也不是很明确，或者也有可能是我太菜了没看懂。

多语言兼容并不完整，请待后续更新，你会发现有些地方是显示的是中文的然后有些地方是英文，这个是因为原来想全写成英文然后懒癌犯了，所以先这样吧。

因为所有的功能目前还没有完全测试，有问题请去项目 issues 或者下方留言。