Differences

This shows you the differences between two versions of the page.

--- hello_world_plugin_extended [2017/01/21 20:06]
lokothodida [Create the file structure]
+++ hello_world_plugin_extended [2017/01/22 21:21]
lokothodida [hello_world/common_functions.php]
@@ Line 7: / Line 7: @@
   * Show how to save data to the ''data/other/'' path
-===== Create the file structure =====
+===== File structure =====
+Create the following files/folders:
 <code>
 - hello_world.php
@@ Line 20: / Line 22: @@
 ===== hello_world.php =====
+Here is where we register the plugin. We shall start out by defining some useful constants (this will be cleaner than defining global variables like ''$thisfile'' and referencing them later - just give the constants informative names):
-<file php hello_world.php>
+<code php>
 <?php
+// === Constants ===
+define('HELLO_WORLD', basename(__FILE__, '.php'));                              // Plugin ID
+define('HELLO_WORLD_PLUGINPATH', GSPLUGINPATH . HELLO_WORLD . '/');             // Path to the plugin's assets folder
+define('HELLO_WORLD_CONFIGFILE', GSDATAOTHERPATH . 'hello_world_config.json');  // File name for the plugin's user-configuration file
+</code>
+Next, we load the internationalized strings that are in the plugin's ''/lang'' directory (which we will define soon):
+<code php>
+// === Internationalization ===
+i18n_merge(HELLO_WORLD) || i18n_merge(HELLO_WORLD, 'en_US');  // Loads English language file by default
+</code>
+We will define a number of helpful functions in a separate file, ''common_functions.php'', and load them at this point:
+<code php>
+// === Load functions ===
+require_once(HELLO_WORLD_PLUGINPATH . 'common_functions.php');
+</code>
+Then we register the plugin. Note that this uses one of the assumed functions that we will define, ''hello_world_i18n'', where there will be language-dependent strings (namely for the plugin name and description):
+<code php>
+// === Plugin, Hook and Filter Registration  ===
+register_plugin(
+  HELLO_WORLD,                                // Plugin id
+  hello_world_i18n('PLUGIN_NAME'),            // Plugin name
+  '0.1.0',                                    // Plugin version
+  'You',                                      // Plugin author
+  'http://www.you.com',                       // Author website
+  hello_world_i18n('PLUGIN_DESCRIPTION'),     // Plugin description
+  'theme',                                    // Page type - on which admin tab to display
+  'hello_world_admin'                         // Main function (administration)
+);
+</code>
+Lastly, we register the plugin hooks - in this case, one for loading a sidebar menu item, and another for the theme footer:
+<code php>
+// Echoes message in footer
+add_action('theme-footer', 'hello_world_footer');
+// Creates sidebar link
+add_action('theme-sidebar', 'createSideMenu', array(HELLO_WORLD, hello_world_i18n('PLUGIN_SIDEBAR')));
+</code>
+This is the full file:
+<file php hello_world.php>
 <?php
 // === Constants ===
@@ Line 55: / Line 107: @@
 ===== hello_world/lang/en_US.php =====
+The PHP files in the ''/lang'' directory just need to define an ''$i18n'' array of internationalized strings. Once we've merged the plugin's language strings with ''i18n_merge'', these strings will be available via ''i18n('hello_world/STRING_NAME', true)'', which we will alias  ''hello_world_i18n('STRING_NAME')''
 <file php en_US.php>
@@ Line 70: / Line 123: @@
 </file>
-===== hello_world/admin.php =====
+===== hello_world/common_functions.php =====
-<file php admin.php>
+The first functions that we need to define are ''hello_world_i18n'' (''i18n'' alias), ''hello_world_admin'' (displays the administration panel) and ''hello_world_footer'' (echoes the message into the theme footer). The latter two will just be stubs that get filled in later:
-<h3><?php echo hello_world_i18n('ADMIN'); ?></h3>
-<form method="post">
+<code php>
-  <input name="message" value="<?php echo $config['message']; ?>">
+// Alias for getting i18n strings for this plugin
-  <button name="save-configuration"><?php echo hello_world_i18n('SAVE'); ?></button>
+function hello_world_i18n($key) {
-</form>
+  return i18n_r(HELLO_WORLD . '/' . $key);
-</file>
+}
+// Administration panel
+function hello_world_admin() {
+  // ...
+}
+// Hook for the theme footer
+function hello_world_footer() {
+  // ...
+}
+</code>
+Now consider the operations that we want to have for the plugin data. The administrator will be able to create a custom message, save it, and then this message will be printed in the theme footer. So we shall create functions for saving this message into a file the ''data/other'' folder. To future-proof this plugin, we will save the data as ''key=>value'' pairs, so the message will be a value with a designated key (ideally the key ''message''):
+<code php>
+// Given an array of key=>value mappings, save that data to the configuration file
+function hello_world_save_config($config = array()) {
+  $file     = HELLO_WORLD_CONFIGFILE;
+  $contents = json_encode($config);            // Encodes the array into a valid JSON string
+  return file_put_contents($file, $contents);  // Saves the JSON string into the configuration JSON file
+}
+// Load plugin configuration from the JSON file as an array
+function hello_world_get_config() {
+  $file     = HELLO_WORLD_CONFIGFILE;
+  $contents = file_get_contents($file);
+  $json     = json_decode($contents);    // Decodes the string
+  $config   = (array) $json;             // Converts the object into a PHP array
+  return $config;
+}
+</code>
+When the plugin is first loaded, the configuration file might not exist. So let's create some utility functions that detect if the file exists, and which create some default data:
+<code php>
+// Check that the configuration file exists
+function hello_world_config_exists() {
+  return file_exists(HELLO_WORLD_CONFIGFILE);
+}
+// Create a default configuration file
+function hello_world_init() {
+  $config = array('message' => hello_world_i18n('HELLO_WORLD'));
+  return hello_world_save_config($config);
+}
+</code>
+Now we can expand on the administration panel. First we ensure that the configuration file exists:
+<code php>
+// Administration panel
+function hello_world_admin() {
+  // Initialize the configuration file
+  $init = hello_world_config_exists() || hello_world_init();
+  // ...
+}
+</code>
+Then we will load the configuration data, and load the ''admin.php'' file (which will use this data and display the admin panel):
+<code php>
+// Administration panel
+function hello_world_admin() {
+  // Initialize the configuration file
+  $init = hello_world_config_exists() || hello_world_init();
+  // still more to add...
+  // Show the admin panel page
+  $config = hello_world_get_config();
+  include(HELLO_WORLD_PLUGINPATH . '/admin.php');
+}
+</code>
+The admin panel will have a ''<form>'' whose method is ''POST'' and whose action is simply the same page. There will be a text field with the name ''message'', and the submit button in said form will have the name ''save-configuration''. So if we want to save the configuration, we will need to check if the ''$_POST'' variable is populated with the ''save-configuration'' key:
+<code php>
+function hello_world_admin() {
+  // Initialize the configuration file
+  $init = hello_world_config_exists() || hello_world_init();
+  // Check if we need to save the configuration
+  $save_changes = isset($_POST['save-configuration']);
+  if ($save_changes) {
+    $save_success = hello_world_save_config($data);
+  }
+  // Show the admin panel page
+  $config = hello_world_get_config();
+  include(HELLO_WORLD_PLUGINPATH . '/admin.php');
+}
+</code>
+Lastly, we need the footer hook to actually load the message:
+<code php>
+// Hook for the theme footer
+function hello_world_footer() {
+  $config = hello_world_get_config();
+  echo '<p>' . $config['message'] . '</p>';
+}
+</code>
+This is the full file. It slightly expands on the administration panel by printing error messages and a introducing a placeholder for validating the submitted data:
-==== hello_world/common_functions.php ====
 <file php common_functions.php>
 <?php
@@ Line 169: / Line 329: @@
   echo '<div class="' . $class . '">' . $message . '</div>';
 }
+</file>
+===== hello_world/admin.php =====
+Lastly we define the look of the administration panel.
+<file php admin.php>
+<h3><?php echo hello_world_i18n('ADMIN'); ?></h3>
+<form method="post">
+  <input name="message" value="<?php echo $config['message']; ?>">
+  <button name="save-configuration"><?php echo hello_world_i18n('SAVE'); ?></button>
+</form>
 </file>

GetSimple CMS Wiki

User Tools

Site Tools

Differences

Page Tools