目录

课程目标

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

什么是短代码

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

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

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

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

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

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

开发短代码

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

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

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

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

<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">gitchat_git_shortcode</span><span class="hljs-params">()</span> </span>{
    <span class="hljs-keyword">return</span> <span class="hljs-string">"Hello World"</span>;
}
add_shortcode( <span class="hljs-string">'git'</span>, <span class="hljs-string">'gitchat_git_shortcode'</span> );

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

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

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

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

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

修改一下短代码函数:

<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">gitchat_git_shortcode</span><span class="hljs-params">( $atts )</span> </span>{
    $atts = shortcode_atts(
        <span class="hljs-keyword">array</span>(
            <span class="hljs-string">'id'</span> => <span class="hljs-string">'1'</span>,
            <span class="hljs-string">'title'</span> => <span class="hljs-string">'hahaha'</span>,
        ),
        $atts,
        <span class="hljs-string">'git'</span>
    );
}

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

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

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

<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">gitchat_git_shortcode</span><span class="hljs-params">( $atts )</span> </span>{
    $atts = shortcode_atts(
        <span class="hljs-keyword">array</span>(
            <span class="hljs-string">'id'</span> => <span class="hljs-string">'1'</span>,
            <span class="hljs-string">'title'</span> => <span class="hljs-string">'hahaha'</span>,
        ),
        $atts,
        <span class="hljs-string">'git'</span>
    );
    <span class="hljs-keyword">return</span>  $atts[<span class="hljs-string">'id'</span>].<span class="hljs-string">"__"</span>.$atts[<span class="hljs-string">'title'</span>];
}

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

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

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

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

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

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

再修改一下短代码函数:

<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">gitchat_git_shortcode</span><span class="hljs-params">( $atts , $content = null )</span> </span>{
    $atts = shortcode_atts(
        <span class="hljs-keyword">array</span>(
            <span class="hljs-string">'id'</span> => <span class="hljs-string">'1'</span>,
            <span class="hljs-string">'title'</span> => <span class="hljs-string">'hahaha'</span>,
        ),
        $atts,
        <span class="hljs-string">'git'</span>
    );
}

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

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

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

<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">gitchat_git_shortcode</span><span class="hljs-params">( $atts , $content = null )</span> </span>{
    $atts = shortcode_atts(
        <span class="hljs-keyword">array</span>(
            <span class="hljs-string">'id'</span> => <span class="hljs-string">'1'</span>,
            <span class="hljs-string">'title'</span> => <span class="hljs-string">'hahaha'</span>,
        ),
        $atts,
        <span class="hljs-string">'git'</span>
    );
    <span class="hljs-keyword">return</span>  $atts[<span class="hljs-string">'id'</span>].<span class="hljs-string">"__"</span>.$atts[<span class="hljs-string">'title'</span>].<span class="hljs-string">"---"</span>.$content;
}

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

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

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

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

编辑器增强

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

QuickTag

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

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

在插件中加入如下代码:

<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">gitchat_git_qt</span><span class="hljs-params">()</span> </span>{
}
add_action( <span class="hljs-string">'admin_print_footer_scripts'</span>, <span class="hljs-string">'gitchat_git_qt'</span> );

这样就在 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 ,在其中加入如下代码:

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

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

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

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

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

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

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

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

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

请单击这里下载本课插件

阅读原文


本文收藏来自互联网,用于学习研究,著作权归原作者所有,如有侵权请联系删除

markdown @tsingchan

部分引用格式为收藏注解,比如本句就是注解,非作者原文。