This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
hello_world_plugin_extended [2017/01/21 20:06] lokothodida [Create the file structure] |
hello_world_plugin_extended [2017/01/22 21:24] (current) lokothodida [hello_world/admin.php] |
||
---|---|---|---|
Line 7: | Line 7: | ||
* Show how to save data to the ''data/other/'' path | * Show how to save data to the ''data/other/'' path | ||
- | ===== Create the file structure ===== | + | ===== File structure ===== |
+ | Create the following files/folders: | ||
<code> | <code> | ||
- hello_world.php | - hello_world.php | ||
Line 20: | Line 22: | ||
===== hello_world.php ===== | ===== 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 | <?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 | <?php | ||
// === Constants === | // === Constants === | ||
Line 55: | Line 107: | ||
===== hello_world/lang/en_US.php ===== | ===== 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> | <file php en_US.php> | ||
Line 70: | Line 123: | ||
</file> | </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> | <file php common_functions.php> | ||
<?php | <?php | ||
Line 169: | Line 329: | ||
echo '<div class="' . $class . '">' . $message . '</div>'; | echo '<div class="' . $class . '">' . $message . '</div>'; | ||
} | } | ||
+ | </file> | ||
+ | |||
+ | ===== hello_world/admin.php ===== | ||
+ | Lastly we define the look of the administration panel. As stated above, it will have a ''<form>'' with a ''message'' input field, ''save-configuration'' button, and will send the data from the form via ''POST''. All that is needed is to ensure the input field is populated with the last saved message: | ||
+ | |||
+ | <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> | </file> |