Hogyan készíthetsz saját WordPress Adminisztrációs oldalt, 1. rész

() translation by (you can also view the original English article)

Egy korábbi sorozatban megmutattam, hogyan használhatod a WordPress Beállítások API-t. Ha új vagy a WordPresshez, vagy eddig más eszközöket - mint pl. a Customizer - használtál a különböző beállítások kezeléséhez, ez olyas valami lesz számodra, amit eddig nem kellett használod a sablonod vagy bővítményed elkészítésekor.

Ahogy a Kódex írja:

A Beállítások API, ami a WordPress 2.7 óta létezik, lehetővé teszi a beállítási űrlappal ellátott admin oldalak fél-automatikus kezelését. Lehetővé teszi, hogy létrehozz oldalakat, azokon belül szekciókat, és mezőket a szekciókon belül.

Nem gondolom, hogy ez olyan, amit kötelező megtanulni, inkább valami, amiről jó, ha tudod, hogy létezik, és hogy hogyan használható, arra az esetre, ha olyan helyzetben találnád magad, hogy a WordPress adminisztrációs felületen beállítási oldalakat kelljen létrehoznod.

Ez egy hatékony, bár kicsit összetett API, ami sok lehetőséget biztosít. Összességében arra jó, hogy a munka részét mi végezzük el szerver oldalon, és minimális része jusson a kliens oldalra.

De mi van akkor, ha egy egyedi megoldáson dolgozunk a megrendelőnek, és egy kicsit több rugalmasságra van szükség, mint amit a Beállítások API (Settings API) biztosít? Például, ha írnunk kell egy bővítményt, aminek kell egy beállítások oldal, de több beállításra van szükség, és egyéni validáló funkciókra?

Erre az esetre lehetőség van, hogy megírjuk a saját WordPress adminisztrációs oldalunkat. Ebben a sorozatban megnézzük, hogyan is kell ezt pontosan csinálni.

Mielőtt nekikezdenénk

Mint a legtöbb tutorialnál, itt is fontos, hogy minden a kezednél legyen a folytatáshoz, így tudd követni a forráskódot, amivel keresztül megyünk a sorozaton.

Ehhez a részhez szükséges:

Hogy legyen egy helyi programozó környezeted beállítva, ami megfelel az operációs rendszerednek.
Hogy legyen egy felinstallált WordPress példányod, ami kész egy bővítmény fogadására.
Hogy ismerős legyél a WordPress bővítmény írásának gyakorlatával.
Hogy ismerős legyél a PHP és HTML nyelvekkel.

Ha nem tudod, hogyan kell egy helyi fejlesztő környezetet létrehozni, ami WordPress-t tartalmaz, kérlek olvasd el ezt a sorozatot, hogy megértsd, hogy működik.

Ha csak viszonylag vagy ismerős a PHP nyelvben, még ha ez csak annyit is jelent, hogy olvasni tudod a kódot, igyekszem majd érthető lépéseket írni és kommentálni a kód minden részét.

Ha mindez megvan, készen is állunk, hogy a bővítményünkön dolgozzunk.

Egyedi WordPress adminisztrációs beállítások

Mire a sorozat végére érünk, lesz egy bővítményünk, ami megfelel a következőknek:

Képes hozzáadni egy almenüt a létező WordPress menürendszerhez.
Képes hozzáadni beállításokat, amik az új almenübe illenek.
Elvégzi a beállítások megfelelő rendszerbe rendezését az oldalon.
Ellenőrzi a beírt értékeket, lementi és később megjeleníti.

Ezen kívül, úgy fogjuk a bővítményünket megírni, hogy a lehető legmodulárisabban legyen felépítve, követve a WordPress Programozási Szabványokat és hasonló praktikákat, hogy a bővítményünk kódja olvasható, írható és karbantartható legyen a lehető legkönnyebb módon.

1. A bővítmény alapja

Az első, amit meg kell tennünk, hogy létrehozzuk a bővítmény alapját. Ez állni fog egy mappa létrehozásából, hogy tudjuk hol tárolni a bővítmény fájljait, egy egyszerű OLVASSEL filet, a licensz egy példányát, egy alap PHP file-t, ami magát a bővítményt fogja indítani, és egy másik mappát, ami az osztályokat fogja tartalmazni az adminisztrációhoz.

A fájlok ehhez a bejegyzéshez mellékletként letölthetőek, de addig is, láthatod itt, hogy néz ki az én mappám:

A bővítmény alapja elég egyszerű. Kérlek, nézd át a következő kódot a custom-admin-settings.php -ben, utána kifejtjük részletesen a következő blokkban.

<?php
/**
 * The plugin bootstrap file
 *
 * This file is read by WordPress to generate the plugin information in the
 * plugin admin area. This file also defines a function that starts the plugin.
 *
 * @link              https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1
 * @since             1.0.0
 * @package           Custom_Admin_Settings
 *
 * @wordpress-plugin
 * Plugin Name:       Custom Admin Settings
 * Plugin URI:        http://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1
 * Description:       Demonstrates how to write custom administration pages in WordPress.
 * Version:           1.0.0
 * Author:            Tom McFarlin
 * Author URI:        https://tommcfarlin.com
 * License:           GPL-2.0+
 * License URI:       http://www.gnu.org/licenses/gpl-2.0.txt
 */

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
     die;
}

add_action( 'plugins_loaded', 'tutsplus_custom_admin_settings' );
/**
 * Starts the plugin.
 *
 * @since 1.0.0
 */
function tutsplus_custom_admin_settings() {

}

Észreveheted, hogy a fenti kódban a valódi kód alapvetően kevés. Ehelyett, jó sok a komment. A fájl felső részében lévő komment blokk leírja, mire is való a fájl.

A @wordpress-plugin tag alatti rész az, amit a WordPress beolvas, hogy legenerálja a bővítmény címét, leírását, és relatív linkeit a WordPress Bővítmények oldalhoz.

Ezután, meggátoljuk, hogy a fájl közvetlenül hozzáférhető legyen. Végül, készítünk egy egyedi függvényt, amit majd a plugins_loaded hook meghív. Ez az a függvény, ami majd elindítja a bővítményt.

Ezen a ponton, ha már belépsz a WordPress adminisztrációs felületre, látnod kell a plugint a Bővítmények oldalon. Kattints is gyorsan az Aktiválás gombra.

Semmi sem történik egyelőre, de ahogy megyünk tovább a tutorialon, hozzáadjuk magát a működést is.

2. Az almenü létrehozása

Ahhoz, hogy el tudjuk kezdeni a munkát, először adjunk hozzá egy almenüt. Ehhez, kihasználjuk a WordPress API add_options_page függvényét. Ez a függvény öt paramétert vár:

a szöveget, ami az almenü által betöltött oldal címe lesz
a szöveget, ami az almenü, mint menüpont címe lesz
a szükséges jogosultságokat, amik az almenü eléréséhez szükségesek
egy egyedi azonosítót
egy callback függvényt, ami az adminisztrációs oldal létrehozásáért felelős

Osztályokat foguk használni arra, hogy rendszerezzük a funkcionalitást, ezért a legtöbb kód objektum-orientált lesz.

Először is, készítsük egy osztályt az admin mappában class-submenu.php néven. Mivel ez az osztály egy új almenü készítésére való, ennek megfelelően fogjuk elnevezni.

Az osztály tartalma így fog kinézni:

<?php
/**
 * Creates the submenu item for the plugin.
 *
 * @package Custom_Admin_Settings
 */

/**
 * Creates the submenu item for the plugin.
 *
 * Registers a new menu item under 'Tools' and uses the dependency passed into
 * the constructor in order to display the page corresponding to this menu item.
 *
 * @package Custom_Admin_Settings
 */
class Submenu {

        /**
   * A reference the class responsible for rendering the submenu page.
	 *
	 * @var    Submenu_Page
	 * @access private
	 */
	private $submenu_page;

	/**
	 * Initializes all of the partial classes.
	 *
	 * @param Submenu_Page $submenu_page A reference to the class that renders the
	 *																	 page for the plugin.
	 */
	public function __construct( $submenu_page ) {
		$this->submenu_page = $submenu_page;
	}

	/**
	 * Adds a submenu for this plugin to the 'Tools' menu.
	 */
	public function init() {
		 add_action( 'admin_menu', array( $this, 'add_options_page' ) );
	}

	/**
	 * Creates the submenu item and calls on the Submenu Page object to render
	 * the actual contents of the page.
	 */
	public function add_options_page() {

		add_options_page(
			'Tuts+ Custom Administration Page',
			'Custom Administration Page',
			'manage_options',
			'custom-admin-page',
			array( $this->submenu_page, 'render' )
		);
	}
}

Ezen a ponton a bővítménynek még mindig nem szabad semmit csinálnia. Még létre kell hoznunk magát a Submenu_Page osztályt, és az osztályokat meg kell hívnunk az alap fájlban.

3. Az aloldal létrehozása

Kezdjük a Submenu_Page osztállyal. Hozz létre egy újabb fájlt az admin mappában, és nevezd el class-submenu-page.php -nek. Ezután, add hozzá a következő kódot.

<?php
/**
 * Creates the submenu page for the plugin.
 *
 * @package Custom_Admin_Settings
 */

/**
 * Creates the submenu page for the plugin.
 *
 * Provides the functionality necessary for rendering the page corresponding
 * to the submenu with which this page is associated.
 *
 * @package Custom_Admin_Settings
 */
class Submenu_Page {

        /**
	 * This function renders the contents of the page associated with the Submenu
	 * that invokes the render method. In the context of this plugin, this is the
	 * Submenu class.
	 */
	public function render() {
		echo 'This is the basic submenu page.';
	}
}

Amikor ez a kód lefut és az oldal legenerálódik, ennyit fog megjeleníteni: "This is the basic submenu page." Ide fogunk majd beállításokat illeszteni. De először, keltsük életre a bővítményt azzal, hogy az alap fájlunkban beindítjuk.

A menü és az oldal legenerálása

Ezután, nyisd meg a custom-admin-settings.php fájlt, amit korábban létrehoztunk. Írjuk is meg a kódot, ami az új almenü létrehozásához és a hozzá való oldalhoz szükséges.

Ne felejtsd, a Submenu osztálynak szüksége van a Submenu_Page osztály egy példányának átadására a constructor felé, aztán meg kell hívnunk az init metódust a Submenu osztályon hogy az egész működni kezdjen.

A kódban, ez a következőképpen néz ki:

<?php

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
     die;
}

// Include the dependencies needed to instantiate the plugin.
foreach ( glob( plugin_dir_path( __FILE__ ) . 'admin/*.php' ) as $file ) {
	include_once $file;
}

add_action( 'plugins_loaded', 'tutsplus_custom_admin_settings' );
/**
 * Starts the plugin.
 *
 * @since 1.0.0
 */
function tutsplus_custom_admin_settings() {

	$plugin = new Submenu( new Submenu_Page() );
	$plugin->init();

}

Ezen a ponton már ott tartunk, hogy ha a WordPress példányodat frissíted, aktiválod a bővítményt (ha még nincs), látodd az új aloldalt az adminisztrációs felületen.

The custom WordPress administration screen

A következő cikkben, megnézzük, hogyan tudunk konkrét beállításokat létrehozni a lapon. Ezen túl, belenézünk a legjobb praktikákba azzal kapcsolatban, hogy hogyan kezeljük a sablonokat és sablon részeket, illetve, hogy hogyan kötjük majd az APIhoz, hogy ne csak elmentse a beállításokat, de rendszerezze és ellenőrizze is őket.

De mielőtt ilyen messzire megyünk, egy kicsit még beszélni akarok a tutorialunkban elkészített osztályok tervezéséről. Alapjában véve, arról akarok beszélni, miért van Submenu és Submenu_Page osztályunk, és hogy ezek hogyan kapcsolódnak az alap fájlhoz.

Egy szó az osztályok felelősségéről

Azoknak, akik az Egy osztály egy felelősség alapelvet ismerik, ez a rész talán unalmas lesz. De ha jól jön egy kis ismétlés vagy kíváncsi vagy többre is, olvass tovább.

Gyűjtsd össze azokat a dolgokat, amik ugyanazon okból változnak. Válaszd el azokat, amik különböző okokból változnak.

Ez ennél többről szól, de ha megnézed az osztályokat egyenként (legalábbis azt a kettőt, amink van eddig), akkor láthatod, hogy az okok, amik miatt változhatnak, a következők:

Az almenü tartalma változik. Bármi az oldal címétől elkezdve az azonosítóig.
A folyamat, ahogy az oldal legenerálódik, változhat (és fog is). Konkrétan itt, jelenleg, semmi mást nem csinál, csak kiír egy szöveget. Hamarosan, be fog tölteni egy adott fájlt. Ezután, talán több fájlt is be kell majd töltenie.

A felső két ok két nagyon különböző ok, amik miatt az osztályok változhatnak, úgyhogy a két dolgot egy osztályban tartani megszegné a fent említett elvet.

Összességében, nem csak azért említem ezt, hogy jobban megértessem a szoftverírás azon elveit, amik WordPress programozásra alkalmazhatóak, hanem hogy megértsd majd, miért szedünk szét olyan részeket, amik sokszor egy nagy fájlban tárolódnak egy WordPress bővítményben.

Az egyik legjobb dolog az elvek megtanulásában, hogy több projektben is alkalmazhatóak, nem csak egy adottban. Megtanulod, gyakorlod őket, és jobban fogsz tudni másoknak tervezési megoldásokat összerakni.

A tanulási folyamat lehet meredek, de amint elkezded azt az utat a lejtőn felfelé, könnyebb és könnyebb lesz ezeket az elveket beépíteni a mindennapi munkádba. Ezután, a munkád amit másoknak készítesz, sokkal könnyebben lesz karbantartható.

Összegzés

Ne felejtsd, a bővítmény a jelenlegi állapotában letölthető erről az oldalról. Ahogy majd haladunk a sorozaton keresztül, mindig letölthetővé teszem majd az aktuális verziót, úgyhogy tudod majd követni a leírt kódot minden részben, ismerkedni vele, és előkészülni az esetleges kérdéseiddel, amiket kommentben le szeretnél írni.

Egy megjegyzésként, ha más megoldások is érdekelnek, amik segíthetnek növelni a WordPress-szel kapcsolatos eszköztáradat, vagy olyan kódok, amiket tanulmányozva jobban felkészült lehetsz WordPressben, ne felejtsd el megtekinteni, mit nyújt még az Envato Market.

Bármelyik tanfolyamomat vagy tutorialomat eléred a profilomon, követhetsz a blogomon és/vagy a Twitteremen a @tommcfarlin felhasználónév alatt, ahol különböző programozási gyakorlatokról írok, és hogy azokat hogyan használhatjuk WordPressben.

Végül, ne habozz leírni bármilyen kérdésedet vagy kommentedet a cikk alatt. Megteszem a tőlem telhető legtöbbet, hogy részt vegyek a beszélgetésben, és hogy válaszoljak a kérdésekre vagy kritikákra, amiket leírtok a projekttel kapcsolatban.

1	<?php
2	/**
3	* Creates the submenu item for the plugin.
4	*
5	* @package Custom_Admin_Settings
6	*/
7
8	/**
9	* Creates the submenu item for the plugin.
10	*
11	* Registers a new menu item under 'Tools' and uses the dependency passed into
12	* the constructor in order to display the page corresponding to this menu item.
13	*
14	* @package Custom_Admin_Settings
15	*/
16	class Submenu {
17
18	/**
19	* A reference the class responsible for rendering the submenu page.
20	*
21	* @var Submenu_Page
22	* @access private
23	*/
24	private $submenu_page;
25
26	/**
27	* Initializes all of the partial classes.
28	*
29	* @param Submenu_Page $submenu_page A reference to the class that renders the
30	* page for the plugin.
31	*/
32	public function __construct( $submenu_page ) {
33	$this->submenu_page = $submenu_page;
34	}
35
36	/**
37	* Adds a submenu for this plugin to the 'Tools' menu.
38	*/
39	public function init() {
40	add_action( 'admin_menu', array( $this, 'add_options_page' ) );
41	}
42
43	/**
44	* Creates the submenu item and calls on the Submenu Page object to render
45	* the actual contents of the page.
46	*/
47	public function add_options_page() {
48
49	add_options_page(
50	'Tuts+ Custom Administration Page',
51	'Custom Administration Page',
52	'manage_options',
53	'custom-admin-page',
54	array( $this->submenu_page, 'render' )
55	);
56	}
57	}