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 或者下方留言。

THE END
夜华子酱我知道你很急,但你先别急