Tutorial: Bina Slideshow Plugin Untuk Wordpress 3.0.x

Atas permintaan saudara lazaac, tutorial ini sama seperti tutorial saya sebelum ini, Tutorial: Bina Module Slideshow untuk Joomla! 1.5.x cuma kali ini saya jadikan ia plugin untuk Wordpress pula. Ini merupakan percubaan kali pertama saya membina plugin untuk Wordpress, jadi sebarang komen dan feedback amatlah saya hargai. Sama seperti tutorial membina module slideshow untuk Joomla! yang lepas, plugin ini juga menggunakan jQuery dan Coin Slider.

Keperluan

Wordpress 3.0.x (sila gunakan yang terkini)

Code Editor (saya guna PSPad, percuma)

Coin Slider for jQuery

Langkah 1

Perbezaan antara WP dan Joomla! ialah cara kita install extension (plugin untuk WP, component, module, plugin untuk Joomla!). Pada Joomla!, kita perlu gunakan Joomla! Extension Installer bagi memastikan ianya dipasang dengan betul. Berbeza dengan WP yang mana kita hanya perlu create folder di dalam wp-content/plugins pada WP kita sahaja. Cukup mudah.

Sekarang, create satu folder di dalam wp-content/plugins, dan berikan nama myslideshow. Kemudian, create file myslideshow.php di dalam folder myslideshow tadi. Di dalam fail coin-slider.zip yang anda download terdapat 3 files. Copy file berikut sahaja

1. coin-slider-styles.css ke dalam folder myslideshow
2. coin-slider.min.js ke dalam folder myslideshow

* Rujuk gambar di sebelah.

** Kita tidak perlukan file jQuery untuk Wordpress kerana Wordpress sudah sediakan file ini, kita hanya perlu load menggunakan kod wp_enqueue_script('jquery') sahaja.

Langkah 2

Buka file myslideshow.php, dan kita akan mulakan dengan kod kod PHP plugin ini.

[code lang="php"]
<?php
/*
Plugin Name: MySlideshow
Plugin URI: http://www.syahzul.com
Description: Slideshow plugin using jQuery & Coin Slider
Version: 1.0
Author: Syahril Zulkefli
Author URI: http://www.syahzul.com
License: GPL2
*/[/code]

Kod ini perlu ada bagi memastikan WP dapat detect plugin kita. Anda boleh tukar maklumat yang ada, tetapi pastikan keyword yang diperlukan tetap ada. Sila rujuk page ini untuk maklumat lanjut: Writing a Plugin.

[code lang="php"]
if ( is_admin() )
{
add_action( 'admin_menu', 'myslideshow_plugin_menu' );
add_action( 'admin_init', 'myslideshow_register_settings' );
}
else
{
add_action( 'wp_head' , 'myslideshow_scripts');
}
[/code]

Pada bahagian ini, kita akan check jika kita berada di bahagian backend, kita akan add satu link pada menu Settings untuk plugin kita dan seterusnya register settings untuk slideshow kita di dalam database. Jika bukan di bahagian backend, kita akan masukkan kod kod javascript di dalam wp_head.

[code lang="php"]
function myslideshow_register_settings()
{
register_setting( 'myslideshow-group', 'mys_slider_image_path' );
register_setting( 'myslideshow-group', 'mys_slider_effect' );
register_setting( 'myslideshow-group', 'mys_slider_width' );
register_setting( 'myslideshow-group', 'mys_slider_height' );
register_setting( 'myslideshow-group', 'mys_slider_spw' );
register_setting( 'myslideshow-group', 'mys_slider_sph' );
register_setting( 'myslideshow-group', 'mys_slider_image_delay' );
register_setting( 'myslideshow-group', 'mys_slider_square_delay' );
register_setting( 'myslideshow-group', 'mys_slider_navigation' );
register_setting( 'myslideshow-group', 'mys_slider_navigation_opacity' );
register_setting( 'myslideshow-group', 'mys_slider_pause_mouseover' );
}
[/code]

Kita akan gunakan function ini untuk add option di dalam database WP kita. Semua value di atas itu akan kita gunakan ketika kita nak paparkan slideshow dan juga pada option page kita.

[code lang="php"]
function myslideshow_plugin_menu()
{
add_options_page('MySlideshow Settings', 'MySlideshow', 'manage_options', 'myslideshow', 'myslideshow_plugin_options');
}
[/code]

Function inilah yang akan create satu link untuk option page plugin kita.

[code lang="php"]
function myslideshow_plugin_options()
{
if (!current_user_can('manage_options')) {
wp_die( __('You do not have sufficient permissions to access this page.') );
}
?>
<div class="wrap">
<div id="icon-options-general" class="icon32"><br /></div>
<h2><?php echo __('MySlideshow Settings'); ?></h2>
<div id="message" class="updated fade" style="display: none"></div>

<form method="post" action="options.php">

<table class="form-table">
<tr valign="top">
<th scope="row">Image Path</th>
<td>
<input type="text" name="mys_slider_image_path" class="regular-text" value="<?php echo get_option('mys_slider_image_path'); ?>" />
<span class="description"><?php _e('Specify your image path here. Must be inside your <strong>wp-content</strong> folder.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Slider Effect</th>
<td>
<select name="mys_slider_effect" style="width: 120px;">
<option value="random"<?php echo get_option('mys_slider_effect') == 'random' ? ' selected="selected"' : ''; ?>><?php _e('Random'); ?></option>
<option value="swirl"<?php echo get_option('mys_slider_effect') == 'swirl' ? ' selected="selected"' : ''; ?>><?php _e('Swirl'); ?></option>
<option value="rain"<?php echo get_option('mys_slider_effect') == 'rain' ? ' selected="selected"' : ''; ?>><?php _e('Rain'); ?></option>
<option value="straight"<?php echo get_option('mys_slider_effect') == 'straight' ? ' selected="selected"' : ''; ?>><?php _e('Straight'); ?></option>
</select>
<span class="description"><?php _e('Choose your preferred slide effect.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Slider Width</th>
<td>
<input type="text" name="mys_slider_width" class="regular-text" style="width: 120px;" value="<?php echo get_option('mys_slider_width'); ?>" />
<span class="description"><?php _e('Enter your slider width (in pixels) here. Numbers only please.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Slider Height</th>
<td>
<input type="text" name="mys_slider_height" class="regular-text" style="width: 120px;" value="<?php echo get_option('mys_slider_height'); ?>" />
<span class="description"><?php _e('Enter your slider height (in pixels) here. Numbers only please.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Square per Width</th>
<td>
<input type="text" name="mys_slider_spw" class="regular-text" style="width: 120px;" value="<?php echo get_option('mys_slider_spw'); ?>" />
<span class="description"><?php _e('Be careful with Square per width because large numbers can cause transitions problems.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Square per Height</th>
<td>
<input type="text" name="mys_slider_sph" class="regular-text" style="width: 120px;" value="<?php echo get_option('mys_slider_sph'); ?>" />
<span class="description"><?php _e('Be careful with Square per height because large numbers can cause transitions problems.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Delay Between Images</th>
<td>
<input type="text" name="mys_slider_image_delay" class="regular-text" style="width: 120px;" value="<?php echo get_option('mys_slider_image_delay'); ?>" />
<span class="description"><?php _e('Enter delay between images, in miliseconds.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Delay Between Squares</th>
<td>
<input type="text" name="mys_slider_square_delay" class="regular-text" style="width: 120px;" value="<?php echo get_option('mys_slider_square_delay'); ?>" />
<span class="description"><?php _e('Enter delay between squares, in miliseconds.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Show navigation?</th>
<td>
<select name="mys_slider_navigation" style="width: 80px;">
<option value="1"<?php echo get_option('mys_slider_navigation') === 1 ? 'selected="selected"' : ''; ?>><?php _e('Yes'); ?></option>
<option value="0"<?php echo get_option('mys_slider_navigation') === 0 ? 'selected="selected"' : ''; ?>><?php _e('No'); ?></option>
</select>
<span class="description"><?php _e('If you choose Yes, slide navigation, including Next and Prev button, will be shown.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Navigation opacity</th>
<td>
<select name="mys_slider_navigation_opacity" style="width: 80px;">
<option value="0.1"<?php echo get_option('mys_slider_navigation_opacity') == '0.1' ? ' selected="selected"' : ''; ?>>0.1</option>
<option value="0.2"<?php echo get_option('mys_slider_navigation_opacity') == '0.2' ? ' selected="selected"' : ''; ?>>0.2</option>
<option value="0.3"<?php echo get_option('mys_slider_navigation_opacity') == '0.3' ? ' selected="selected"' : ''; ?>>0.3</option>
<option value="0.4"<?php echo get_option('mys_slider_navigation_opacity') == '0.4' ? ' selected="selected"' : ''; ?>>0.4</option>
<option value="0.5"<?php echo get_option('mys_slider_navigation_opacity') == '0.5' ? ' selected="selected"' : ''; ?>>0.5</option>
<option value="0.6"<?php echo get_option('mys_slider_navigation_opacity') == '0.6' ? ' selected="selected"' : ''; ?>>0.6</option>
<option value="0.7"<?php echo get_option('mys_slider_navigation_opacity') == '0.7' ? ' selected="selected"' : ''; ?>>0.7</option>
<option value="0.8"<?php echo get_option('mys_slider_navigation_opacity') == '0.8' ? ' selected="selected"' : ''; ?>>0.8</option>
<option value="0.9"<?php echo get_option('mys_slider_navigation_opacity') == '0.9' ? ' selected="selected"' : ''; ?>>0.9</option>
<option value="1.0"<?php echo get_option('mys_slider_navigation_opacity') == '1.0' ? ' selected="selected"' : ''; ?>>1.0</option>
</select>
<span class="description"><?php _e('Enter opacity value for navigation.'); ?></span>
</td>
</tr>

<tr valign="top">
<th scope="row">Pause on mouse over?</th>
<td>
<select name="mys_slider_pause_mouseover" style="width: 80px;">
<option value="1"<?php echo get_option('mys_slider_pause_mouseover') === 1 ? 'selected="selected"' : ''; ?>><?php _e('Yes'); ?></option>
<option value="0"<?php echo get_option('mys_slider_pause_mouseover') === 0 ? 'selected="selected"' : ''; ?>><?php _e('No'); ?></option>
</select>
<span class="description"><?php _e('If you choose Yes, slideshow will be stop when user hovering the mouse over the image.'); ?></span>
</td>
</tr>
</table>

<?php settings_fields( 'myslideshow-group' ); ?>

<p class="submit">
<input type="submit" value="Save Changes" class="button-primary" name="Submit">
</p>
</form>
</div>
<?php
}
[/code]

Dan ini merupakan kod untuk option page pada backend WP kita. Lihat contoh option page pada gambar di bawah ini.

[code lang="php"]
function myslideshow_init()
{
/* Register our script. */
wp_register_script('myslideshow_script', WP_PLUGIN_URL . '/myslideshow/coin-slider.min.js');

/* Register our css. */
wp_register_style('myslideshow_style', WP_PLUGIN_URL . '/myslideshow/coin-slider-styles.css');

wp_enqueue_script('jquery');
wp_enqueue_script('myslideshow_script', WP_PLUGIN_URL . '/myslideshow/coin-slider.min.js');
wp_enqueue_style('myslideshow_style', WP_PLUGIN_URL . '/myslideshow/coin-slider-styles.css');
}
add_action('init', 'myslideshow_init');
[/code]

Kod ini kita perlukan untuk load file Javascript dan CSS menggunakan function wp_enqueue_script dan wp_enqueue_style yang disediakan oleh WP.

[code lang="php"]
function myslideshow_scripts()
{
$html = '<script type="text/javascript">' . "\n";
$html .= 'jQuery(document).ready( function() {' . "\n";
$html .= ' jQuery("#myslideshow").coinslider({' . "\n";
$html .= ' width: ' . get_option('mys_slider_width') . ", ";
$html .= ' height: ' . get_option('mys_slider_height') . ", ";
$html .= ' spw: ' . get_option('mys_slider_spw') . ", ";
$html .= ' sph: ' . get_option('mys_slider_sph') . ", ";
$html .= ' delay: ' . get_option('mys_slider_image_delay') . ", ";
$html .= ' sDelay: ' . get_option('mys_slider_square_delay') . ", ";
$html .= ' opacity: ' . get_option('mys_slider_navigation_opacity') . ", ";
$html .= ' effect: \'' . get_option('mys_slider_effect') . '\', '; // random, swirl, rain, straight
$html .= ' navigation: ' . (get_option('mys_slider_navigation') == 1 ? 'true' : 'false') . ', ';
$html .= ' links: false, ';
$html .= ' hoverPause: ' . (get_option('mys_slider_pause_mouseover') == 1 ? 'true' : 'false') . "\n";
$html .= ' });' . "\n";
$html .= '});' . "\n";
$html .= '</script>';
echo $html;
}
[/code]

Function yang akan dapatkan option value kita dari database dan kemudian generate kod kod javascript untuk slideshow nanti.

[code lang="php"]
function myslideshow_get_images()
{
if ( !defined('DS') )
define( 'DS', DIRECTORY_SEPARATOR );

// get path from parameter
$image_path = get_option('mys_slider_image_path');

// add root into our path
$abspath = WP_CONTENT_DIR . DS . $image_path . DS;

// convert '/' to proper directory separator, just in case
$abspath = str_replace( '/', DS, $abspath );

// Run through the source folder
$folder = opendir( $abspath );

$images = array();

// loop the source
while( $file = readdir( $folder ) )
{
// make sure the item is not a folder
if( !is_dir( $file ) )
{
$parts = explode(".", $file); // pull apart the name and dissect by period

if (is_array($parts) && count($parts) > 1)
{ // does the dissected array have more than one part

$extension = end($parts); // set to we can see last file extension

if ($extension == 'jpg' OR $extension == 'JPG' OR $extension == 'png' OR $extension == 'PNG' OR $extension == 'gif' OR $extension == 'GIF')
{
$images[] = WP_CONTENT_URL . '/' . $image_path . '/' . $file;
}
}
}
}

return $images;
}
[/code]

Seterusnya, function ini akan dapatkan senarai image untuk slideshow dan add dalam array $images. Dalam function ini, kita akan check file extensions, dan hanya dapatkan file .jpg, .png dan .gif sahaja.

[code lang="php"]
function myslideshow_html()
{
?>
<!-- MySlideshow -->
<div id="myslideshow">
<?php
// get images to show
$images = myslideshow_get_images();

for ( $x = 0; $x < count($images); $x++ ) {
?>
<img src="<?php echo $images[$x]; ?>" />
<?php
}
?>
</div>
<!-- MySlideshow -->
<?php
}
[/code]

Dan ini merupakan function yang akan generate output untuk slideshow kita. Kita akan panggil function ini dari file theme kita nanti.

Langkah 3

Create satu folder di dalam wp-content dan namakan myslideshow. Kemudian, save 4 gambar berikut di dalam folder tersebut.

* Nota: Klik pada gambar untuk view fullsize.

Langkah 4

Masukkan kod ini myslideshow_html() di dalam file theme anda. Untuk contoh ini, saya gunakan theme twentyten, saya masukkan kod di bawah ini di dalam file index.php.

Langkah 5

Sekarang anda perlu configure plugin ini terlebih dahulu, bagi membolehkan WP save settings untuk slideshow ini.

Penerangan Parameters

• Image Path
  Lokasi imej yang kita nak gunakan. Pastikan ianya berada di dalam folder wp-content. Untuk tutorial ini, sila masukkan myslideshow.
• Slider effect
  Ada 3 effects yang boleh kita gunakan; Swirl, Rain, Straight. Dan boleh combine semua, gunakan Random.
• Slider width
  Lebar slideshow anda. Pastikan lebar imej juga sama bagi mendapatkan hasil yang memuaskan hati anda.
• Slider height
  Tinggi slideshow anda. Pastikan tinggi imej juga sama bagi mendapatkan hasil yang memuaskan hati anda.
• Square per width
  Jumlah kotak berdasarkan lebar, sila tengok demo untuk fahamkan.
• Square per height
  Jumlah kotak berdasarkan tinggi, sila tengok demo untuk fahamkan.
  
• Delay between images
  Had masa antara setiap satu image. Dalam format miliseconds; 1000 miliseconds sama dengan 1 saat.
• Delay between squares
  Had masa antara setiap satu kotak. Dalam format miliseconds; 1000 miliseconds sama dengan 1 saat.
• Show navigation
  Perlu tunjukkan button Next dan Prev?
• Navigation opacity
  Opacity untuk button Next dan Prev.
• Pause on mouse over
  Slideshow berhenti bila user letak mouse atas slideshow tu.

Demo

http://www.syahzul.com/demo/wordpress/

Download

Kalau rasa buat tak menjadi tu, sila download dari sini, free. Boleh guna pada mana mana website jika sudi.

http://bit.ly/cAQLwx

Penutup

Walaupun sebenarnya ini bukan macam tutorial sangat, tapi kalau rajin kaji kod kod di atas tadi untuk belajar konsep plugin untuk Wordpress. Dan ini merupakan kali pertama saya cuba bina pluginuntuk Wordpress, jadi komen dan feedback amatlah dihargai.

Nota lagi:

Gambar tu untuk tujuan pembelajaran sahaja, sila jangan gunakan untuk tujuan lain.