开发一个短代码插件

课程目标

这节课来开发一个短代码插件,实现自定义短代码,并在此基础上,对 WordPress 自带的编辑器进行增强。

什么是短代码

短代码就是形如[git]这样的代码,WordPress 自2.5版本开始引入短代码机制,通过短代码,一个完全不懂技术的编辑人员也可以发布样式丰富的短代码。

一个短代码应该是由[]所包围,同时可以接受一定的参数。当我们使用短代码时,WordPress 在进行内容加载时,就会将短代码通过代码转换为适当的动态内容。虽然短代码可能很短,但是其转换出来的内容可能会非常长。

短代码的使用有很多种形式,比如:

[git]
[git path="213"]
[git path="123321"]Code[/git]

这三种都是短代码的调用形式,只是有没有加入参数,和是否需要包含内容。

在插件开发过程中,有些时候需要让用户控制一些内容的显示,这个时候就要用到短代码了,通过短代码,可能用户只需要一行代码,就可以执行你的插件中极为复杂的操作。

开发短代码

在最开始,依然是创建插件,这里创建一个新的插件,插件名为 gitchat_shortcode

接下来开发这个插件的功能。

注册一个不需要参数的短代码

首先来注册一个不需要参数的短代码。在插件中加入如下代码,就可以注册一个标签为 git 的短代码了,这个短代码的功能非常简单,就是输出一个 hello world:

function gitchat_git_shortcode() {
    return "Hello World";
}
add_shortcode( 'git', 'gitchat_git_shortcode' );

我们到插件后台,启用这个插件,然后进入文章管理中,创建一篇文章来测试短代码。

发布后,查看文章页面,就可以看到短代码输出了。

这样就完成了一个最简单的短代码。对于一些纯粹展示型的内容,可以通过这样一个简单的方法实现内容的嵌入。

注册一个加入了参数的短代码

不过,大多数的时候,我们的短代码都需要加入一个或多个参数,来实现短代码的功能。这时就需要对短代码进行优化了。

修改一下短代码函数:

function gitchat_git_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'id' => '1',
            'title' => 'hahaha',
        ),
        $atts,
        'git'
    );
}

这样,短代码就成功的接收到了参数,并进行处理,这里传入了三个参数,第一个参数是我们定义的短代码的参数,可以通过[git id="xxx" title="xxxx"]来实现调用。第二个参数则是这个短代码函数接受到的参数,是 WordPress 传递给我们的参数,里面包含了输入时的参数。第三个则是参数对应的短代码。

经过处理后,就可以以$atts['id']的形式在函数内调用具体的参数和值。

比如,我们让短代码输出接收到的参数,将函数改为下面这样:

function gitchat_git_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'id' => '1',
            'title' => 'hahaha',
        ),
        $atts,
        'git'
    );
    return  $atts['id']."__".$atts['title'];
}

回到前台刷新一下页面,我们可以看到,这里我们的短代码将默认设置的值进行了输出。

单击“编辑”按钮,进入后台,修改短代码调用:

再次回到前台,查看输出的内容,可以看到,我们设置的内容已经被输出出来了,这就说明内容可以被参数所接受、处理,最后输出了出来:

注册一个接受标签包含内容的短代码

有些时候,我们不止需要参数,毕竟可能会包含非常多的内容,比如代码高亮类的插件。

此时,希望我们的短代码能够获取到两个匹配标签之间的内容。

再修改一下短代码函数:

function gitchat_git_shortcode( $atts , $content = null ) {
    $atts = shortcode_atts(
        array(
            'id' => '1',
            'title' => 'hahaha',
        ),
        $atts,
        'git'
    );
}

这次,短代码函数接受两个参数,分别是 attscontent,其中 content 就是两个标签之间包含的内容。

这里设置了 content 的值为 null,如果你需要设置默认值,将其改为默认值即可。

将两个参数和内容都输出出来,将代码改为下面这样:

function gitchat_git_shortcode( $atts , $content = null ) {
    $atts = shortcode_atts(
        array(
            'id' => '1',
            'title' => 'hahaha',
        ),
        $atts,
        'git'
    );
    return  $atts['id']."__".$atts['title']."---".$content;
}

现在刷新一下文章页,可以看到,由于短代码没有匹配包含,所以并没有输出 content。

单击“编辑”按钮,将内容修改为[git id="!123" title="你好"]这是我的标题[/git],保存并回到文章页,刷新。

可以看到,这次输入内容正常的刷新出来了。

至此,完成了三种不同类型的短代码开发,足以应付你的绝大多数场景了。

编辑器增强

我们现在开发好了短代码,但是如果设置了多个短代码或短代码有多个参数,用户在使用时就会很麻烦,因为还要去查询短代码的说明。这里,就来实现编辑器的增强,在编辑器上加入短代码的按钮。

QuickTag

WordPress 的编辑器支持两种模式,分别是 TinyMCE 和 QuickTag 模式(HTML)模式,点击编辑器右上角的文本,就可以添加一个按钮到 QuickTag 中了。

接下来实现在编辑器中加入一个 QuickTag。

在插件中加入如下代码:

function gitchat_git_qt() {
}
add_action( 'admin_print_footer_scripts', 'gitchat_git_qt' );

这样就在 WordPress 后台加载底部脚本时,加入了我们自己的函数。接下来来写函数体的内容。

将函数改为下面这样:

function gitchat_git_qt() {
    if ( wp_script_is( 'quicktags' ) ) { // 判断是否正在加载 quicktags 
    ?> 
    <script type="text/javascript">
    // 调用 quick tag 的 api 添加按钮
    QTags.addButton( 'git', 'Git', '[git id="13" title="code"]', '[/code]', '', 'QucikTag For GitChat', 1 );
    </script>
    <?php
    }
}

我来解释一下上面这段代码。

首先,使用 if 语句来判断当前是否正在加载 quicktag 相关的脚本,因为如果你加载的过早,会导致 Qtags 实例调用失败,也就没有办法来加载按钮了。

然后嵌入一段 JavaScript 代码。这个代码很简单,使用 QTagsaddButton 方法,来加载一个新按钮,这个函数接受8个参数,不过定义时一般来说,可以不传入那么多。

QTags.addButton( id, display, arg1, arg2, access_key, title, priority, instance );

第一个参数是按钮的 ID,需要是唯一的;第二个参数则是这个按钮上显示的文字,比如设置为 Git,显示的时候是,可以设置成为你自己的(比如使用 dashicons);第三个参数则是第一次按下这个按钮时,会输出的内容;第四个参数是第二次按下这个按钮会输出的内容;第五个参数是 access_key,目前已经被弃用了,我们就不用管了;第六个参数是标题,当鼠标指针悬浮在这个按钮上时,将会展示标题文字,可以将其设置为短代码的说明或按钮的说明;第七个参数是优先级,这个参数会决定短代码的位置,比如将其设置为 1-9 时,这个按钮会放在第一位;设置为 11-19 时,会放在第二个位置,如果你希望放在最后,则需要设置一个非常大的值才行;最后一个参数是对按钮进行设置,可以给短代码加入 ariaLabel 和 ariaLabelClose ,基本用不到,可以不填。

为什么第三个和第四个参数要这样拆?

这是因为,如果选中文字再按下按钮时,编辑器会自动将选中的内容放在参数三和参数四之间,类似这样:

如果拆分有问题,生成的代码可能就有问题了,将短代码的参数放在参数三是更为合适的。

保存插件,进入新建文章页面,将编辑器切换为 QuickTag 编辑器,就能看到添加的按钮了:

TinyMCE 增强

QuickTag 非常方便,但是大多数人更习惯使用 TinyMCE,所以我们还要针对 TinyMCE 编辑器进行增强。

Tiny 编辑器的增强就比较麻烦了。

首先要为这个按钮创建一个 JS 文件,在插件根目录下创建一个 tinymce.js ,在其中加入如下代码:

// tinymce.js
(function() {
    tinymce.create('tinymce.plugins.gitchat', {
        init : function(ed, url) {
            ed.addButton('gitchat', {
                title : 'GitChat Button',
                image : url+'/icon.png',
                onclick : function() {
                     ed.selection.setContent('[git id="1" title="haha"]' + ed.selection.getContent() + '[/git]');
                }
            });
        },
        createControl : function(n, cm) {
            return null;
        },
    });
    tinymce.PluginManager.add('gitchat', tinymce.plugins.gitchat);
})();

接下来将我们的按钮注册到 TinyMCE 中;重新打开我们的插件主文件,在文件尾部加入如下代码:

 function register_button( $buttons ) {
    array_push( $buttons, "|", "gitchat" ); // 将按钮加到列表尾部
    return $buttons;
 }
 function register_plugin( $plugin_array ) {
    $plugin_array['gitchat'] = plugin_dir_url( __FILE__ ) . '/tinymce.js'; // 新增我们自己开发的插件
    return $plugin_array;
 }
 function gitchat_tinymce_enhance() {
      // 判断用户是否有权限编辑文章/页面,无权则不加载
     if ( ! current_user_can('edit_posts') && ! current_user_can('edit_pages') ) {
        return;
      }
      // 如果未开启富文本编辑,则不渲染。
      if ( get_user_option('rich_editing') == 'true' ) {
        add_filter( 'mce_external_plugins', 'register_plugin' );
        add_filter( 'mce_buttons', 'register_button' );
      }
 }
 add_action('admin_init', 'gitchat_tinymce_enhance');

tinymce.js 中,我们调用 tinymce.create() 创建了一个新的插件,然后使用 init 函数定义了一个新增的按钮和其对应的 onClick 方法,最后使用 PluginManager 来将插件注入到系统中去。

需要准备一个 png 文件作为图标。

接下来在插件主文件中,先定义了 register_button,将我们的按钮放入编辑器的列表中。然后定义了 register_plugin 将插件页注入到 TinyMCE 中去,最后定义了gitchat_tinymce_enhance并将其挂载在 admin_init 上。在这个函数中,我们对具体的权限和是否进行富文本编辑进行了判断,根据判断的结果,决定是否加入我们的插件。

编辑完成后,保存文件,回到后台,进入编辑器,可以看到我们的按钮,已经添加进去了。

选择我们要处理的文字,点击按钮,就可以把相关内容包含在其中了。如果不选择任何东西,则直接将短代码输入到编辑器中。

至此,我们也完成了对 TinyMCE 编辑器的增强。

results matching ""

    No results matching ""