BaseSettingsPage - Page-Carbajal/WPExpress GitHub Wiki

Class WPExpress\Admin\BaseSettingsPage

The BaseSettingsPage class is an abstract class you can extend to create your own custom Settings Pages in WordPress.

Important: I am currently working on the code for autoloading values. Current code will still work. But as of version 1.5.0 it's recommended not to use the fields->setValue method, unless you absolutely need to.

1. The Constructor method

Following Convention Over Configuration the User Capabilities, Top Parent Menu, Page Slug and the Templates Path are pre-configured for you.

The constructor method only requests for 1 parameter. The Page Title.

You can get away with as little as 2 lines of code for your own constructor.

<?php

namespace MyProject;

use WPExpress\Admin\BaseSettingsPage;

class OptionsPage extends BaseSettingsPage
{
    public function __construct()
    {
        parent::__construct('Theme Settings', 'manage_options');
        // $this->setPageDescription('Built with WPExpress'); // Show me some loooove!
        $this->addPageOptions();
    }

    private function addPageOptions()
    {
        // Code to add Page Options
    }
}

2. setTopParentMenu method

Very important.

By default your Settings Page will be loaded under the Tool's menu in WordPress.

To change the location of your page indicate one of the following options:

dashboard. This option will place a link to your Settings Page under the Dashboard menu
pages This option will place a link to your Settings Page under the Page menu
posts This option will place a link to your Settings Page under the Posts menu
plugins This option will place a link to your Settings Page under the Plugins menu
settings This option will place a link to your Settings Page under the Settings menu
theme This option will place a link to your Settings Page under the Theme menu
tools This option will place a link to your Settings Page under the Tools menu. This is the Default
top This option will place a link to your Settings Page as a Top Level Menu
users This option will place a link to your Settings Page under the Users menu

$this->setTopParentMenu('theme');

3. registerPage method

This method creates the menu and registers the render filter. Call it only if you are not using the parent::__construct method.

4. addMenuItem method

This method registers the action that will render your Settings Page. You do not need to call it.

5. setPageTitle method

Set the title for your Settings Page.

$this->setPageTitle('My Awesome Theme Settings');

6. setPageDescription method

This is a very simple method. It allows you to set a description message for your Settings Page.

$this->setPageDescription('Built with WPExpress');

7. setCustomTemplatePath method

Use this method to indicate the name of your templates folder.

Remember you have to point to the top level templates folder, and within this folder create either a mustache or twig folder with writing permissions for your web user.

The RenderEngine will try to create cache directories inside the mustache or twig directories. This speeds up the process of rendering your page.

$this->setCustomTemplatePath( get_stylesheet_directory() . "/templates" );

8. useMustacheTemplates method

This method indicates your Settings Page you are working with mustache files to render the HTML.

$this-> useMustacheTemplates();

The class BaseSettingsPage defaults to mustache.

9. useTwigTemplates method

This method is same as the previous one, it indicates your Settings Page to use twig templates instead of mustache.

$this-> useTwigTemplates();

10. fields object

The Fields Object is a WPExpress/UI/FieldCollection object.

Use this object to add your options to the Settings Page

Example

<?php 

use WPExpress\Admin\BaseSettingsPage;

class MyPage extends BaseSettingsPage
{
    public function __construct()
    {
        // Configuration code
        $this->addPageOptions();
    }

    private function addPageOptions()
    {
        // Add a text input
        $this->fields->addTextInput('my-text')->setID('something')->addLabel('My Text!')->setID('my-big-text');
        // Add a select field with a label 
        $this->fields->addSelect('my-select',array('Uno', 'Dos', 'Tres'));
        $this->fields->addLabel('My Spanish Numero');
        $this->fields->setID('spanish-numero');
        // Add a text area
        $this->fields->addTextArea('large-text')->setID('something')->addLabel('My Text!')->setID('my-big-text');

        // Change the id of the text input
        $this->fields('my-text')->setID('little-text');

        return $this;
    }
}

The fields object doesn't actually build any HTML, it is a dictionary of sorts. Storing all of the field data until it needs to be rendered.

Notice how $fields can invoke methods like setID and setAttribute. This is possible because by default it assigns the properties to the last created element. If you need to change a property on a previous field you would call the fields method.

Visit the FieldCollection page for more information.

11. fields method

This is a helper method to set the current field index and allow you to set properties to the object.

Example

You have declared all of your options and now want to set a custom id attribute for the field email


$this->fields('email')->setID('contact-us-email');

Visit the FieldCollection page for more information.

12. getOptionValue method

This, is one of the most important methods on this class.

Use this method to access any of your option values.

$options = new MyOptions(); //MyOptions is a class extending the BaseSettingsPage

echo $option->getOptionValue('my-theme-option');
echo $option->getOptionValue('my-theme-option-2');

13. render method

This method returns the HTML output by calling WPExpress/UI/RenderEngine to render your Settings Page.

It gets hooked to a WordPress action on the addMenuItem class.

https://codex.wordpress.org/Creating_Options_Pages#Example_.232