() translation by (you can also view the original English article)
Wann immer das WordPress-Team eine neue Version herausbringt stellen sie einige neue Features vor. Diese richten sich jedoch nicht immer nur an die Endbenutzer sondern oft auch an Entwickler. Denn WordPress enthält eine Menge Tools welche die Entwicklung von fantastischen Themes und Plugins erleichtern.
Eine der neusten APIs für WordPress-Entwickler ist der frisch vorgestellte Color Picker; dieses Feature erlaubt es, einfache Text-Eingabefelder durch ein hübsches und benutzerfreundliches Farbauswahl-Tool zu ersetzen.
In dieser Anleitung werde ich Euch zeigen, wie Ihr den Color Picker in eurem WordPress-Projekt einsetzen könnt. Los geht’s!
Warum den Color Picker verwenden?
Es gibt diverse Gründe weshalb WordPress-Entwickler den Color Picker zur Implementierung einer Farbauswahl verwenden sollten:
Für Benutzer
- Er bietet einen schnellen und einfachen Weg eine Farbe auszuwählen.
- Benutzer müssen sich keine Gedanken über das Format der Farbangabe (Hexadezimal, RGB, usw.) machen.
- Einfach gesagt bietet er eine deutlich verbesserte User Experience.
Für Entwickler
- Eure Dashboard-Seiten sind an das WordPress-Interface angepasst.
- Er vereinfacht das Validieren des Inhaltes des Farb-Eingabefeldes.
- Das Resultat ist ein professionelles Produkt welches native Eingabeelemente einsetzt.
Nachdem wir einige der Hauptaspekte des WordPress Color Pickers durchgegangen sind, werden wir uns ansehen, wie wir ihn in unseren Plugins oder Themes einsetzen können.
Den Color Picker einbinden
Bevor es losgeht, muss ich noch anmerken, das die Color Picker API mit WordPress 3.5 vorgestellt wurde. Um also diesem Tutorial folgen zu können, stellt bitte sicher das Ihr Version 3.5 oder höher verwendet.
Um den Color Picker einzusetzen, müsste Ihr nur eine jQuery-Datei und ein Stylesheet einbinden. Die folgenden Code-Zeilen zeigen Euch wie das geht.
1 |
add_action( 'admin_enqueue_scripts', 'wptuts_add_color_picker' ); |
2 |
function wptuts_add_color_picker( $hook ) { |
3 |
|
4 |
if( is_admin() ) { |
5 |
|
6 |
// Add the color picker css file
|
7 |
wp_enqueue_style( 'wp-color-picker' ); |
8 |
|
9 |
// Include our custom jQuery file with WordPress Color Picker dependency
|
10 |
wp_enqueue_script( 'custom-script-handle', plugins_url( 'custom-script.js', __FILE__ ), array( 'wp-color-picker' ), false, true ); |
11 |
}
|
12 |
}
|
Beachtet bitte, das wir für die custom-script.js-Datei die wp-color-picker-Abhängigkeit angegeben haben. In unserer jQuery-Datei können wir nun den Color Picker zu unseren Farb-Eingabefeldern hinzufügen.
1 |
(function( $ ) { |
2 |
|
3 |
// Add Color Picker to all inputs that have 'color-field' class
|
4 |
$(function() { |
5 |
$('.color-field').wpColorPicker(); |
6 |
});
|
7 |
|
8 |
})( jQuery ); |
Erstellen eines Plugins mit dem WordPress Color Picker
Jetzt ist es an der Zeit zu demonstrieren, wie der Color Picker in einem realen Plugin eingesetzt wird.
Folgendes werden wir uns ansehen:
- Anlegen einer Einstellungsseite zur Simulation von Theme-Optionen.
- Hinzufügen von Eingabefeldern welche den Color Picker verwenden.
- Speichern und validieren der Benutzereingaben.
Schritt 1
Sobald Ihr Euer Plugin im wp-content/plugins-Ordner angelegt habt kann es richtig losgehen. Das folgende Bild zeigt Euch, wie ich das Plugin für diese Anleitung strukturiert habe.
Schritt 2
Fügt den Kommentar mit den Plugin-Infos innerhalb der color-picker-plugin.php-Datei ein und erstellt eine neue PHP-Klasse CPA_Theme_Options. Der untenstehende Code zeigt alle Klassenmethoden welche wir benötigen werden.
1 |
/*
|
2 |
Plugin Name: Color Picker API
|
3 |
Plugin URI: https://code.tutsplus.com
|
4 |
Description: Demo about the new Color Picker API
|
5 |
Version: 1.0
|
6 |
Author: code.tutsplus.com
|
7 |
Author URI: http://code.tutsplus.com
|
8 |
*/
|
9 |
|
10 |
/**
|
11 |
* Main Class - CPA stands for Color Picker API
|
12 |
*/
|
13 |
class CPA_Theme_Options { |
14 |
|
15 |
/*--------------------------------------------*
|
16 |
* Attributes
|
17 |
*--------------------------------------------*/
|
18 |
|
19 |
/** Refers to a single instance of this class. */
|
20 |
private static $instance = null; |
21 |
|
22 |
/* Saved options */
|
23 |
public $options; |
24 |
|
25 |
/*--------------------------------------------*
|
26 |
* Constructor
|
27 |
*--------------------------------------------*/
|
28 |
|
29 |
/**
|
30 |
* Creates or returns an instance of this class.
|
31 |
*
|
32 |
* @return CPA_Theme_Options A single instance of this class.
|
33 |
*/
|
34 |
public static function get_instance() { |
35 |
|
36 |
if ( null == self::$instance ) { |
37 |
self::$instance = new self; |
38 |
}
|
39 |
|
40 |
return self::$instance; |
41 |
|
42 |
} // end get_instance; |
43 |
|
44 |
/**
|
45 |
* Initializes the plugin by setting localization, filters, and administration functions.
|
46 |
*/
|
47 |
private function __construct() { } |
48 |
|
49 |
/*--------------------------------------------*
|
50 |
* Functions
|
51 |
*--------------------------------------------*/
|
52 |
|
53 |
/**
|
54 |
* Function that will add the options page under Setting Menu.
|
55 |
*/
|
56 |
public function add_page() { } |
57 |
|
58 |
/**
|
59 |
* Function that will display the options page.
|
60 |
*/
|
61 |
public function display_page() { } |
62 |
|
63 |
/**
|
64 |
* Function that will register admin page options.
|
65 |
*/
|
66 |
public function register_page_options() { } |
67 |
|
68 |
/**
|
69 |
* Function that will add javascript file for Color Piker.
|
70 |
*/
|
71 |
public function enqueue_admin_js() { } |
72 |
|
73 |
/**
|
74 |
* Function that will validate all fields.
|
75 |
*/
|
76 |
public function validate_options( $fields ) { } |
77 |
|
78 |
/**
|
79 |
* Function that will check if value is a valid HEX color.
|
80 |
*/
|
81 |
public function check_color( $value ) { } |
82 |
|
83 |
/**
|
84 |
* Callback function for settings section
|
85 |
*/
|
86 |
public function display_section() { /* Leave blank */ } |
87 |
|
88 |
/**
|
89 |
* Functions that display the fields.
|
90 |
*/
|
91 |
public function title_settings_field() { } |
92 |
|
93 |
public function bg_settings_field( ) { } |
94 |
|
95 |
} // end class |
96 |
|
97 |
CPA_Theme_Options::get_instance(); |
Schritt 3
Als erstes werden wir den Konstruktor der Klasse implementieren. Der folgende Code zeigt, was das Plugin tun wird sobald eine neue Instanz der Klasse erzeugt wird.
Es wird:
- eine neue Einstellungsseite im Einstellungen-Abschnitt des WordPress Admin-Menüs einfügen,
- innerhalb dieser Einstellungsseite ein neues Eingabefeld anlegen,
- die CSS-Styles des Color Pickers einbinden,
- die JavaScript-Datei, welche den Color Picker lädt, einfügen,
- die bereits gespeicherten Einstellungen in das
options-Attribut übernehmen.
1 |
private function __construct() { |
2 |
|
3 |
// Add the page to the admin menu
|
4 |
add_action( 'admin_menu', array( &$this, 'add_page' ) ); |
5 |
|
6 |
// Register page options
|
7 |
add_action( 'admin_init', array( &$this, 'register_page_options') ); |
8 |
|
9 |
// Css rules for Color Picker
|
10 |
wp_enqueue_style( 'wp-color-picker' ); |
11 |
|
12 |
// Register javascript
|
13 |
add_action('admin_enqueue_scripts', array( $this, 'enqueue_admin_js' ) ); |
14 |
|
15 |
// Get registered option
|
16 |
$this->options = get_option( 'cpa_settings_options' ); |
17 |
}
|
Schritt 4
Dieser Schritt zeigt wie wir die Einstellungsseite registrieren und anzeigen.
1 |
/**
|
2 |
* Function that will add the options page under Setting Menu.
|
3 |
*/
|
4 |
public function add_page() { |
5 |
|
6 |
// $page_title, $menu_title, $capability, $menu_slug, $callback_function
|
7 |
add_options_page( 'Theme Options', 'Theme Options', 'manage_options', __FILE__, array( $this, 'display_page' ) ); |
8 |
}
|
9 |
|
10 |
/**
|
11 |
* Function that will display the options page.
|
12 |
*/
|
13 |
public function display_page() { |
14 |
?>
|
15 |
<div class="wrap"> |
16 |
|
17 |
<h2>Theme Options</h2> |
18 |
<form method="post" action="options.php"> |
19 |
<?php
|
20 |
settings_fields(__FILE__); |
21 |
do_settings_sections(__FILE__); |
22 |
submit_button(); |
23 |
?>
|
24 |
</form>
|
25 |
</div> <!-- /wrap --> |
26 |
<?php
|
27 |
}
|
Beachtet das wir, innerhalb der display_page()-Methode, ebenfalls schon den Code eingefügt haben, welcher dafür sorgt das die Formular-Tags, die Eingabefelder und der Speichern-Button angezeigt werden.
Schritt 5
In diesem Schritt werden wir die Methoden zum Registrieren und Anzeigen der zwei Eingabefelder Blog Titel und Hintergrundfarbe implementieren. Beide Eingabefelder platzieren wir in einem Theme-Optionen-Abschnitt.
1 |
/**
|
2 |
* Function that will register admin page options.
|
3 |
*/
|
4 |
public function register_page_options() { |
5 |
|
6 |
// Add Section for option fields
|
7 |
add_settings_section( 'cpa_section', 'Theme Options', array( $this, 'display_section' ), __FILE__ ); // id, title, display cb, page |
8 |
|
9 |
// Add Title Field
|
10 |
add_settings_field( 'cpa_title_field', 'Blog Title', array( $this, 'title_settings_field' ), __FILE__, 'cpa_section' ); // id, title, display cb, page, section |
11 |
|
12 |
// Add Background Color Field
|
13 |
add_settings_field( 'cpa_bg_field', 'Background Color', array( $this, 'bg_settings_field' ), __FILE__, 'cpa_section' ); // id, title, display cb, page, section |
14 |
|
15 |
// Register Settings
|
16 |
register_setting( __FILE__, 'cpa_settings_options', array( $this, 'validate_options' ) ); // option group, option name, sanitize cb |
17 |
}
|
18 |
|
19 |
/**
|
20 |
* Functions that display the fields.
|
21 |
*/
|
22 |
public function title_settings_field() { |
23 |
|
24 |
$val = ( isset( $this->options['title'] ) ) ? $this->options['title'] : ''; |
25 |
echo '<input type="text" name="cpa_settings_options[title]" value="' . $val . '" />'; |
26 |
}
|
27 |
|
28 |
public function bg_settings_field() { |
29 |
|
30 |
$val = ( isset( $this->options['title'] ) ) ? $this->options['background'] : ''; |
31 |
echo '<input type="text" name="cpa_settings_options[background]" value="' . $val . '" class="cpa-color-picker" >'; |
32 |
|
33 |
}
|
Schritt 6
Dieser Schritt legt seinen Fokus auf das Validieren der beiden Eingabefelder, bevor die neuen Werte in der Datenbank gespeichert werden.
1 |
/**
|
2 |
* Function that will validate all fields.
|
3 |
*/
|
4 |
public function validate_options( $fields ) { |
5 |
|
6 |
$valid_fields = array(); |
7 |
|
8 |
// Validate Title Field
|
9 |
$title = trim( $fields['title'] ); |
10 |
$valid_fields['title'] = strip_tags( stripslashes( $title ) ); |
11 |
|
12 |
// Validate Background Color
|
13 |
$background = trim( $fields['background'] ); |
14 |
$background = strip_tags( stripslashes( $background ) ); |
15 |
|
16 |
// Check if is a valid hex color
|
17 |
if( FALSE === $this->check_color( $background ) ) { |
18 |
|
19 |
// Set the error message
|
20 |
add_settings_error( 'cpa_settings_options', 'cpa_bg_error', 'Insert a valid color for Background', 'error' ); // $setting, $code, $message, $type |
21 |
|
22 |
// Get the previous valid value
|
23 |
$valid_fields['background'] = $this->options['background']; |
24 |
|
25 |
} else { |
26 |
|
27 |
$valid_fields['background'] = $background; |
28 |
|
29 |
}
|
30 |
|
31 |
return apply_filters( 'validate_options', $valid_fields, $fields); |
32 |
}
|
33 |
|
34 |
/**
|
35 |
* Function that will check if value is a valid HEX color.
|
36 |
*/
|
37 |
public function check_color( $value ) { |
38 |
|
39 |
if ( preg_match( '/^#[a-f0-9]{6}$/i', $value ) ) { // if user insert a HEX color with # |
40 |
return true; |
41 |
}
|
42 |
|
43 |
return false; |
44 |
}
|
Falls der Benutzer versucht den Farbwert manuell falsch einzugeben, wird der Color Picker ihn darauf hinweisen, das die Eingabe ungültig ist; allerdings, obwohl die Eingabe unter Umständen keinen Farbwert darstellt, wird die Eingabe trotzdem in der Datenbank abgespeichert. Die check_color()-Funktion wird daher die Eingabe auf Gültigkeit überprüfen.
Schritt 7
Dies ist der letzte und finale Schritt. Wir werden unsere JavaScript-Datei, welche das normale Eingabefeld mit dem Color Picker ausstattet, einbinden.
1 |
/**
|
2 |
* Function that will add javascript file for Color Piker.
|
3 |
*/
|
4 |
public function enqueue_admin_js() { |
5 |
|
6 |
// Make sure to add the wp-color-picker dependecy to js file
|
7 |
wp_enqueue_script( 'cpa_custom_js', plugins_url( 'jquery.custom.js', __FILE__ ), array( 'jquery', 'wp-color-picker' ), '', true ); |
8 |
}
|
Nachdem wir die jquery.custom.js-Datei eingebunden haben, müssen wir diese jetzt allerdings noch erstellen.
1 |
(function( $ ) { |
2 |
$(function() { |
3 |
|
4 |
// Add Color Picker to all inputs that have 'color-field' class
|
5 |
$( '.cpa-color-picker' ).wpColorPicker(); |
6 |
|
7 |
});
|
8 |
})( jQuery ); |
Wenn Ihr jetzt das Plugin aktiviert, solltet Ihr eine Einstellungsseite mit den Eingabefeldern wie in dem Bild unten zusehen bekommen.
That's It!
In dieser Anleitung habt Ihr gelernt, wie Ihr den neuen WordPress Color Picker verwenden könnt. In dem Demo-Plugin habe ich Euch gezeigt, wie Ihr diesen in ein echtes Plugin einbinden könnt. Ihr könnt die Color Picker API allerdings nahezu überall verwenden: in Meta-Boxen, Widget-Formularen, und so weiter.
Der Color Picker steht nur in WordPress 3.5+ zur Verfügung. Falls ein Benutzer eine ältere WordPress-Version verwendet, wird unser Code jedoch trotzdem funktionieren; nur ohne die Anzeige des neuen Color Pickers. Achtet auf jeden Fall darauf, jeden Farbwert mit der check_color()-Funktion, wie in Schritt 6 gezeigt, zu validieren.
Eure Plugins und Themes sind nun mächtiger und benutzerfreundlicher als vorher.
