Pak Jiddat

Read: In the name of thy Lord Who createth, Createth man from a clot. Read: And thy Lord is the Most Bounteous, Who teacheth by the pen, Teacheth man that which he knew not. Nay, but verily man is rebellious That he thinketh himself independent!. Lo! unto thy Lord is the return. (Sura Alalaq 96:8)

Developing WordPress plugins using Pak Php framework - Part 2

Created On: 11 Apr, 2017: 12:21:26 - Tags : content management systems | pak php framework

Introduction

In the first part of this article, I presented the Pak Php Framework and how to use it to create a basic WordPress plugin. In the second part, I will describe more complex features that are often needed in WordPress plugins.

How to Translate your plugin

To translate your plugin, you have to upload the .po and .mo translation files to the languages folder of the plugin. These files contain the text to be translated. The Pak Php framework uses the load_plugin_textdomain WordPress function for loading the plugin translation files. To use the translated text within your plugin you can use the following WordPress translation functions. For example:
$translated_text = __( $text, $domain ); // or
_e( $text, $domain );
To use the translated text inside your JavaScript files, you have to mention the translated text in Configuration.php. This is described in the first part of this article in the section titled How to load custom JavaScript and CSS files. The translated text needs to be given in Configuration.php. It is an array with following keys:
  1. name: It is the name of the JavaScript file that will have access to the translated data.
  2. variable name: It is the name of the JavaScript variable that will contain the translated data. In this example it is WPE_L10n.
  3. data: It is an array of key/value pairs where the key is the name that will be used to access the translated text from JavaScript and value is the translated text.
If you want to access the translated text from a JavaScript file then you have to use following JavaScript code:
WPE_L10n.title_alert;

How to Create a Simple Settings Page for your Plugin

To create a settings page, you have to give following configuration parameters in Configuration.php:
  1. ['wordpress']['use_settings']: Set this to true if you want to have a settings page for your plugin
  2. ['wordpress']['settings_page_title']: Set this to the title of your settings page. It will be displayed as heading on your settings page
  3. ['wordpress']['settings_menu_title']: Set this to the text of the WordPress menu item. Clicking on this menu item will open your settings page
  4. ['wordpress']['settings_menu_permissions']: Set this to the minimum permissions required to access the settings menu
  5. ['wordpress']['settings_page_url']: Set this to the URL of your settings page
  6. ['wordpress']['settings_page_content_callback']: Set this to the callback function that will display the html for your settings page. See the function DisplaySettingsPage in Settings.php for an example of how to implement this function. This function does two things. First it fetches the HTML of the form fields. Next it displays the form fields inside the settings.html template file
  7. ['wordpress']['admin_init_callback']: Set this to the callback function that will initialize your admin page. See the function InitializeAdminPage in Settings.php for an example of this function. The main use of this function is to register the form fields. The registered form fields are fetched and displayed by the DisplaySettingsPage function mentioned above.
The registration of form fields is not required but it is a good practise as it registers your form fields with the WordPress Settings API. The Settings API makes your plugin more secure and also takes care of saving your form fields

Here is a screenshot of the settings page:

Settings page for wordpressexample project

How to create a Dashboard Widget

Creating a Dashboard widget is a two step process. First you have to define a function that registers the Dashboard. The second step is to implement the function that displays the dashboard contents. To define the function that registers the Dashboard, you have to define a custom action called wp_dashboard_setup in Configuration.php. This function registers a dashboard widget. In our example this is the function SetupDashboardWidget in WordPressExample.php. This function calls the function AddDashboardWidget. The second steps is to define the function that displays the contents of the Dashboard widget. This function is called DisplayDashboardWidget and is defined in DashboardWidget.php. This function reads a dashboard template file and echoes its contents. It replaces placeholders in this template file with the title and text given in the settings page. Here is a screenshot of the dashboard widget:

Screenshot of Dashboard Widget

How to Make AJAX Calls

Configuring an AJAX function is a two step process. First you have to define a custom action that starts with wp_ajax inside Configuration.php. For example if you want to call your ajax function dashboardwidget, then your custom action should be called wp_ajax_dashboardwidget. The callback function for this action is the ajax function. The JavaScript AJAX call must include a parameter called action. The value of this parameter should be the name of the AJAX function. In this case it is dashboardwidget. See the file wpe-admin.js for an example of how to make the ajax call using jQuery. jQuery is provided by WordPress, so there is no need to load it in your project. To secure the AJAX calls. For example to prevent unauthorized scripts from making the AJAX call, a parameter called security has to be included with the JavaScript AJAX call. The value of this parameter is a text string. This string can be created using the WordPress function wp_create_nonce. The security parameter needs to be validated inside the ajax function on the server side. It can be validated using the WordPress function check_ajax_referer.

How to Create Custom Post Types and Taxonomies

By default WordPress has posts and categories. A taxonomy is similar to a category. If you want to add your own custom post type or taxonomy, then you have to register it when your plugin is first initialized. This can be done by adding a callback function to the init hook. This function needs to call the WordPress function register_post_type, which registers your custom post type with WordPress. The Pak Php framework takes care of registering your custom post type. To add a new custom post type or taxonomy using the Pak Php framework, you have to first add a custom action for the init hook. This function needs to call the AddNewCustomPostType function. This function is provided by the Pak Php framework in the file Application.php which is in the package \Framework\Wordpress. This function simply creates a new custom post type. You can give parameters to this function that control how the custom post type should work. For example should it have a GUI, should it be publicly searchable, which features should it support and more.

How to Unit Test Your Plugin by Extending the WordPress XML-RPC interface

There are two main options for unit testing WordPress plugins. The first one is to use WP-CLI. This is a command line tool written in PHP that gives access to certain WordPress features. WP-CLI requires access to the console which is not always possible. It works by generating test files and then running PHPUnit on these test files. Another option for unit testing WordPress plugins is to add your test functions to the WordPress XML-RPC interface and then calling the functions from any XML-RPC client. This method is supported by the Pak PHP framework. To add functions to the WordPress XML-RPC interface, you have to first define a callback for the xmlrpc_methods filter in Configuration.php. Your callback function should take one parameter, which is the list of WordPress XML-RPC methods. By adding or removing methods from this parameter you can control which XML-RPC functions are exposed by WordPress. You can just add your test function to this parameter. It is easy to add user name and password checks to your test function. This can be done with the following code:
global $wp_xmlrpc_server;
/** The rpc arguments are escaped */
 $wp_xmlrpc_server->escape( $args );
/** The blog id, user name and password */
 $blog_id  = $args[0];
 $username = $args[1];
 $password = $args[2];
/** If the login info is not correct then an error is returned */
 if (! $user = $wp_xmlrpc_server->login( $username, $password))
  return $wp_xmlrpc_server->error;
The above method receives an array with 3 elements as arguments. The first is the id of your blog. If your blog is not hosting multiple sites, then the blog id parameter should have a value of 1. The second parameter is the user name and the third one is the password. The test functions are defined in Testing.php file in the wordpressexample project. In order to test your WordPress function, you need to define a function that calls the WordPress test function over XML-RPC. In our example, the function that calls the test function is called TestWordPressUnitTest and is defined in Testing.php file in the webexample project. This function uses the xmlrpc PHP extension. This extension is not required and its easy to make XML-RPC call using another option such as php curl. You can also test your XML-RPC function using the XML-RPC Client extension for Google Chrome. See following screenshot:

Google Chrome XML-RPC client

How to create your own shortcodes

To create your own shortcodes you have to first define the shortcode in Configuration.php. Following code defines a short code:
/** The custom wordpress shortcodes are defined */
$this->user_configuration['wordpress']['custom_shortcodes'] = array(
/** Shortcode for displaying sample text */
array("name"=>"get-dashboard-widget-text","callback"=>array("application","GetShortCodeText")),
);
Then you need to implement the shortcode function. The shortcode function takes one argument which is an array containing shortcode parameters. Default values for the shortcode parameters can be given within the shortcode function. For example the following code can be used:
$parameters = shortcode_atts(array('parameter1' => 'default value','parameter2' => 'default value'), $parameters);

How to create frontend sidebar widgets

To create sidebar widgets you have to define the sidebar widget in Configuration.php. Following code defines a sidebar widget:
/** The custom wordpress widgets are defined */
 $this->user_configuration['wordpress']['custom_widgets'] = array(
                                                                   /** Widget for displaying sample text */
                                               		           array("name"=>"WordPress Example Widget",
"class"=>"\WordPressExample\SidebarWidget"));
Next you have to define the widget class that will implement the sidebar widget. In the above example the widget class is called SidebarWidget. This class should extend the \Frameworks\WordPress\Widgets class. This class should implement following functions: GetWidgetInformationRenderFormFields and GetMainWidgetContent. The SidebarWidget.php file in the WordPressExample project implements a sidebar widget

How to include third party scripts

To include third party Php scripts with your WordPress plugin you have to create a vendors folder inside the WordPress plugin folder and download the third party scripts to this folder. You can then access the third party Php scripts by simply adding the class names to the Configuration.php project file. To include third party JavaScript and CSS files, you have to include the path of the CSS or JavaScript file relative to the root folder of your plugin. For example if you have a JavaScript file called test.js inside vendors/third-party-tool folder then you would use the path vendors/third-party-tool/test.js inside your Configuration.php file.

Conclusion

This article described how to create a WordPress plugin using the Pak Php framework. The Pak Php framework was used to develop the Islam Companion plugin hosted on wordpress.org. Hopefully this article increased the interest of the reader in WordPress plugin development and the Pak Php framework.

Related Articles

  1. Creating custom themes for October CMS
  2. Developing WordPress plugins using Pak Php framework - Part 1
  3. Validate your WordPress blog using WordPress XML-RPC API, Php Tidy and Nu HTML Checker
  4. WordPress Deployment with Jenkins and Redmine
  5. Tuning WordPress performance using Varnish
  6. Improving WordPress Performance
  7. Creating your own WordPress themes and plugins
  8. WordPress for small and medium businesses
  9. Some excellant Wordpress Plugins
  10. Managing Php scripts using the Pak Php Framework Admin Tool
  11. How to test Pak Php applications
  12. Writing command line scripts using Pak Php framework
  13. Pak Php framework
  14. Developing your own Php Utilities Framework