Eritellud seadistuspaneeli ehitamine WordPressi teemale on ülesanne, mis võib venida nädalateks. WordPressi Settings API nõuab tohutul hulgal tüüpkoodi kirjutamist: registreerimine, väljade renderdamine, valideerimine, salvestamine. Ja kui projekt põleb, on selle kõige nullist kirjutamine lubamatu luksus.

Redux Framework lahendab selle probleemi radikaalselt: Settings API käsitsi jändamise asemel kirjeldad vajalikud väljad ühes konfiguratsioonifailis ning raamistik hoolitseb kõige muu eest, renderdamine, valideerimine, escaping, import/eksport ja isegi dünaamiline CSS. WordPress.org-is on pluginat alla laaditud üle 32 miljoni korra ja sellel on üle miljoni aktiivse installatsiooni ning see pole turunduslik inflatsioon, vaid otsene tagajärg sellest, et Redux säästab tõepoolest nädalaid arendustööd.

Selles juhendis seadistame Redux Frameworki samm-sammult nullist kuni töötava teema seadistuspaneelini, sealhulgas otseesitlus kohandajas ja salvestatud väärtuste turvaline kasutamine avalikus vaates.

💡 Kiirülevaade:

• Redux Frameworki paigaldamine: kolm viisi WordPressi projekti integreerimiseks
• Raamistiku ühendamine ja konfiguratsioonifaili loomine
• Paneeli argumentide seadistamine: asukoht menüüs, kohandaja, Google Fonts
• Sektsioonide ja sisendväljade lisamine ühtse Redux API kaudu
• Salvestatud väärtuste väljavõtmine teema mallides koos veakaitsega

Mis on Redux Framework ja miks seda vaja on

Redux Framework on tasuta avatud lähtekoodiga seadistuste raamistik WordPressi teemadele ja pluginatele. See on ehitatud standardse WordPressi Settings API peale, kuid abstraheerib täielikult selle keerukuse. Kümnete register_setting, add_settings_field ja settings_fields väljakutsete asemel kirjutad PHP-s deklaratiivse massiivi ning saad täielikult töötava, responsiivse seadistuspaneeli, mille valikus on 49 väljatüüpi.

Oluline on mitte segi ajada olekuhalduse JavaScripti teegiga Redux, need on täiesti erinevad tooted, millel on sama nimi. WordPressi raamistik ilmus enne JS teeki.

Peamised võimalused, mille saad "karbist väljas":

• 49 väljatüüpi: alates tavalisest tekstist ja märkeruudust kuni ACE redaktori, kordaja, Google Mapsi, plokkide sorteerija ja pildikerijani;
• Automaatne CSS väljund: tüpograafia, värvi, gradiendi, vahede väljade puhul piisab CSS selektori määramisest ja Redux genereerib ise stiililehe koos Google Fontsiga;
• Kohandaja integratsioon: sama argument customizer => true ja kogu paneel dubleeritakse WordPressi kohandajas koos otse-eelvaatega;
• Seadete import/eksport: sisseehitatud tööriist konfiguratsiooni ülekandmiseks saitide vahel;
• Kompilaator: konks, mis käivitub, kui muutub väli lipuga compile => true, näiteks saad sellega SCSS-i uuesti ehitada;
• Valideerimine ja escaping: iga väärtus läbib väljatüübile vastava puhastuse, tekstiväli ei võta vastu massiivi, numbriväli filtreerib stringid välja.

Alates 2024. aastast areneb raamistik Team Updrafti (David Anderson, UpdraftPlusi looja) tiiva all. Praegune versioon 4.5.11 (märts 2026), täielik ühilduvus WordPress 7.0 ja PHP 8.5-ga. Projekt asub aadressil redux.io, dokumentatsioon Reduxi dokumentatsiooni saidil.

Redux Frameworki paigaldamine

Reduxi lisamiseks projekti on kolm viisi. Valik sõltub sinu teema arhitektuurist ja sellest, kuidas plaanid seda levitada.

Eraldi pluginana

Paigalda Redux Framework WordPress.org kataloogist tavalise pluginana. Pärast aktiveerimist seadistuspaneeli ei ilmu, plugin pakub ainult API-t. Kõik seaded kirjeldad konfiguratsioonifailis oma teema sees.

Plussid: teema jääb kergeks (raamistiku tuum ei paisu arhiivi); raamistik uueneb iseseisvalt standardse WordPressi mehhanismi kaudu.

Miinused: sinu teema nõuab kolmanda osapoole plugina olemasolu, kasutaja peab selle eraldi paigaldama ja aktiveerima; ilma pluginata kaob seadistuspaneel ning teema koodis pead tagama graatsilise varukäitumise.

Teema tuumas

Kopeeri ReduxCore kaust oma teema sisse ja ühenda see failis functions.php. Raamistik muutub teema lahutamatuks osaks, kasutaja ei pea lisamoodulit paigaldama.

Plussid: seadistuspaneel näeb välja nagu teema loomulik osa, kasutaja ei paigalda midagi täiendavat.

Miinused: teema arhiivi suurus kasvab umbes 2 MB võrra; iga raamistiku uuendus nõuab sinupoolset teema uuendust; Theme Check plugin võib anda hoiatusi.

Sõltuvas teemapluginas

Soovitatav lähenemine premium-teemadele. Loo oma teemale eraldi kaasnev plugin (sinna on mugav hoida ka kohandatud postitüüpe, lühikoode, vidinaid) ja põimi Redux sellesse. Teema functions.php failis lisa selle plugina olemasolu kontroll TGMPA või sarnase mehhanismi kaudu.

Plussid: puhas arhitektuur (teema funktsionaalsus on esitlusest eraldatud); raamistik ei paisu teema arhiivi; raamistiku uuendused ei mõjuta otseselt teema koodi.

Miinused: nõuab eraldi plugina kirjutamist ja hooldamist; veidi kõrgem sisenemislävi teistele arendajatele, kes projekti uurima hakkavad.

Reduxi konfiguratsioon ei sõltu paigaldusmeetodist, edasised sammud on identsed iga variandi puhul.

Üldine konfiguratsioon: raamistiku ühendamine

Redux Frameworki plugina seest (või ametlikult Reduxi saidilt alla laaditud arhiivist) leia kaust ReduxCore, see sisaldab kogu tuuma.

Loo oma pluginasse (või teemasse) kaust, näiteks optionpanel, ja kopeeri sinna ReduxCore sisu. Kõrvale pane tühi config.php fail, selles kirjeldame kõik sektsioonid ja paneeli väljad.

Nüüd ühenda raamistik. Plugina põhifaili (või teema functions.php) lisa:

1
<?php
2
if ( ! class_exists( 'Redux' ) ) {
3
    require_once plugin_dir_path( __FILE__ ) . 'optionpanel/ReduxCore/framework.php';
4
}

class_exists kontroll hoiab ära saatusliku vea, kui mõni teine saidi osa on Reduxi juba laadinud (näiteks eraldi pistikprogrammi kaudu). Kui raamistik puudub, siis seadete paneeli lihtsalt ei laadita ja sait jätkab tööd.

Pärast seda saad asuda sektsioonide ja väljade loomise juurde.

Seadete paneeli loomine

Raamistiku argumendid

Esmalt määra globaalne muutuja kõigi seadete hoidmiseks, seda läheb vaja väärtuste väljavõtmiseks teema mallides:

1
$opt_name = 'mytheme_options';

Prefiks on kohustuslik, see hoiab ära nimekonfliktid teiste Reduxi kasutavate pistikprogrammidega. Hea tava: brandname_themename.

Nüüd paneme kokku argumentide massiivi. Siin on minimaalne töötav konfiguratsioon:

1
$args = array(
2
    'opt_name'             => $opt_name,
3
    'display_name'         => 'Theme Settings',
4
    'display_version'      => '1.0.0',
5
    'menu_type'            => 'submenu',
6
    'allow_sub_menu'       => true,
7
    'menu_title'           => 'Theme Settings',
8
    'page_title'           => 'Theme Settings Panel',
9
    'page_parent'          => 'themes.php',
10
    'page_permissions'     => 'manage_options',
11
    'page_slug'            => 'theme_options',
12
    'dev_mode'             => false,
13
    'update_notice'        => false,
14
    'customizer'           => true,
15
    'save_defaults'        => true,
16
    'show_import_export'   => true,
17
    'async_typography'     => true,
18
    'admin_bar'            => true,
19
    'global_variable'      => $opt_name,
20
);
21
 
22
Redux::set_args( $opt_name, $args );

Peamiste argumentide lahtiseletus:

• menu_type: submenu, paneel ilmub „Välimus" menüüelemendi sisse; menu, eraldiseisev ülataseme element administraatoris;
• customizer: true lubab kõigi väljade dubleerimise WordPressi kohandajas koos eelvaatega, kasutaja näeb muudatusi enne salvestamist;
• dev_mode: luba arenduse ajal (laiendatud silumine, demode import), kuid kindlasti lülita enne avaldamist välja;
• update_notice: alati false manustatud Reduxiga teemade ja pistikprogrammide puhul, sinu kasutajad ei tohiks saada raamistiku uuendusteateid sinu tootest eraldi;
• show_import_export: lisab tööriista kõigi seadete ühe klõpsuga saitide vahel teisaldamiseks.

Rohkem kui 40 argumendi täielikku loendit vaata argumentide juhendist.

Sektsioonide ja väljade lisamine

Sektsioon on loogiline väljade grupp (kaart seadete ekraanil). Minimaalne sektsioon:

1
Redux::set_section( $opt_name, array(
2
    'title'  => 'Site Header',
3
    'id'     => 'header_section',
4
    'icon'   => 'dashicons-heading',
5
    'fields' => array(
6
        array(
7
            'id'       => 'header_logo',
8
            'type'     => 'media',
9
            'title'    => 'Logo',
10
            'subtitle' => 'Upload logo image',
11
            'default'  => array( 'url' => get_template_directory_uri() . '/images/logo.png' ),
12
        ),
13
        array(
14
            'id'      => 'sticky_header',
15
            'type'    => 'switch',
16
            'title'   => 'Sticky Header',
17
            'default' => true,
18
        ),
19
    ),
20
) );

Sektsiooni ikoonid: Redux 4.x toetab sisseehitatud WordPressi Dashicons'e (täielik loend aadressil developer.wordpress.org). Kohandatud ikoonide jaoks kasuta oma ikoonikomplekti CSS-klasse (näiteks Font Awesome).

Iga väli on assotsiatiivne massiiv kohustuslike võtmetega id, type ja title. Näited sagedamini kasutatavatest tüüpidest:

1
// Select with search
2
array(
3
    'id'      => 'sidebar_layout',
4
    'type'    => 'select',
5
    'title'   => 'Sidebar Layout',
6
    'options' => array(
7
        'right' => 'Sidebar Right',
8
        'left'  => 'Sidebar Left',
9
        'none'  => 'No Sidebar',
10
    ),
11
    'default' => 'right',
12
),
13
 
14
// RGBA color picker
15
array(
16
    'id'      => 'accent_color',
17
    'type'    => 'color_rgba',
18
    'title'   => 'Accent Color',
19
    'default' => array(
20
        'color' => '#2271b1',
21
        'alpha' => 1,
22
    ),
23
),
24
 
25
// Typography with Google Fonts
26
array(
27
    'id'          => 'body_typography',
28
    'type'        => 'typography',
29
    'title'       => 'Text Font',
30
    'google'      => true,
31
    'font-backup' => true,
32
    'line-height' => true,
33
    'font-size'   => true,
34
    'default'     => array(
35
        'font-family' => 'Inter',
36
        'font-size'   => '16px',
37
    ),
38
),

Alamsektsiooni loomiseks lisa argument 'subsection' => true, väli ilmub pesastatud kaardina ülemsektsiooni sisse.

Kõigi 49 tüübi loend koos konfiguratsiooninäidetega on Reduxi dokumentatsiooni väljatüüpide osas.

Valikute kasutamine teemas

Redux salvestab kõik väärtused ühte globaalsesse muutujasse, samasse, mille määrasid parameetris $opt_name. Väärtuse saamiseks mallis deklareeri see esmalt globaalseks. Kuid otsene global deklaratsioon väljaspool funktsiooni või action'it on halb tava. Õige lähenemine:

1
function mytheme_get_option( $option_id, $default = '' ) {
2
    global $mytheme_options;
3
    return isset( $mytheme_options[ $option_id ] ) ? $mytheme_options[ $option_id ] : $default;
4
}

Ümbrisfunktsioon teeb kaks asja: hoiab ära PHP Notice „undefined index" olematu võtme poole pöördumisel ja pakub varuväärtust. Mallis näeb kasutamine välja selline:

1
$logo = mytheme_get_option( 'header_logo' );
2
if ( ! empty( $logo['url'] ) ) {
3
    echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( get_bloginfo( 'name' ) ) . '">';
4
}

Kui seadete paneel pole veel seadistatud (näiteks kasutaja aktiveeris teema, kuid ei paigaldanud sõltuvat pluginat), on $mytheme_options tühi massiiv ja mytheme_get_option() tagastab vaikimisi $default ilma hunniku hoiatusteta failis debug.log.

Dünaamilise CSS-i jaoks kasuta Reduxi sisseehitatud võimet, määra välja seadistuses output argument:

1
array(
2
    'id'     => 'body_bg_color',
3
    'type'   => 'color',
4
    'title'  => 'Background Color',
5
    'output' => array( 'background-color' => 'body' ),
6
),

Redux genereerib ja lisab automaatselt CSS-reegli <style>body{background-color:#fff;}</style>, ilma ühegi käsitsi kirjutatud koodireata.

Paigaldus- ja väljade seadistamise protsess on selgelt näidatud selles videoõpetuses: alates raamistiku ühendamisest kuni esimese sektsiooni loomiseni koos valikute ja lülititega:

⁉️🤔 Korduma kippuvad küsimused

Mille poolest Redux Framework erineb Carbon Fieldsist, ACF Options Pagesist ja teistest lahendustest?

Redux pakub 49 väljatüüpi „karbist võttes" (võrdluseks ~25 Carbon Fieldsis ja ~30 ACF Pro-s) ning keskendub spetsiaalselt teema seadete paneelidele, mitte postituse meta väljadele. ACF Options Pages on lisand meta välja mootorile, samas kui Redux oli algselt disainitud valikute paneelide jaoks: sisseehitatud import/eksport, kompilaator, live-eelvaade customizer'is, dünaamiline CSS koos Google Fontsiga. Carbon Fields on olemuselt lähedasem, kuid nõuab Composerit ja nimeruume, mis paljudes hostimiskeskkondades on takistuseks. Järeldus: kui kasutad juba ACF-i meta väljade jaoks, võta ACF Options Pages, et vältida olemite paljundamist; kui ehitad teemat nullist ja vajad võimsat valikute paneeli, annab Redux tasuta rohkem funktsioone.

Kas Redux Framework töötab plokiteemadega (Full Site Editing)?

Jah, kuid mööndustega. Redux väljastab seadete paneeli läbi klassikalise adminiliidese (Settings API), mitte läbi saidiredaktori. Hübriidse lähenemise korral, plokiteema pluss Reduxi paneel globaalsete seadete jaoks (värvid, tüpograafia, analüütika skriptid), kombinatsioon töötab. Versiooni 4.5.11 seisuga pole otsest integratsiooni theme.json-iga rakendatud: väärtused tuleb mallides välja võtta läbi mytheme_get_option() ja lisada CSS-muutujatena. Puhta FSE keskkonna puhul, kus kõik seaded peaksid asuma saidiredaktoris, on Redux üleliigne; klassikaliste ja hübriidteemade jaoks üks parimaid valikuid.

Mida teha, kui Redux läheb vastuollu teise pluginaga, mis kasutab sedasama teeki?

See on tuntud „topelt kaasamise" probleem. Kontroll if ( ! class_exists( 'Redux' ) ) enne require_once-i garanteerib, et raamistik laaditakse täpselt ühe korra: WordPress käivitab PHP-d järjestikku ja kõige esimene require_once muudab järgnevad kutsed kahjutuks. Kui sinu teema ja kolmanda osapoole plugin mõlemad tõmbavad Reduxi, laaditakse see koopia, mis esimesena initsialiseeriti, ja mõlema toote paneelid jätkavad tööd. Olulise versioonide erinevuse korral on võimalik mitteühilduvus API tasemel, mis parandatakse mahajäänud poole uuendamisega jooksvale väljalaskele.

Kas Redux Frameworki kasutamiseks ärilises teemas on vaja litsentsi?

Ei. Redux on levitatud GPLv2 all, sama litsents mis WordPressil. Võid raamistikku vabalt kaasata ärilistesse teemadesse ja pluginatesse, müüa neid ThemeForestis, levitada oma saidi kaudu. Ainus GPLv2 piirang, tuletatud teosed peavad samuti olema GPLv2 all, kuid see nõue kehtib lähtekoodile, mitte lõppkasutaja saidi sisule. Redux Pro (lisaväljad, laiendatud customizer, prioriteetne tugi) on eraldi tasuline toode, mis pole raamistiku toimimiseks vajalik.

Mida teha, kui pärast WordPressi uuendust lakkas Reduxi paneel avanemast?

Stsenaarium: pärast suurt WP uuendust valge ekraan teema seadete lehel. Tegevuste järjekord: esiteks kontrolli, et sul on Reduxi versioon mitte madalam kui 4.5.11 (ühilduvus WP 7.0-ga). Teiseks, lülita minutiks sisse 'dev_mode' => true ja vaata PHP veaväljundit seadete ekraanil, Redux näitab arendusrežiimis üksikasjalikku logi. Kolmandaks, kui viga tulvab konkreetsest väljast, kontrolli, kas kasutad aegunud tüüpi (search eemaldati Redux 3.x-s, divide nimetati ümber). Kehtiv väljade nimekiri on alati Reduxi dokumentatsioonis.

Kas Redux Frameworki tasub 2026. aastal kasutada

Redux Framework on küps, aktiivselt toetatud toode, mille taga on 32 miljonit allalaadimist ja üle 270 kaasautori kogukond GitHubis. Kui ehitad klassikalist või hübriidset WordPressi teemat ja vajad seadete paneeli rikkaliku väljade komplekti, live-eelvaate customizer'is ja dünaamilise CSS-iga, säästab Redux nädalaid arendustööd ja annab tulemuse, mis vastab WordPressi turvalisuse standarditele (PHPCS, escaping, valideerimine).

Arhitektuuriliselt on parim viis integreerimiseks viia raamistik sõltuvasse teema pluginasse läbi require_once koos class_exists kontrolliga. See annab nii puhta koodibaasi kui ka kaitse topelt kaasamise konfliktide eest ja läbipaistva uuendustee.

Millal Reduxi pole vaja: teed kerget teemat ilma seadete paneelita; töötad puhtas FSE keskkonnas (plokiteema koos theme.json-iga); sul on juba ACF rakendatud koos Options Pagesiga meta väljade jaoks. Neil juhtudel on Reduxi tõmbamine ühe sisse/välja nupu pärast nagu varblaste pihta kahurist laskmine: raamistik lisab teemale ~2 MB ilma proportsionaalse kasuta.

Enne töö alustamist vaata ametlikku dokumentatsiooni Reduxi arendajate saidil ja repositooriumi GitHubis, seal saad ka veast teada anda või funktsiooni välja pakkuda. Kui vajad abi konkreetse väljatüübi või argumendiga, kirjuta kommentaaridesse, mõtleme koos välja.