چگونه دکمه‌های دلخواه به ویرایشگر متن وردپرس اضافه کنیم؟

[omidrayaneh]

در وردپرس از ویرایشگر متن TinyMCE استفاده می‌شود. این ویرایشگر به خاطر قابلیت‌های فراوانی که دارد و این امکان که کاربر می‌تواند به وسیله‌ی افزونه‌ها بر قابلیت‌های آن بیفزاید، بهترین ویرایشگر WYSIWYG به حساب می‌آید. ویرایشگر WYSIWYG ویرایشگری است که در آن کاربر مثل نرم‌افزار ورد متن مورد نظر را می‌نویسد و به وسیله‌ی گزینه‌های گرافیکی شکل و حالت قسمت‌های مختلف متن را تغییر می‌دهد. سپس ویرایشگر این متن را به کد HTML تبدیل می‌کند. در وردپرس TinyMCE کمی تغییر داده شده و برخی گزینه‌های آن به این خاطر که خیلی استفاده ندارند و در عین حال محیط کار را شلوغ و کاربر را سردرگم می‌کنند، مخفی هستند. برای نمونه دکمه‌های SuperScript (توان)، SubScript (اندیس)، و خط افقی از این جمله هستند. نمایان کردن این دکمه‌ها کار سختی نیست ولی اگر کاربر دکمه‌ی جدیدی بخواهد که کارایی خاصی داشته باشد چه باید بکند؟ در این مقاله می‌خواهیم ببینیم چگونه می‌توانیم این کار را انجام دهیم.
در این مقاله دو دکمه به نام‌های Dropcap و Recent Posts ایجاد می‌کنیم. دکمه‌ی Dropcap یک عمل زیبانویسی در زبان انگلیسی انجام می‌دهد. بدین‌صورت که حرف اول پاراگراف را از متن جدا می‌کند و به صورت بزرگ قبل از پاراگراف قرار می‌دهد. دکمه‌ی Recent Posts نیز نوشته‌های جدید نویسنده را در آخر هر پست لیست می‌کند.
برای اینکه فایل‌ها با هم قاطی نشوند یک پوشه به هر نامی که می‌خواهیم درون پوشه‌ی پوسته ایجاد می‌کنیم. مثلاً ما در اینجا نام wptuts-editor-buttons را انتخاب می‌کنیم. سپس درون آن پوشه یک فایل پی اچ پی (مثلاً wptuts.php) و یک فایل جاوا اسکریپت (مثلاً wptuts-plugin.js) ایجاد می‌کنیم. حال فایل functions.php که درون پوشه‌ی پوسته قرار دارد را باز می‌کنیم و در ابتدای آن به وسیله‌ی require فایل پی اچ پی که ایجاد کردیم را فراخوانی می‌کنیم:
1
require( 'wptuts-editor-buttons/wptuts.php' );
راحت‌ترین راه برای ایجاد حالت Dropcap تغییر در کد CSS حرف اول پاراگراف است. بدین صورت که یک کلاس با نام dropcap تعریف کرده و با نسبت دادن آن به حرف مورد نظر اندازه‌ی آن را بزرگ می‌کنیم و در سمت چپ پاراگراف قرار می‌دهیم. برای این کار این کد را در فایل style.css مربوط به پوسته کپی کنید:
1
2
3
4
5
6
7
/* Add this code in style.css */
.dropcap {
float: left;
font-size: 80px;
padding-right: 7px;
line-height: 72px;
}
برای ایجاد لیست آخرین نوشته‌ها از یک shortcode و تابعی به شرح زیر استفاده می‌کنیم. این کد را درون فایل پی اچ پی که ساختید (wptuts.php) کپی کنید:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
add_shortcode( 'recent-posts', 'wptuts_recent_posts' );
function wptuts_recent_posts( $atts ) {
extract( shortcode_atts( array(
'numbers' => '5',
), $atts ) );
$rposts = new WP_Query( array( 'posts_per_page' => $numbers, 'orderby' => 'date' ) );
if ( $rposts->have_posts() ) {
$html = '<h3>Recent Posts</h3><ul class="recent-posts">';
while( $rposts->have_posts() ) {
$rposts->the_post();
$html .= sprintf(
'<li><a href="%s" title="%s">%s</a></li>',
get_permalink($rposts->post->ID),
get_the_title(),
get_the_title()
);
}
$html .= '</ul>';
}
wp_reset_query();
return $html;
}
1

این کد بدین صورت نوشته شده است که با کلیک کاربر بر روی دکمه‌ی مورد نظر یک پنجره باز می‌شود که کاربر باید در آن تعداد آخرین نوشته‌هایی که می‌خواهد لیست شوند را وارد کند. اگر مثلاً کاربر عدد ۷ را وارد کند، shortcode مربوطه بدین‌صورت خواهد شد:
1
[recent-posts numbers="7"/]
ثبت کردن یک افزونه‌ی جدید برای TinyMCE در وردپرس اگر تصور کنیم هم‌اکنون یک افزونه‌ی جدید برای TinyMCE داریم و می‌خواهیم آن را در وردپرس ثبت کنیم از این کد استفاده می‌کنیم:
1
2
3
4
5
6
7
8
9
10
11
12
13
add_action( 'init', 'wptuts_buttons' );
function wptuts_buttons() {
add_filter( "mce_external_plugins", "wptuts_add_buttons" );
add_filter( 'mce_buttons', 'wptuts_register_buttons' );
}
function wptuts_add_buttons( $plugin_array ) {
$plugin_array['wptuts'] = get_template_directory_uri() . '/wptuts-editor-buttons/wptuts-plugin.js';
return $plugin_array;
}
function wptuts_register_buttons( $buttons ) {
array_push( $buttons, 'dropcap', 'showrecent' ); // dropcap', 'recentposts
return $buttons;
}
هوک mce_external_plugins بسیار مهم است به این دلیل که افزونه را به TinyMCE وارد می‌کند. علاوه بر این احتیاج داریم که یک نشانه (ID) برای افزونه (wptuts) و آدرس دقیق فایل جاوا اسکریپت (wptuts-plugin.js) را وارد کنیم. هوک mce_buttons به TinyMCE‌ می‌گوید از چه دکمه‌هایی برای افزونه استفاده بکند. Dropcap و showrecent نیز نشانه‌ی این دکمه‌ها هستند. این‌ها را باید به خاطر بسپاریم زیرا بعداً از آن‌ها استفاده خواهیم کرد. راه‌اندازی افزونه‌ی TinyMCE به نظر من بهترین راه برای دانستن چگونگی گسترش یک قابلیت بر روی یک پلتفرم استفاده از راهنمای آن است. TinyMCE نیز راهنمای wiki دارد که به ما نشان می‌دهد چگونه برای TinyMCE افزونه بسازیم. در راهنما این‌گونه ذکر شده که برای ایجاد یک افزونه باید از این کد استفاده کنیم:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
(function() {
tinymce.create('tinymce.plugins.Wptuts', {
/**
* Initializes the plugin, this will be executed after the plugin has been created.
* This call is done before the editor instance has finished it's initialization so use the onInit event
* of the editor instance to intercept that event.
*
* @param {tinymce.Editor} ed Editor instance that the plugin is initialized in.
* @param {string} url Absolute URL to where the plugin is located.
*/
init : function(ed, url) {

},

/**
* Creates control instances based in the incomming name. This method is normally not
* needed since the addButton method of the tinymce.Editor class is a more easy way of adding buttons
* but you sometimes need to create more complex controls like listboxes, split buttons etc then this
* method can be used to create those.
*
* @param {String} n Name of the control to create.
* @param {tinymce.ControlManager} cm Control manager to use inorder to create new control.
* @return {tinymce.ui.Control} New control instance or null if no control was created.
*/
createControl : function(n, cm) {
return null;
},

/**
* Returns information about the plugin as a name/value array.
* The current keys are longname, author, authorurl, infourl and version.
*
* @return {Object} Name/value array containing information about the plugin.
*/
getInfo : function() {
return {
longname : 'Wptuts Buttons',
author : 'Lee',
authorurl : 'http://wp.tutsplus.com/author/leepham',
infourl : 'http://wiki.moxiecode.com/index.php/TinyMCE:Plugins/example',
version : "0.1"
};
}
});

// Register plugin
tinymce.PluginManager.add( 'wptuts', tinymce.plugins.Wptuts );
})();
این کد را باید به فایل wptuts-plugin.js اضافه کنید. کدهای راهنما (comment) را به این دلیل حذف نکردیم که متوجه شوید چگونه کار می‌کند. اگر فکر می‌کنید احتیاجی به آن‌ها ندارید می‌توانید آن‌ها را حذف کنید. ما در این کد دو کار اساسی انجام می‌دهیم: در ابتدا با استفاده از متود create در TinyMCE یک افزونه‌ی جدید ایجاد می‌کنیم. عملکرد افزونه در توابع init و createControl مشخص می‌شوند. اطلاعاتی مثل نام افزونه، نام برنامه نویس و … در تابعی به نام getInfo تشریح شده‌اند. همانطور که می‌بینید اسم افزونه را Wptuts و نشانه‌ی آن را wptuts گذاشته ایم. در قسمت آخر، افزونه‌ی جدید، به ابزار مدیریت افزونه‌های (TinyMCE Plugin Manager) اضافه می‌شود. ایجاد دکمه‌ها در تابع init دکمه‌هایی که قرار است در نوار ابزار TinyMCE گذاشته شوند را ایجاد می‌کنیم.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
(function() {
tinymce.create('tinymce.plugins.Wptuts', {
init : function(ed, url) {
ed.addButton('dropcap', {
title : 'DropCap',
cmd : 'dropcap',
image : url + '/dropcap.jpg'
});

ed.addButton('showrecent', {
title : 'Add recent posts shortcode',
cmd : 'showrecent',
image : url + '/recent.jpg'
});
},
// ... Hidden code
});
// Register plugin
tinymce.PluginManager.add( 'wptuts', tinymce.plugins.Wptuts );
})();
در شیئ ed از متود addButton استفاده کردیم تا به برنامه بگوییم که می‌خواهیم یک دکمه ایجاد کنیم. این متود دو آرگومان دارد:
اولین آرگومان شامل نشانه‌ی دکمه است. می‌بایست از همان نشانه‌ای استفاده کنیم که قبلاً هم استفاده کردیم واگرنه برنامه کار نخواهد کرد.
دومین آرگومان شامل اطلاعات ظاهری و نحوه‌ی کارکرد دکمه می‌شود:
عنوان دکمه
عملکرد دکمه. عملکرد دکمه مهم‌ترین چیزی است که در اینجا می‌نویسید. همانطور که می‌بینید در این قسمت روبروی cmd نوشته شده است: showrecent این نشانه‌ مربوط به دستوراتی است که هر دفعه با اجرای دکمه فراخوانی می‌شود.
تصویر دکمه. در اینجا آدرس تصویر را وارد کرده ایم. پارامتر URL آدرس کامل پوشه‌ای که افزونه در آن قرار دارد را به برنامه وارد می‌کند. در این صورت با گذاشتن تصویر پلاگین در همان پوشه و نوشتن اسم آن بعد از URL می‌توانید به راحتی آن را آدرس دهی کنید.
حال اگر ویرایشگر وردپرس را باز کنیم دکمه‌ها را در آن‌جا می‌بینیم. البته هنوز کار نمی‌کنند.

اضافه کردن دستورات دکمه‌ها
تا کنون نشانه‌ی دستوراتی که قرار است هر دکمه فراخوانی کند را به TinyMCE داده‌ایم ولی مشخص نکرده‌ایم که این دستورات چه هستند. درون تابع init کارایی دکمه‌ها را مشخص خواهیم کرد:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
(function() {
tinymce.create('tinymce.plugins.Wptuts', {
init : function(ed, url) {
ed.addButton('dropcap', {
title : 'DropCap',
cmd : 'dropcap',
image : url + '/dropcap.jpg'
});

ed.addButton('showrecent', {
title : 'Add recent posts shortcode',
cmd : 'showrecent',
image : url + '/recent.jpg'
});

ed.addCommand('dropcap', function() {
var selected_text = ed.selection.getContent();
var return_text = '';
return_text = '<span class="dropcap">' + selected_text + '</span>';
ed.execCommand('mceInsertContent', 0, return_text);
});

ed.addCommand('showrecent', function() {
var number = prompt("How many posts you want to show ? "),
shortcode;
if (number !== null) {
number = parseInt(number);
if (number > 0 && number <= 20) {
shortcode = '[recent-post number="' + number + '"/]';
ed.execCommand('mceInsertContent', 0, shortcode);
}
else {
alert("The number value is invalid. It should be from 0 to 20.");
}
}
});
},
// ... Hidden code
});
// Register plugin
tinymce.PluginManager.add( 'wptuts', tinymce.plugins.Wptuts );
})();
برای اضافه کردن یک دستور از متود ed.addCommand استفاده کرده‌ایم. در اینجا احتیاج دارید نشانه‌ی دستور و تابع callback که توسط متود ed.execCommand فراخوانی می‌شود را وارد کنید. توجه داشته باشید که شیئ ed بیانگر tinyMCE.activeEditor است. بیایید نگاهی به توابع callback بیندازیم:
در دستور dropcap می‌خواهیم با انتخاب یک حرف توسط کاربر و کلیک بر روی دکمه‌ی مربوطه آن حرف تبدیل به حالت dropcap بشود. یعنی از پاراگراف بیرون بیاید و با اندازه‌ی بزرگ در سمت چپ آن قرار گیرد. برای گرفتن حرف از متود ed.selection.getContent استفاده می‌شود. حال که حرف مورد نظر را وارد برنامه کرده‌ایم آن را درون یک المان span قرار می‌دهیم تا حالتی که در فایل style.css برای dropcap مشخص کردیم بر آن اعمال شود. حال می‌خواهیم نتیجه‌ی کار را به بخش HTML ویرایشگر باز گردانیم. برای این کار از یکی از دستورات TinyMCE به نام mceInsertContent استفاده می‌کنیم. آنچه که قرار است به ویرایشگر باز گردد در سومین آرگومان mceInsertContent نوشته می‌شود.
فرایند مشابهی برای دستور showrecent انجام می‌شود. به جز اینکه در اینجا احتیاجی نیست که کاربر حرفی را انتخاب کند بلکه تنها از او سؤال می‌شود که چه تعداد از نوشته‌های جدید را می‌خواهد در آن مکان لیست کند.
ایجاد CSS برای ویرایشگر (اختیاری)
تا اینجا با انجام هر کدام از فرایندها نتیجه‌ی کامل در سایت نمایش داده می‌شود و نه در ویرایشگر. برای اینکه مثلاً نتیجه‌ی Dropcap را درون ویرایشگر نیز ببینیم می‌توانیم کد CSS که برای آن درون فایل style.css نوشتیم را درون فایل editor-style.css نیز کپی کنیم. برای دکمه‌ی دیگر کار به راحتی Dropcap نیست به این خاطر که المان HTML ندارد. البته می‌توانیم به shortcode یک المان HTML نسبت بدهیم و سپس به آن المان شکل و حالت CSS اعمال کنیم ولی به سادگی آنچه برای Dropcap‌ انجام دادیم نخواهد بود.
نتایج:
نتیجه‌ی Dropcap در ویرایشگر بدین صورت است:

و درون مرورگر:

دکمه‌ی Recent Posts نیز به خوبی کار می‌کند.

در این آموزش ما از یک ساز و کار ساده برای ایجاد دکمه‌های دلخواه استفاده کردیم. ممکن است توجه کرده باشید که برای پرسش تعداد نوشته‌های جدید از کاربر از prompt‌ استفاده کردیم که تنها یک ورودی دارد. این سؤال پیش می‌آید که اگر بخواهیم چند چیز مختلف از کاربر سؤال کنیم آیا باید چند بار این کار را تکرار کنیم یا می‌توانیم یک پنجره با چند قسمت برای وارد کردن اطلاعات به کاربر نشان دهیم. اگر می‌خواهید بدانید با آموزش‌های آینده‌ی ما همراه باشید.
اگر هم میخواهید نمونه فایل انجام شده را از اینجا دانلود کنید