KT MetaBox

Třída KT_MetaBox slouží k definici a obsluze systémových metaboxů, typicky k rozšíření, resp. doplnění vlastních metaboxů k příspěvkům, stránkám a dalším (vlastním) typům obsahu anebo také pro vlastní administrační stránky. KT_MetaBox spolupracuje s KT formuláři a obvykle jeden metabox představuje, resp. obsahuje jeden KT Form Fieldset. Takže ve spojitosti s metaboxy je dobré definovat nebo využávat i KT Configy…

Konstanta KT_CAR_KEY není definovaná v projektu a je použita pouze v ukázkovém příkladě. KT_CAR_KEY prezentuje název vlastního typu obsahu (post_type).

Metaboxy je možné vytvořit buď pomocí konstruktoru třídy KT_MetaBox anebo pomocí před připravených statických metod createXxx…

V případě KT_MetaBoxu rozlišujeme 4 druhy použití, tzv. datové typy metaboxů, které jsou definovány výčtovým typem KT_MetaBox_Data_Type_Enum (na základě KT_Enum):

KT_MetaBox_Data_Type_Enum::POST_META – pro posty a odvozené s uložením do post metas
KT_MetaBox_Data_Type_Enum::OPTIONS – ukládání do (WP) options
KT_MetaBox_Data_Type_Enum::CRUD – pro vlastní modely na základě KT_Crud
KT_MetaBox_Data_Type_Enum::CUSTOM – vlastní zpracování metaboxů (hlavně uložení)

Jak na to

Nejprve si připravíte config soubor s fieldsety (pro formuláře)
Pak vytvoříte soubor pro metaboxy, např. kt/yours/requires/metaboxes/kt_car_metaboxes.inc.php
Pak v souboru definujete jednotlivé instance třídy KT_MetaBox buď pomocí:
- klasické definice třídy přes konstruktor a následnou konfigurací pomocí setrů s následným vyvoláním ručníregistrace metodou ->register()
- nebo přes před připravené statické pomocné metody (podle parametrů):
  - KT_MetaBox::create(…)
  - KT_MetaBox::createMultiple(…)
  - KT_MetaBox::createCrud(…)
  - KT_MetaBox::createCustom(…)

Příklady

Nastavení šablony

Jedním z nejtypičtějších příkladů použití metaboxů a zároveň mírně specifický je nastavení šablony. K tomu je vhodné nejprve definovat config s form fieldsetem. Příklad mluví za vše:

<?php 

if ( is_admin() ) {
    $themeSettings = new KT_Custom_Metaboxes_Subpage( "themes.php", __( "Nastavení šablony", KT_DOMAIN ), __( "Nastavení šablony", KT_DOMAIN ), "update_core", KT_WP_Configurator::THEME_SETTING_PAGE_SLUG );
    $themeSettings->setRenderSaveButton()->register();

    KT_MetaBox::create( KT_WP_FW_Theme_Config::getConfigFieldset(), KT_WP_Configurator::getThemeSettingSlug(), KT_MetaBox_Data_Type_Enum::OPTIONS );
}

<?php

if ( is_admin() ) {

$themeSettings = new KT_Custom_Metaboxes_Subpage( "themes.php", __( "Nastavení šablony", KT_DOMAIN ), __( "Nastavení šablony", KT_DOMAIN ), "update_core", KT_WP_Configurator::THEME_SETTING_PAGE_SLUG );

$themeSettings->setRenderSaveButton()->register();

KT_MetaBox::create( KT_WP_FW_Theme_Config::getConfigFieldset(), KT_WP_Configurator::getThemeSettingSlug(), KT_MetaBox_Data_Type_Enum::OPTIONS );

}

Výpis souboru /kt/yours/requires/metaboxes/kt_wp_fw_theme_metaboxes.inc.php

Založení pro post (nebo options)

Následující kódy založí metabox(y) pdole kolekce fieldset(ů) z configu pro daný typ postu na základě klíče a budou je automaticky načítat a ukládat z/do post meta (kromě zpracování typu custom):

<?php 

// ručně na základě fieldSetu
$fieldSet = KT_Car_Config::getCarFieldset();
$metaBox = new KT_MetaBox($fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::POST_META);

// "pooautomaticky" na základě fieldsetu
$metaBox = KT_MetaBox::create( KT_Car_Config::getCarFieldset(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::POST_META );

// hromadně na základě kolekce fieldsetů
$metaBoxes = KT_MetaBox::createMultiple( KT_Car_Config::getAllGenericFieldsets(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::POST_META );

// vlastní zpracování na základě fieldsetu
$metaBox = KT_MetaBox::createCustom( $fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, kt_car_metabox_custom_callback );

function kt_car_metabox_custom_callback($post, $form) { 
    // TODO: vlastní zpracování 
}

<?php

// ručně na základě fieldSetu

$fieldSet = KT_Car_Config::getCarFieldset();

$metaBox = new KT_MetaBox($fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::POST_META);

// "pooautomaticky" na základě fieldsetu

$metaBox = KT_MetaBox::create( KT_Car_Config::getCarFieldset(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::POST_META );

// hromadně na základě kolekce fieldsetů

$metaBoxes = KT_MetaBox::createMultiple( KT_Car_Config::getAllGenericFieldsets(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::POST_META );

// vlastní zpracování na základě fieldsetu

$metaBox = KT_MetaBox::createCustom( $fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, kt_car_metabox_custom_callback );

function kt_car_metabox_custom_callback($post, $form) {

// TODO: vlastní zpracování

}

Definice pro metaboxy typu POST_META nebo OPTIONS se liší pouze v zadání konstanty a funkce je pak stejná, pouze s rozdílem úložiště.

Založení pro CRUD

Následující kódy založí metabox(y) opět podle kolekce fieldsetů z configu tenktokrát ale pro daný (KT) CRUDu (tzn. vlastní tabulky, resp. objektu z DB) na základě klíče a budou je automaticky načítat a ukládat z/do DB pomocí ID:

<?php 

// ručně na základě fieldSetu
$fieldSet = KT_Car_Config::getCarFieldset();
$metaBox = new KT_MetaBox($fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::CRUD);
$metaBox->setIdParamName(KT_CAR_ID_PARAM);
$metaBox->setClassName("KT_Car_Model");

// "pooautomaticky" na základě fieldsetu
$metaBox = KT_MetaBox::create(KT_Car_Config::getCarFieldset(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::CRUD);
$metaBox->setIdParamName(KT_CAR_ID_PARAM);
$metaBox->setClassName("KT_Car_Model");

// hromadně na základě kolekce fieldsetů
$metaBoxes = KT_MetaBox::createMultiple(KT_Car_Config::getAllGenericFieldsets(), KT_CAR_KEY, KKT_MetaBox_Data_Type_Enum::CRUD);
foreach ($metaBoxes as $metaBox) {
    $metaBox->setIdParamName(KT_CAR_ID_PARAM);
    $metaBox->setClassName("KT_Car_Model");
}

// vlastní zpracování na základě fieldsetu
$metaBox = KT_MetaBox::createCustom($fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, kt_car_metabox_custom_callback);
$metaBox->setIdParamName(KT_CAR_ID_PARAM);
$metaBox->setClassName("KT_Car_Model");

function kt_car_metabox_custom_callback($post, $form) {
    // TODO: vlastní zpracování 
}

<?php

// ručně na základě fieldSetu

$fieldSet = KT_Car_Config::getCarFieldset();

$metaBox = new KT_MetaBox($fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::CRUD);

$metaBox->setIdParamName(KT_CAR_ID_PARAM);

$metaBox->setClassName("KT_Car_Model");

// "pooautomaticky" na základě fieldsetu

$metaBox = KT_MetaBox::create(KT_Car_Config::getCarFieldset(), KT_CAR_KEY, KT_MetaBox_Data_Type_Enum::CRUD);

$metaBox->setIdParamName(KT_CAR_ID_PARAM);

$metaBox->setClassName("KT_Car_Model");

// hromadně na základě kolekce fieldsetů

$metaBoxes = KT_MetaBox::createMultiple(KT_Car_Config::getAllGenericFieldsets(), KT_CAR_KEY, KKT_MetaBox_Data_Type_Enum::CRUD);

foreach ($metaBoxes as $metaBox) {

$metaBox->setIdParamName(KT_CAR_ID_PARAM);

$metaBox->setClassName("KT_Car_Model");

}

// vlastní zpracování na základě fieldsetu

$metaBox = KT_MetaBox::createCustom($fieldset->getName(), $fieldset->getTitle(), KT_CAR_KEY, kt_car_metabox_custom_callback);

$metaBox->setIdParamName(KT_CAR_ID_PARAM);

$metaBox->setClassName("KT_Car_Model");

function kt_car_metabox_custom_callback($post, $form) {

// TODO: vlastní zpracování

}

Synchronizace dat z/do DB v případě CRUD metaboxů probíhá na základě ID parametru v URL a názvu třídy, proto je třeba je vždy zadat!

Rozšířené založení

Pokud chcete v rámci, resp. mimo zakládací statické metody nastavit další parametry, je třeba vypnout automatickou inicializaci a vyvolat jí následně po nastavení požadovaným parametrů ručně:

<?php 

$carMetaboxes = KT_MetaBox::createMultiple(KT_Car_Config::getAllGenericFieldset(), KT_POST_KEY,KT_MetaBox_Data_Type_Enum::POST_META, false);
foreach(carMetaboxes as carMetabox)
{
    $carMetabox->setContext(KT_Metabox::CONTEXT_SIDE)
               ->register();
}

$carMetabox = KT_Metabox::create(KT_Car_Config::getCarFieldset(), KT_POST_KEY, KT_MetaBox_Data_Type_Enum::POST_META, false);
$carMetabox->setContext(KT_Metabox::CONTEXT_SIDE)
           ->register();

<?php

$carMetaboxes = KT_MetaBox::createMultiple(KT_Car_Config::getAllGenericFieldset(), KT_POST_KEY,KT_MetaBox_Data_Type_Enum::POST_META, false);

foreach(carMetaboxes as carMetabox)

{

$carMetabox->setContext(KT_Metabox::CONTEXT_SIDE)

->register();

}

$carMetabox = KT_Metabox::create(KT_Car_Config::getCarFieldset(), KT_POST_KEY, KT_MetaBox_Data_Type_Enum::POST_META, false);

$carMetabox->setContext(KT_Metabox::CONTEXT_SIDE)

->register();

Povinné parametry

V podstatě parametry konstruktoru třídy KT_MetaBox:

$id – identifikační klíč MetaBoxu v systému (v případě pomocných create metod se načte automaticky na Name fieldsetu)
$title – nadpis MetaBoxu v systému (v případě pomocných create metod se načte automaticky na Title fieldsetu)
$screen – klíč obrazovky, resp. umístění MetaBoxu v rámci systému
$dataType – klíč, resp. hodnota datového typu z výčtu KT_MetaBox_Data_Type_Enum
$fieldset (KT_Form_Fieldset) – pokud používáte datový typ CUSTOM, tak není třeba zadávat, jinak je nutný…

Volitelné parametry

(set/get)IsDefaultAutoSave – nastaví označení, zda se má provádět u výchozích akcí automatické uložené dat, výchozí je true
(set/get)CustomCallback – nastaví název případné vlastní funkce pro callback
(set/get)ClassName – nastaví název případné vlastní třídy ve spojitosti s datovým typem: KT_MetaBox_Data_Type_Enum::CRUD
(set/get)IdParamName – nastaví název ID (URL) parametru případné vlastní třídy ve spojitosti s datovým typem: KT_MetaBox_Data_Type_Enum::CRUD
(set/get)Priority – nastavení požadované priority, výchozí je normal
(set/get)Context – nastavení požadovaného contextu, výchozí je default
(set/add/get/remove)PageTemplate(s) – nastavení page templatu pouze pro zadaný page template nebo výčet page templatů (pole)
(set/get)PostFormat – omezení pouze pro zadaný post format

Připravené konstanty

CONTEXT_NORMAL = „normal“;
CONTEXT_ADVANCED = „advanced“;
CONTEXT_SIDE = „side“;
PRIORITY_LOW = „low“;
PRIORITY_HIGH = „high“;
PRIORITY_DEFAULT = „default“;
PRIORITY_CORE = „core“;
DEFAULT_PAGE_TEMPLATE_KEY = „default“;

Shrnutí

U metaboxů tedy rozlišujeme datový typ a to pomocí výčtu: KT_MetaBox_Data_Type_Enum, který určuje, jak se data budou zpracovávat. Založení metaboxů je možné provést pomocí konstruktoru třídy KT_MetaBox, anebo pomocí několika před připravených statických metod KT_MetaBox::createXxx, a celý proces zakládání je úzce spjatý s formuláři, resp. fieldsety a configy.