Oman asetuspaneelin rakentaminen WordPress-teemaan on tehtävä, joka voi venyä viikoiksi. WordPressin Settings API vaatii valtavasti valmista runkokoodia: rekisteröinti, kenttien renderöinti, validointi, tallennus. Ja kun projekti on tulessa, kaiken tämän kirjoittaminen tyhjästä on perusteetonta ylellisyyttä.

Redux Framework ratkaisee tämän ongelman radikaalisti: Settings API:n manuaalisen säätämisen sijaan kuvailet tarvittavat kentät yhdessä konfiguraatiotiedostossa, ja framework hoitaa kaiken muun, renderöinnin, validoinnin, escapauksen, tuonnin/viennin ja jopa dynaamisen CSS:n. WordPress.orgissa lisäosalla on yli 32 miljoonaa latausta ja yli miljoona aktiivista asennusta, eikä tämä ole markkinointiliioittelua, vaan suora seuraus siitä, että Redux todella säästää viikkoja kehitystyötä.

Tässä oppaassa Redux Frameworkin vaiheittainen käyttöönotto tyhjästä toimivaksi teema-asetuspaneeliksi, mukaan lukien live-esittely customizerissa ja tallennettujen arvojen turvallinen käyttö julkisella puolella.

💡 Nopea yleiskatsaus:

• Redux Frameworkin asentaminen: kolme tapaa integroida WordPress-projektiin
• Frameworkin kytkeminen ja konfiguraatiotiedoston luominen
• Paneelin argumenttien määrittely: sijainti valikossa, customizer, Google Fonts
• Osioiden ja syötekenttien lisääminen yhtenäisen Redux API:n kautta
• Tallennettujen arvojen hakeminen teemapohjissa virhesuojauksella

Mikä Redux Framework on ja miksi tarvitset sitä

Redux Framework on ilmainen avoimen lähdekoodin asetusframework WordPress-teemoille ja lisäosille. Se on rakennettu WordPressin vakio-Settings API:n päälle, mutta abstrahoi täysin sen monimutkaisuuden. Kymmenien register_setting-, add_settings_field- ja settings_fields-kutsujen sijaan kirjoitat deklaratiivisen PHP-taulukon ja saat täysin toimivan, responsiivisen asetuspaneelin, jossa on valittavana 49 kenttätyyppiä.

Tärkeää olla sekoittamatta tilanhallinnan JavaScript-kirjastoon Redux, nämä ovat täysin eri tuotteita, joilla on sama nimi. WordPress-framework ilmestyi ennen JS-kirjastoa.

Keskeiset ominaisuudet, jotka saat "suoraan laatikosta":

• 49 kenttätyyppiä: tavallisesta tekstistä ja valintaruudusta ACE-editoriin, toistimeen, Google Mapsiin, lohkojärjestelijään ja kuvaslideriin;
• Automaattinen CSS-tulostus: typografia-, väri-, liukuväri- ja välistyskentille, määrität vain CSS-valitsimen ja Redux itse generoi tyylitiedoston Google Fonts -kirjasimilla;
• Customizer-integraatio: sama argumentti customizer => true, ja koko paneeli monistuu WordPress Customizeriin live-esikatselulla;
• Asetusten tuonti/vienti: sisäänrakennettu työkalu konfiguraation siirtämiseen sivustojen välillä;
• Kääntäjä: koukku, joka laukeaa, kun kenttä, jossa on compile => true -lippu, muuttuu, voit esimerkiksi kääntää SCSS:n uudelleen;
• Validointi ja escapaus: jokainen arvo käy läpi kenttätyyppiä vastaavan puhdistuksen, tekstikenttä ei hyväksy taulukkoa, numerokenttä suodattaa merkkijonot pois.

Vuodesta 2024 lähtien framework on kehittynyt Team Updraftin (David Anderson, UpdraftPlusin luoja) siipien alla. Nykyinen versio, 4.5.11 (maaliskuu 2026), täysi yhteensopivuus WordPress 7.0:n ja PHP 8.5:n kanssa. Projekti elää osoitteessa redux.io, dokumentaatio osoitteessa Reduxin dokumentaatiosivusto.

Redux Frameworkin asentaminen

Reduxin voi lisätä projektiin kolmella tavalla. Valinta riippuu teemasi arkkitehtuurista ja siitä, miten aiot jakaa sitä.

Erillisenä lisäosana

Asenna Redux Framework WordPress.org-hakemistosta tavallisena lisäosana. Aktivoinnin jälkeen asetuspaneeli ei tule näkyviin, lisäosa tarjoaa vain API:n. Kuvailet kaikki asetukset teemasi sisällä olevassa konfiguraatiotiedostossa.

Plussat: teema pysyy kevyenä (frameworkin ydin ei paisuta arkistoa); framework päivittyy itsenäisesti WordPressin vakiomekanismin kautta.

Miinukset: teemasi vaatii kolmannen osapuolen lisäosan olemassaolon, käyttäjän on asennettava ja aktivoitava se erikseen; ilman lisäosaa asetuspaneeli katoaa, ja sinun on tarjottava hallittu varautuminen teemakoodissa.

Teeman ytimessä

Kopioi ReduxCore-kansio teemasi sisälle ja kytke se functions.php-tiedostossa. Frameworkista tulee olennainen osa teemaa, käyttäjän ei tarvitse asentaa ylimääräistä lisäosaa.

Plussat: asetuspaneeli näyttää teeman natiivilta osalta, käyttäjä ei asenna mitään ylimääräistä.

Miinukset: teema-arkiston koko kasvaa noin 2 Mt; jokainen framework-päivitys vaatii teemapäivityksen sinulta; Theme Check -lisäosa saattaa antaa varoituksia.

Riippuvaisessa teemalisäosassa

Suositeltu lähestymistapa premium-teemoille. Luo teemallesi erillinen kumppanilisäosa (siihen on kätevää sijoittaa myös custom post typet, shortcodet, widgetit) ja upota Redux siihen. Teeman functions.php-tiedostoon lisää tarkistus tämän lisäosan olemassaolosta TGMPA:n tai vastaavan mekanismin kautta.

Plussat: puhdas arkkitehtuuri (teeman toiminnallisuus on erotettu esitystavasta); framework ei paisuta teema-arkistoa; framework-päivitykset eivät vaikuta suoraan teemakoodiin.

Miinukset: vaatii erillisen lisäosan kirjoittamista ja ylläpitoa; hieman korkeampi aloituskynnys muille kehittäjille, jotka perehtyvät projektiin.

Reduxin konfiguraatio ei riipu asennustavasta, jatkovaiheet ovat identtiset kaikissa vaihtoehdoissa.

Yleinen konfiguraatio: frameworkin kytkeminen

Etsi Redux Framework -lisäosan sisältä (tai viralliselta Redux-sivustolta ladatusta arkistosta) ReduxCore-kansio, se sisältää koko ytimen.

Luo lisäosaasi (tai teemaasi) kansio, esimerkiksi optionpanel, ja kopioi ReduxCore-kansion sisältö siihen. Laita sen viereen tyhjä config.php-tiedosto, kuvailemme siihen kaikki osiot ja paneelin kentät.

Kytke nyt framework. Lisää lisäosan päätiedostoon (tai teeman functions.php-tiedostoon):

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

class_exists-tarkistus estää kohtalokkaan virheen, jos jokin toinen sivuston osa on jo ladannut Reduxin (esimerkiksi erillisen lisäosan kautta). Jos kehys puuttuu, asetuspaneeli ei yksinkertaisesti lataudu, ja sivusto toimii edelleen.

Tämän jälkeen voit siirtyä luomaan osioita ja kenttiä.

Asetuspaneelin luominen

Kehyksen argumentit

Aseta ensin globaali muuttuja kaikkien asetusten tallentamiseksi, sitä tarvitaan arvojen hakemiseen teemapohjissa:

1
$opt_name = 'mytheme_options';

Etuliite on pakollinen, se estää nimikonfliktit muiden Reduxia käyttävien lisäosien kanssa. Hyvä käytäntö: brandname_themename.

Kootaan nyt argumenttitaulukko. Tässä on minimaalinen toimiva konfiguraatio:

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 );

Keskeisten argumenttien erittely:

• menu_type: submenu, paneeli ilmestyy "Ulkoasu"-valikkokohtaan; menu, erillinen ylätason kohta hallintapaneelissa;
• customizer: true mahdollistaa kaikkien kenttien kopioinnin WordPressin mukauttimeen live-esikatselulla, käyttäjä näkee muutokset ennen tallennusta;
• dev_mode: ota käyttöön kehityksen aikana (laajennettu virheenkorjaus, demojen tuonti), mutta muista kytkeä pois ennen julkaisua;
• update_notice: aina false teemoille ja lisäosille, joihin Redux on upotettu, käyttäjiesi ei tule saada ilmoituksia kehyksen päivityksistä erillään tuotteestasi;
• show_import_export: lisää työkalun kaikkien asetusten siirtämiseksi sivustojen välillä yhdellä napsautuksella.

Täydellinen lista yli 40 argumentista löytyy argumenttioppaasta.

Osioiden ja kenttien lisääminen

Osio on looginen kenttäryhmä (välilehti asetusnäytöllä). Minimaalinen osio:

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
) );

Osioiden kuvakkeet: Redux 4.x tukee sisäänrakennettuja WordPressin Dashicons-kuvakkeita (täydellinen lista osoitteessa developer.wordpress.org). Mukautetuille kuvakkeille käytä oman kuvakesettisi CSS-luokkia (esimerkiksi Font Awesome).

Jokainen kenttä on assosiatiivinen taulukko, jossa on pakolliset avaimet id, type ja title. Esimerkkejä yleisesti käytetyistä tyypeistä:

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
),

Luodaksesi alaosion lisää argumentti 'subsection' => true, kenttä ilmestyy sisäkkäisenä välilehtenä ylätason osion sisällä.

Lista kaikista 49 tyypistä konfiguraatioesimerkkeineen löytyy Redux-dokumentaation kenttätyyppiosiosta.

Optioiden käyttö teemassa

Redux tallentaa kaikki arvot yhteen globaaliin muuttujaan, samaan jonka määritit $opt_name-parametrissa. Saadaksesi arvon templaatissa, julista se ensin globaaliksi. Mutta suora global-määrittely funktion tai actionin ulkopuolella on huono käytäntö. Oikea lähestymistapa:

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
}

Käärefunktio tekee kaksi asiaa: estää PHP Notice "undefined index" -ilmoituksen kun haetaan olematonta avainta ja tarjoaa varoarvon. Templaatissa käyttö näyttää tältä:

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
}

Jos asetuspaneelia ei ole vielä määritetty (esimerkiksi käyttäjä aktivoi teeman mutta ei asentanut riippuvaa lisäosaa), $mytheme_options on tyhjä taulukko, ja mytheme_get_option() palauttaa hiljaisesti $default-arvon ilman kasaa varoituksia debug.logissa.

Dynaamista CSS:ää varten käytä Reduxin sisäänrakennettua ominaisuutta, määritä output-argumentti kenttäkonfiguraatiossa:

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

Redux generoi ja upottaa automaattisesti CSS-säännön <style>body{background-color:#fff;}</style>, ilman yhtäkään riviä manuaalista koodia.

Asennus- ja kenttäasetusprosessi näkyy selkeästi tässä video-oppaassa: kehyksen kytkemisestä ensimmäisen osion luomiseen valintalistoilla ja kytkimillä:

⁉️🤔 Usein kysytyt kysymykset

Miten Redux Framework eroaa Carbon Fieldsistä, ACF Options Pagesista ja muista ratkaisuista?

Redux tarjoaa 49 kenttätyyppiä "suoraan paketista" (verrattuna noin 25:een Carbon Fieldsissä ja noin 30:een ACF Prossa) ja keskittyy nimenomaan teeman asetuspaneleihin, ei artikkelien metakenttiin. ACF Options Pages on lisäosa metakenttämoottorin päälle, kun taas Redux suunniteltiin alun perin optiopaneeleja varten: sisäänrakennettu tuonti/vienti, kääntäjä, live-esikatselu customizerissa, dynaaminen CSS Google Fonts -tuella. Carbon Fields on hengeltään lähempänä, mutta vaatii Composerin ja nimiavaruudet, mikä on monissa hosting-ympäristöissä este. Johtopäätös: jos käytät jo ACF:ää metakenttiin, ota ACF Options Pages välttääksesi entiteettien moninkertaistamisen; jos rakennat teemaa alusta alkaen ja tarvitset tehokkaan optiopaneelin, Redux antaa enemmän ominaisuuksia ilmaiseksi.

Toimiiko Redux Framework lohkoteemojen (Full Site Editing) kanssa?

Kyllä, mutta tietyin varauksin. Redux tuottaa asetuspaneelin klassisen hallintaliittymän kautta (Settings API), ei sivustoeditorin kautta. Hybridilähestymistavassa, lohkoteema plus Redux-paneeli yleisille asetuksille (värit, typografia, analytiikkaskriptit), yhdistelmä toimii. Versiosta 4.5.11 alkaen suoraa integraatiota theme.json-tiedostoon ei ole toteutettu: arvot täytyy hakea templaateissa mytheme_get_option()-funktiolla ja upottaa CSS-muuttujina. Puhtaassa FSE-ympäristössä, jossa kaikkien asetusten tulisi sijaita sivustoeditorissa, Redux on tarpeeton; klassisille ja hybriditeemoille se on yksi parhaista vaihtoehdoista.

Mitä tehdä, jos Redux on ristiriidassa toisen samaa kirjastoa käyttävän lisäosan kanssa?

Tämä on tunnettu "kaksoissisällytyksen" ongelma. Tarkistus if ( ! class_exists( 'Redux' ) ) ennen require_once-kutsua takaa, että kehys latautuu täsmälleen kerran: WordPress suorittaa PHP:tä peräkkäin, ja aivan ensimmäinen require_once tekee myöhemmistä kutsuista vaarattomia. Jos teemasi ja kolmannen osapuolen lisäosa molemmat vetävät Reduxin mukaan, ensin alustettu kopio latautuu, ja molempien tuotteiden paneelit jatkavat toimintaansa. Merkittävässä pääversioerossa yhteensopimattomuus API-tasolla on mahdollinen, korjattavissa päivittämällä jälkeen jäänyt osapuoli nykyiseen julkaisuun.

Tarvitaanko lisenssi Redux Frameworkin käyttämiseen kaupallisessa teemassa?

Ei. Reduxia jaetaan GPLv2-lisenssillä, samalla kuin WordPressiä. Voit vapaasti sisällyttää kehyksen kaupallisiin teemoihin ja lisäosiin, myydä niitä ThemeForestissa, jakaa oman sivustosi kautta. GPLv2:n ainoa rajoitus, johdannaisteosten on myös oltava GPLv2:n alaisia, mutta tämä vaatimus koskee lähdekoodia, ei loppukäyttäjän sivuston sisältöä. Redux Pro (lisäkenttiä, laajennettu customizer, prioriteettituki) on erillinen maksullinen tuote, jota ei vaadita kehyksen toimintaan.

Mitä tehdä, jos WordPress-päivityksen jälkeen Redux-paneeli lakkasi avautumasta?

Skenaario: suuren WP-päivityksen jälkeen valkoinen ruutu teeman asetussivulla. Toimintajärjestys: ensin, tarkista että Redux-versiosi on vähintään 4.5.11 (yhteensopivuus WP 7.0:n kanssa). Toiseksi, laita hetkeksi päälle 'dev_mode' => true ja katso PHP-virhetulostetta asetusnäytöllä, Redux näyttää dev-tilassa yksityiskohtaisen lokin. Kolmanneksi, jos virhe tulvii tietystä kentästä, tarkista käytätkö vanhentunutta tyyppiä (search poistettu Redux 3.x:ssä, divide uudelleennimetty). Ajantasainen kenttäluettelo aina Redux-dokumentaatiossa.

Kannattaako Redux Frameworkia käyttää vuonna 2026

Redux Framework on kypsä, aktiivisesti tuettu tuote, jonka takana on 32 miljoonaa latausta ja yli 270 avustajan yhteisö GitHubissa. Jos rakennat klassista tai hybridi-WordPress-teemaa ja tarvitset asetuspaneelin, jossa on rikas kenttävalikoima, live-esikatselu customizerissa ja dynaaminen CSS, Redux säästää sinulta viikkojen kehitystyön ja antaa tuloksen, joka täyttää WordPress-tietoturvan standardit (PHPCS, escapointi, validointi).

Arkkitehtonisesti paras tapa integroida on viedä kehys riippuvaan teemalisäosaan require_once-kutsulla ja class_exists-tarkistuksella. Tämä antaa sekä puhtaan koodipohjan, suojan kaksoissisällytyksen ristiriidoilta että läpinäkyvän päivityspolun.

Milloin Reduxia ei tarvita: teet kevyttä teemaa ilman asetuspaneelia; työskentelet puhtaassa FSE-ympäristössä (lohkoteema theme.json-tiedostolla); sinulla on jo ACF käytössä Options Pages -lisäosineen metakenttiä varten. Näissä tapauksissa Reduxin vetäminen mukaan yhden on/off-napin takia on kuin ampuisi tykillä kärpästä: kehys lisää noin 2 Mt teeman kokoon ilman vastaavaa hyötyä.

Ennen työn aloittamista katso virallinen dokumentaatio Redux-kehittäjäsivustolla ja repositorio GitHubissa, siellä voit myös ilmoittaa bugista tai ehdottaa ominaisuutta. Jos tarvitset apua tietyn kenttätyypin tai argumentin kanssa, kirjoita kommentteihin, selvitetään yhdessä.