Skip to content

Commit 7fe85fc

Browse files
author
hsehszroc
committed
added readme file
1 parent 77f8b5a commit 7fe85fc

File tree

1 file changed

+328
-0
lines changed

1 file changed

+328
-0
lines changed

‎README.md‎

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
<!--
2+
<!-- ***
3+
https://www.markdownguide.org/basic-syntax/#reference-style-links
4+
-->
5+
[![Contributors][contributors-shield]][contributors-url]
6+
[![Forks][forks-shield]][forks-url]
7+
[![Stargazers][stars-shield]][stars-url]
8+
[![Issues][issues-shield]][issues-url]
9+
[![GPL License][license-shield]][license-url]
10+
[![LinkedIn][linkedin-shield]][linkedin-url]
11+
<!-- ***
12+
<!-- -->
13+
14+
15+
<!-- PROJECT LOGO -->
16+
<br />
17+
<p align="center">
18+
<a href="https://github.com/TheWebSolver/tws-setting-framework">
19+
<img src="images/official_logo.png" alt="Logo" width="80" height="80">
20+
</a>
21+
22+
<h3 align="center">TWS Setting Framework</h3>
23+
<p align="center">
24+
CREATE ADMIN PAGES WITH SECTIONS -|- CONTENTS/FIELDS WITHIN EACH SECTION
25+
<br/>
26+
This plugin is a framework meant for creating settting pages and setting fields in WordPress admin dashboard.
27+
</p>
28+
</p>
29+
30+
<!-- TABLE OF CONTENTS -->
31+
## Table of Contents
32+
33+
* [About the Project](#about-the-project)
34+
* [Preface](#preface)
35+
* Getting Started
36+
* [Prerequisites](#prerequisites)
37+
* [Installation](#installation)
38+
* [Usage](#usage)
39+
* [Example Code](#example-code)
40+
* [Debug Mode](#debug-mode)
41+
* [License](#license)
42+
* [Contact](#contact)
43+
* [Acknowledgement](#acknowledegement)
44+
45+
46+
47+
<!-- ABOUT THE PROJECT -->
48+
## About The Project
49+
<small>[Top↑](#table-of-contents)</small>
50+
51+
#### Screenshot 1
52+
![Screenshot 1][screenshot-1]
53+
54+
#### Screenshot 2
55+
![Screenshot 2][screenshot-2]
56+
57+
### Preface
58+
<small>[Top↑](#table-of-contents)</small>
59+
60+
This framework is a ready to use plugin or to include inside your own plugin/theme for anyone who needs to create: <br/>
61+
- WordPress Admin pages (**_Welcome | Fields Demo_** navigations at left side in screenshot 1 above)
62+
- Different Sections within a page (tabs **_Getting Started | Hooks & Filters | Recommended Setup | Ready to Go?_** inside **_Welcome_** page in screenshot 1 above)
63+
- Contents within each section (tab content of **_Getting Started_** inside **_Welcome_** page in screenshot 1 above)
64+
- Contents and/or setting fields within each section (tab content and fields of **_Ready to Go?_** inside **_Welcome_** page in screenshot 2 above)
65+
66+
67+
<!-- GETTING STARTED -->
68+
## Getting Started
69+
70+
### Prerequisites
71+
<small>[Top↑](#table-of-contents)</small>
72+
73+
#### Recommended Setup (Built using)
74+
75+
This plugin is developed using:
76+
77+
* [Code Editor - **Visual Studio Code (VS Code)**](https://code.visualstudio.com/download) - Loved by most developers for coding
78+
* [VS Code extension - **WordPress Snippets**](https://github.com/jason-pomerleau/vscode-wordpress-toolbox) - Snippets for every WordPress function, class and constant.
79+
* [VS Code extension - **PHP Intelephense**](https://github.com/bmewburn/vscode-intelephense) - Essential features for productive PHP development
80+
* [VS Code extension - **Comment Anchors**](https://github.com/ExodiusStudios/vscode-comment-anchors) - Find anchors for WordPress **Action** & **Filter** hooks (and other anchors too) added in this framework's files
81+
* [VS Code Font - **Fira Code**](https://github.com/tonsky/FiraCode) - Download and install to your OS and then use from VS Code font family setting
82+
* [WordPress Plugin - **Show Hooks**](https://wordpress.org/plugins/show-hooks/) - See visual representation of WordPess action and filter hooks.
83+
84+
### Installation
85+
<small>[Top↑](#table-of-contents)</small>
86+
87+
#### For using as plugin
88+
89+
- Download or clone this repo into plugins directory using:
90+
```sh
91+
git clone https://github.com/TheWebSolver/tws-setting-framework.git
92+
```
93+
#### For using inside your plugin/theme
94+
- Download or clone this repo into appropriate directory inside your plugin/theme using:
95+
```sh
96+
git clone https://github.com/TheWebSolver/tws-setting-framework.git
97+
```
98+
- Include the framework file **_tws-setting-framework.php_** from your main plugin file
99+
```sh
100+
include_once 'path_to_framework_directory/tws-setting-framework.php';
101+
```
102+
103+
## Usage
104+
<small>[Top↑](#table-of-contents)</small>
105+
106+
- This framework uses PHP Namespace:
107+
```php
108+
namespace TheWebSolver\Plugin\Core\Framework;
109+
```
110+
111+
- This framework creates main menu with title as **"The Web Solver"**. In file [init.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/init.php), see function:
112+
```php
113+
function tws_setting_framework_main_menu();
114+
```
115+
>All submenus are created inside it by default if child-class args doesn't define the main menu slug.
116+
117+
- Child-classes can be found inside [templates](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates) directory. Files that create child-classes are [with-fields.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/with-fields.php) and [without-fields.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/without-fields.php).
118+
>These are example codes and can be used as boilerplate for creating your own child-class.
119+
120+
#### NOTE:
121+
122+
>Regarding documentation, once it is 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](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/contents)_.
123+
124+
>_(See screenshot 1 above for reference on how content gets displayed)_
125+
126+
>There is thorough commenting on all of the core files which can also be considered as in-file documentation.
127+
128+
### Example Code
129+
<small>[Top↑](#table-of-contents)</small>
130+
131+
- File [without-fields.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/without-fields.php) contains child-class `Without_Fields` that extends the parent class `Setting_Component` The parent class is in file [setting-component.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/setting/setting-component.php). It has basically everything this framework can do such as:
132+
- creating submenu page _(see method `__construct`)_
133+
- creating sections as tabs inside that submenu page _(see method `sections`)_
134+
- creating contents and/or fields on each section (as tab) of that submenu page _(see method `sections`)_
135+
>For visual representation on how it looks, see screenshot 1 above.
136+
137+
>For code structure, see PHP code below.
138+
139+
```php
140+
<?php
141+
/**
142+
* Submenu page with menu title as "Welcome" under main menu "The Web Solver"
143+
*/
144+
145+
namespace TheWebSolver\Plugin\Core\Framework;
146+
147+
// Exit if accessed directly
148+
if ( ! defined( 'ABSPATH' ) ) exit;
149+
150+
final class Without_Fields extends Setting_Component {
151+
152+
/** Constructor */
153+
public function __construct() {
154+
parent::__construct(
155+
[
156+
__CLASS__ => [
157+
'menu_slug' => '', // uses default if not set
158+
'page_title' => __( 'Welcome', 'tws-core' ),
159+
'menu_title' => __( 'Welcome', 'tws-core' ),
160+
'cap' => 'read', // wordpress user capability to view page and edit/update page section fields
161+
'slug' =>'tws_welcome_page', // submenu page slug
162+
'icon' => HZFEX_Setting_Framework_Url . 'assets/graphics/files-icon.svg', // icon that displays on before page navigation title (files icon before page title Welcome in screenshot 1)
163+
]
164+
]
165+
);
166+
}
167+
168+
protected function sections() {
169+
$sections = [
170+
'welcome' => [
171+
'title' => __( 'Getting Started', 'tws-core' ),
172+
'tab_title' => __( 'Getting Started', 'tws-core' ),
173+
'desc' => 'Some description',
174+
'callback' => [ $this, 'welcome_callback' ], // callback can be used this way
175+
],
176+
'hooks' => [
177+
'title' => __( 'Hooks/Filters', 'tws-core' ),
178+
'tab_title' => __( 'Hooks & Filters', 'tws-core' ),
179+
'callback' => function() { if( file_exists( HZFEX_Setting_Framework_Path. 'templates/contents/hooks-filters.php' ) ) include_once HZFEX_Setting_Framework_Path. 'templates/contents/hooks-filters.php'; }, // callback can be used this way also
180+
],
181+
'recommendation' => [
182+
'title' => __( 'Recommendation', 'tws-core' ),
183+
'tab_title' => __( 'Recommended Setup', 'tws-core' ),
184+
'callback' => function() { if( file_exists( HZFEX_Setting_Framework_Path . 'templates/contents/recommendations.php' ) ) include_once HZFEX_Setting_Framework_Path . 'templates/contents/recommendations.php'; },
185+
],
186+
'tws_mixed_section' => [
187+
'title' => __( 'This title is only visible when fields are set.', 'tws-core' ), // only shows when "fields" are set.
188+
'tab_title' => __( 'Ready to Go?', 'tws-core' ),
189+
'desc' => sprintf( '<div>%1$s</div><div><small><em>%2$s <code>templates/with-fields.php</code></em></small></div>',
190+
__( 'This description is only visible when fields are set.', 'tws-core' ),
191+
__( 'Enabling the switch below (actually it is a checkbox field type with style customization) will instantiate another child class on file', 'tws-core' ),
192+
), // only shows when "fields" are set.
193+
'callback' => function() { echo 'This is just a callback like other three section tabs in this page.'; },
194+
'fields' => [
195+
'tws_enable_fields' => [
196+
'label' => __( 'Enable another child-class?', 'tws-core' ),
197+
'desc' => __( 'You should definitely enable this to test other types of input fields.', 'tws-core' ),
198+
'type' => 'checkbox',
199+
'class' => 'hz_switcher_control',
200+
'default' => 'off'
201+
],
202+
],
203+
],
204+
];
205+
206+
return $sections;
207+
}
208+
209+
/**
210+
* Sets content for "Getting Started" section in page "Welcome".
211+
*/
212+
public function welcome_callback() {
213+
if( file_exists( HZFEX_Setting_Framework_Path. 'templates/contents/welcome.php' ) ) include_once HZFEX_Setting_Framework_Path. 'templates/contents/welcome.php';
214+
}
215+
}
216+
217+
// initialize this submenu page.
218+
new Without_Fields();
219+
```
220+
- File [with-fields.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/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.
221+
222+
>Please check the [with-fields.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/with-fields.php) file to view the code structure.
223+
224+
>For refresher, the parent class is in file [setting-component.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/setting/setting-component.php).
225+
226+
- >For visual presentation on how it works, see screenshot 3, 4, 5 and 6 below.
227+
228+
#### Screenshot 3 - General Fields
229+
![Screenshot 3][screenshot-3]
230+
231+
#### Screenshot 4 - Multi selection fields, wysiwyg, password, color, etc. fields
232+
![Screenshot 4][screenshot-4]
233+
234+
#### Screenshot 5 - Fields that are applied custom styling, Select2 plugin for select fields.
235+
![Screenshot 5][screenshot-5]
236+
237+
- To get the saved field value, use:
238+
239+
```php
240+
Settings_API::get_option( $field_id, $section_id, $default );
241+
```
242+
>For example - from the child class [Without_Fields↑](#example-code) above, if you want to get value of the field **`tws_enable_fields`**, use:
243+
```php
244+
<?php
245+
246+
namespace TheWebSolver\Plugin\Core\Framework;
247+
248+
// use TheWebSolver\Plugin\Core\Framework\Settings_API; // uncomment this if you are not using above namespace.
249+
250+
$enabled = Settings_API::get_option( 'tws_enable_fields', 'tws_mixed_section', 'off' );
251+
```
252+
253+
### Debug Mode
254+
<small>[Top↑](#table-of-contents)</small>
255+
256+
- For debugging purpose, you can define debug constant to `true`.
257+
258+
On file [tws-setting-framework.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/tws-setting-framework.php) at around **_line 32_**, change `false` to `true`.
259+
260+
```php
261+
define( 'HZFEX_SETTING_FRAMEWORK_DEBUG_MODE', true );
262+
```
263+
264+
>For example, once set to `true`, it will display sections and fields set at child-class [without-fields.php](https://github.com/TheWebSolver/tws-setting-framework/tree/master/templates/without-fields.php) from:
265+
266+
```php
267+
protected function sections();
268+
```
269+
#### Screenshot 6 - Debug mode to view codes and saved field values that are added from child-classes
270+
![Screenshot 6][screenshot-6]
271+
272+
<!-- LICENSE -->
273+
## License
274+
<small>[Top↑](#table-of-contents)</small>
275+
276+
Distributed under the GNU General Public License v3.0 (or later) License. See **[LICENSE](https://github.com/TheWebSolver/tws-setting-framework/blob/master/LICENSE)** file for more information.
277+
278+
279+
280+
<!-- CONTACT -->
281+
## Contact
282+
<small>[Top↑](#table-of-contents)</small>
283+
284+
```sh
285+
----------------------------------
286+
DEVELOPED-MAINTAINED-SUPPPORTED BY
287+
----------------------------------
288+
███║ ███╗ ████████████████
289+
███║ ███║ ═════════██████╗
290+
███║ ███║ ╔══█████═╝
291+
████████████║ ╚═█████
292+
███║═════███║ █████╗
293+
███║ ███║ █████═╝
294+
███║ ███║ ████████████████╗
295+
╚═╝ ╚═╝ ═══════════════╝
296+
```
297+
298+
Shesh Ghimire - [@hsehszroc](https://twitter.com/hsehszroc)
299+
300+
Project Link: [https://github.com/TheWebSolver/tws-setting-framework](https://github.com/TheWebSolver/tws-setting-framework)
301+
302+
303+
<!-- MARKDOWN LINKS & IMAGES -->
304+
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
305+
[contributors-shield]: https://img.shields.io/github/contributors/TheWebSolver/repo.svg?style=flat-square
306+
[contributors-url]: https://github.com/TheWebSolver/repo/graphs/contributors
307+
[forks-shield]: https://img.shields.io/github/forks/TheWebSolver/repo.svg?style=flat-square
308+
[forks-url]: https://github.com/TheWebSolver/tws-setting-framework/network/members
309+
[stars-shield]: https://img.shields.io/github/stars/TheWebSolver/repo.svg?style=flat-square
310+
[stars-url]: https://github.com/TheWebSolver/tws-setting-framework/stargazers
311+
[issues-shield]: https://img.shields.io/github/issues/TheWebSolver/repo.svg?style=flat-square
312+
[issues-url]: https://github.com/TheWebSolver/tws-setting-framework/issues
313+
[license-shield]: https://www.gnu.org/graphics/gplv3-or-later-sm.png
314+
[license-url]: https://github.com/TheWebSolver/repo/blob/master/LICENSE.txt
315+
[linkedin-shield]: https://img.shields.io/badge/LinkedIn-blue?style=flat-square&logo=linkedin&color=blue
316+
[linkedin-url]: https://www.linkedin.com/in/sheshgh/
317+
[screenshot-1]: images/getting-started.png
318+
[screenshot-2]: images/ready-to-go.png
319+
[screenshot-3]: images/simple-fields.png
320+
[screenshot-4]: images/advanced-fields.png
321+
[screenshot-5]: images/stylized-fields.png
322+
[screenshot-6]: images/debug.png
323+
324+
<!-- ACKNOWLEDGEMENT -->
325+
## Acknowledegement
326+
<small>[Top↑](#table-of-contents)</small>
327+
328+
- >This project uses base for Settings_API from [wordpress-settings-api-class](https://github.com/tareq1988/wordpress-settings-api-class).

0 commit comments

Comments
 (0)