TWS Setting Framework

CREATE ADMIN PAGES WITH SECTIONS -|- CONTENTS/FIELDS WITHIN EACH SECTION
This plugin is a framework meant for creating settting pages and setting fields in WordPress admin dashboard.

Table of Contents

• About the Project
  • Preface
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Example Code
  • Debug Mode
• License
• Contact
• Acknowledgement

About The Project

Top↑

Screenshot 1

Screenshot 2

Preface

Top↑

This framework is a ready to use plugin (if not building your own plugin or theme) or to include inside your own plugin/theme for anyone who needs to create:

• WordPress Admin pages (Welcome | Fields Demo navigations at left side in screenshot 1 above)
• Different Sections within a page (tabs Getting Started | Hooks & Filters | Recommended Setup | Ready to Go? inside Welcome page in screenshot 1 above)
• Contents within each section (tab content of Getting Started inside Welcome page in screenshot 1 above)
• Contents and/or setting fields within each section (tab content and fields of Ready to Go? inside Welcome page in screenshot 2 above)

Getting Started

Prerequisites

Top↑

Recommended Setup (Built using)

This plugin is developed using:

• Code Editor - Visual Studio Code (VS Code) - Loved by most developers for coding.
• VS Code extension - WordPress Snippets - Snippets for every WordPress function, class and constant.
• VS Code extension - PHP Intelephense - Essential features for productive PHP development.
• VS Code extension - Comment Anchors - Find anchors for WordPress Action & Filter hooks (and other anchors too) added in this framework's files.
• VS Code Font - Fira Code - Free monospaced font with programming ligatures. Set it from VS Code font family.
• WordPress Plugin - Show Hooks - See visual representation of WordPess action and filter hooks.

Installation

Top↑

For using as plugin

change with-fields.php and without-fields.php to your requirement.

• Download or clone this repo into plugins directory using:

  git clone https://github.com/TheWebSolver/tws-setting-framework.git

For using inside your plugin/theme

• Download or clone this repo into appropriate directory inside your plugin/theme using:

  git clone https://github.com/TheWebSolver/tws-setting-framework.git

• Include the framework file tws-setting-framework.php from your plugin/theme file

  require_once 'path_to_framework_directory/tws-setting-framework.php';

Usage

Top↑

• This framework uses PHP Namespace:

  namespace TheWebSolver\Core\Setting;

• This framework creates main menu with title as "The Web Solver". In file init.php, see function:

  function tws_setting_framework_main_menu();

  All submenus are created inside it by default if child-class args doesn't define the main menu slug.

• Child-classes can be found inside templates directory. Files that create child-classes are with-fields.php and without-fields.php.

  These are example codes and can be used as boilerplate for creating your own child-class.

NOTE:

Regarding documentation, once activated, navigate to Welcome submenu page which has four sections as tabs, first three of them are documentation tabs. Contents in these three tabs are added from files that are inside directory templates/contents.

(See screenshot 1 above for reference on how content gets displayed)

There is thorough commenting on all of the core files which can also be considered as in-file documentation.

Example Code

Top↑

• File without-fields.php contains child-class Without_Fields that extends the parent class Setting_Component The parent class is in file setting-component.php. It has basically everything this framework can do such as:

  • creating submenu page (see method __construct)
  • creating sections as tabs inside that submenu page (see method sections)
  • creating contents and/or fields on each section (as tab) of that submenu page (see method sections)

  For visual representation on how it looks, see screenshot 1 above.

  For code structure, see PHP code below.

  <?php
  /**
  * Submenu page with menu title as "Welcome" under main menu "The Web Solver"
  */
  
  namespace TheWebSolver\Core\Setting;
  
  // Exit if accessed directly
  if ( ! defined( 'ABSPATH' ) ) exit;
  
  final class Without_Fields extends Setting_Component {
  
      /** Constructor */
      public function __construct() {
          parent::__construct(
              [
                  __CLASS__ => [
                      'menu_slug'     => '', // uses default if not set
                      'page_title'    => __( 'Welcome', 'tws-core' ),
                      'menu_title'    => __( 'Welcome', 'tws-core' ),
                      'cap'           => 'read', // wordpress user capability to view page and edit/update page section fields
                      'slug'          =>'tws_welcome_page', // submenu page slug
                      'icon'          => HZFEX_SETTING_URL . 'assets/graphics/files-icon.svg', // icon that displays on before page navigation title (files icon before page title Welcome in screenshot 1)
                  ]
              ]
          );
      }
  
      protected function sections() {
          $sections = [
              'welcome' => [
                  'title'     => __( 'Getting Started', 'tws-core' ),
                  'tab_title' => __( 'Getting Started', 'tws-core' ),
                  'desc'      => 'Some description',
                  'callback'  => [ $this, 'welcome_callback' ], // callback can be used this way
              ],
              'hooks'   => [
                  'title'     => __( 'Hooks/Filters', 'tws-core' ),
                  'tab_title' => __( 'Hooks & Filters', 'tws-core' ),
                  'callback'  => function() { if( file_exists( HZFEX_SETTING_PATH. 'templates/contents/hooks-filters.php' ) ) include_once HZFEX_SETTING_PATH. 'templates/contents/hooks-filters.php'; }, // callback can be used this way also
              ],
              'recommendation' => [
                  'title'      => __( 'Recommendation', 'tws-core' ),
                  'tab_title'  => __( 'Recommended Setup', 'tws-core' ),
                  'callback'   => function() { if( file_exists( HZFEX_SETTING_PATH . 'templates/contents/recommendations.php' ) ) include_once HZFEX_SETTING_PATH . 'templates/contents/recommendations.php'; },
              ],
              'tws_mixed_section' => [
                  'title'         => __( 'This title is only visible when fields are set.', 'tws-core' ), // only shows when "fields" are set.
                  'tab_title'     => __( 'Ready to Go?', 'tws-core' ),
                  'desc'          => sprintf( '<div>%1$s</div><div><small><em>%2$s <code>templates/with-fields.php</code></em></small></div>',
                  __( 'This description is only visible when fields are set.', 'tws-core' ),
                  __( 'Enabling the switch below (actually it is a checkbox field type with style customization) will instantiate another child class on file', 'tws-core' ),
              ), // only shows when "fields" are set.
                  'callback'      => function() { echo 'This is just a callback like other three section tabs in this page.'; },
                  'fields'        => [
                      'tws_enable_fields' => [
                          'label'     => __( 'Enable another child-class?', 'tws-core' ),
                          'desc'      => __( 'You should definitely enable this to test other types of input fields.', 'tws-core' ),
                          'type'      => 'checkbox',
                          'class'     => 'hz_switcher_control',
                          'default'   => 'off'
                      ],
                  ],
              ],
          ];
  
          return $sections;
      }
  
      /**
       * Sets content for "Getting Started" section in page "Welcome".
       */
      public function welcome_callback() {
          if( file_exists( HZFEX_SETTING_PATH. 'templates/contents/welcome.php' ) ) include_once HZFEX_SETTING_PATH. 'templates/contents/welcome.php';
      }
  }
  
  // initialize this submenu page.
  new Without_Fields();

• File with-fields.php contains child-class With_Fields that extends the parent class Setting_Component. It contains all supported setting fields and can be used as boilerplate.

  Please check the with-fields.php file to view the code structure.

  For refresher, the parent class is in file setting-component.php.

• For visual representation on how section and field gets displayed, see screenshot 3, 4 and 5 below.

Screenshot 3 - General Fields

Screenshot 4 - Multi selection fields, wysiwyg, password, color, etc. fields

Screenshot 5 - Fields that are applied custom styling, Select2 plugin for select fields.

• To get the saved field value, use:

  Settings_API::get_option( $field_id, $section_id, $default );

  For example - from the child class Without_Fields↑ above, if you want to get value of the field tws_enable_fields, use:

  <?php
  
  namespace TheWebSolver\Core\Setting;
  
  // use TheWebSolver\Core\Setting\Settings_API; // uncomment this if you are not using above namespace.
  
  $enabled = Settings_API::get_option( 'tws_enable_fields', 'tws_mixed_section', 'off' );

Debug Mode

Top↑

• For debugging purpose, you can define debug constant to true.

  On file tws-setting-framework.php at around line 32, change contstant value from false to true. For visual representation, see screenshot 6 below.

  define( 'HZFEX_SETTING_FRAMEWORK_DEBUG_MODE', true );

  For example, once set to true, it will display sections and fields set at child-class without-fields.php from:

  protected function sections();

  Screenshot 6 - Debug mode to view codes and saved field values that are added from child-classes

  

License

Top↑

Distributed under the GNU General Public License v3.0 (or later) License. See LICENSE file for more information.

Contact

Top↑

----------------------------------
DEVELOPED-MAINTAINED-SUPPPORTED BY
----------------------------------
███║     ███╗   ████████████████
███║     ███║   ═════════██████╗
███║     ███║        ╔══█████═╝
 ████████████║      ╚═█████
███║═════███║      █████╗
███║     ███║    █████═╝
███║     ███║   ████████████████╗
╚═╝      ╚═╝    ═══════════════╝

Shesh Ghimire - @hsehszroc

Project Link: https://github.com/TheWebSolver/tws-setting-framework

Acknowledegement

Top↑

• This project uses base for Settings_API from wordpress-settings-api-class.