pluginjpg 2

WordPress

My First WordPress Plugin

18 Jan , 2014  

Why Write a Plugin

Last week I wrote about Really Easy Responsive Columns in WordPress. In that post I recommended using Justin Tadlock’s Grid Columns plugin which did a great job of adding columns to your posts. The one downside was it didn’t collapse down to a single column at smaller widths.

To get this collapsing thing done I created a plugin which enabled the columns to collapse down at smaller screen widths. The reason I wrote a plugin instead of amending the functions.php file was that it means I can change my theme and it will still work.

The Structure

There were a few different ways to approach this but I decided that the simplest way for my plugin to do it was to add in new CSS that changed the column widths to 100%. It had to come after the Grid Columns CSS and only if the screen was below a specified width.

The Plugin Structure

wordpress/wp-content/plugins/
└── grid-columns-collapse
    ├── css
    |   └── gc-collapse.css
    └── grid-columns-collapse.php

So the plugin is in a folder containing a php file with the same name as the foldervery important. The php file will have the code that runs the plugin.

At the start of the php file is a comment area which contains meta-data that wordpress uses to administer the plugin. Feel free to copy and paste from mine and enter your own data –

/*
Plugin Name: Grid Columns Collapse
Plugin URI: http://http://www.designmite.com/
Description: This is a companion plugin for Justin Tadlock's 'Grid Columns' plugin - http://themehybrid.com/plugins/grid-columns. Specify a screen width at which the columns to collapse down into one. 
Version: 1.0
Author: Tony Hill
Author URI: http://twitter.com/designmite
License: Help yourselves!
*/

The CSS

The CSS that I wanted my plugin to overwrite basically consisted of percentage widths of columns like this –

.column-grid-4 .column-span-4 { width: 100%;   }
.column-grid-4 .column-span-3 { width: 73.75%; }
.column-grid-4 .column-span-2 { width: 47.5%;  }
.column-grid-4 .column-span-1 { width: 21.25%; }

My CSS just set these to %100 like so –

.column-grid-4 .column-span-4 { width: 100%; }
.column-grid-4 .column-span-3 { width: 100%; }
.column-grid-4 .column-span-2 { width: 100%; }
.column-grid-4 .column-span-1 { width: 100%; }

There were a few other bits and bobs, like some margins set to 0 but nothing tricky. I put this css in a file called gc-collapse.css in a css folder within my plugin folder.

Registering the ‘Width’ setting

To register the width setting I used add_option() and register_setting().

function gc_register_settings() {
  add_option( 'gc-collapse_width','650', 1);
  register_setting( 'default', 'gc-collapse_width' ); 
} 
add_action( 'admin_init', 'gc_register_settings' );
  1. Create a function to register the setting.
  2. Add the option – add_option( $name, $default_value, $autoload ) – The last option is a boolean telling wordpress whether or not to save this value if it changes.
  3. Register this option as a setting.
  4. Add this function to admin_init.

The Options Page

First I had to register the options page like this –

function gc_register_options_page() {
  add_plugins_page('Grid Columns Collapse', 'Grid Columns Collapse', 'manage_options', 'gc-collapse-options', 'gc_collapse_options_page');
}
add_action('admin_menu', 'gc_register_options_page');

This uses add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function). There is a full breakdown of these parameters here but the last parameter is the name of the function that renders the option page. Here is the code for that –

function gc_collapse_options_page() {
  ?>
<div class="wrap">
  <h2>Grid Columns Collapse</h2>
  <form method="post" action="options.php"> 
    <?php settings_fields( 'default' ); ?>

      <p>This is a companion plugin for Justin Tadlock's 'Grid Columns' plugin.
        <br>http://themehybrid.com/plugins/grid-columns
      </p>
      <table class="form-table">
        <tr valign="top">
          <th scope="row"><label for="gc-collapse_width">Width</label></th>
          <td><input type="text" id="gc-collapse_width" name="gc-collapse_width" value="<?php echo get_option('gc-collapse_width'); ?>" /></td>
        </tr>
      <p>Enter in the max-width at which you would like the columns 
        <br>to collapse down to a single column.
      </p>

      </table>
    <?php submit_button(); ?>
  </form>
</div>
<?php
}
  1. Starts with a PHP closing tag to start rendering HTML.
  2. The wrap class is a wordpress class for default admin menu rendering.
  3. We have a form that will call options.php. This is where wordpress handles the options.
  4. Calling settings_fields( 'default' ) means that wordpress will save the changed setting. Otherwise we would have to write our own function for storing the setting.
  5. The input is given the name of the option gc-collapse_width.
  6. The value is called using get_option().
  7. Ends with PHP open tag to finish rendering HTML

Finally – Enqueue the CSS

OK, now this is the point where the plugin can do what it has been written to do!

function grid_columns_collapse() {
  $gc_width = get_option('gc-collapse_width') . "px";
    wp_register_style( 
      'gc-collapse', 
      plugin_dir_url( __FILE__ ) . 'css/gc-collapse.css',
      array('grid-columns'),
      '20140114',
      "screen and (max-width: $gc_width)"
       );

    wp_enqueue_style( 'gc-collapse' );
}
 add_action( 'wp_enqueue_scripts', 'grid_columns_collapse' );
  1. Use get_option to get the width value and put it into a variable $gc_width
  2. Register the style wth wp_register_style() and the following attributes;
    • gc-collapse – the name of the stylesheet
    • plugin_dir_url( __FILE__ ) . 'css/gc-collapse.css' – the location of the css
    • array('grid-columns') – only injects this stylesheet after the Grid Columns stylesheet
    • 20140114 – a version number
    • screen and (max-width: $gc_width) – the media query which will only apply this stylesheet when the screen is narrower than our gc-width
  3. Enqueue the style and add the action!

Install & Activate

  1. Download the Grid Columns plugin
  2. Download Grid Columns Collapse
  3. Put these into your plugins folder – typically /wp-content/plugins
  4. Activate the plugins in your wp-admin dashboard

There is documentation on how to use the Grid Columns plugin included in the download and all you need to know about using the Collapse plug in is shown below. Hope this is useful!
columnSettings

Thanks Guys!

Mainly I learned how to do this from these three places ;

  1. How to enqueue Scripts & Stylesheets to WordPress via a plugin
  2. Creating a Simple Options Page
  3. Creating Options Pages in the WordPress Codex


One response to “My First WordPress Plugin”

  1. Dave says:

    Hi Tony,

    Thank you for writing and sharing Grid Columns Collapse. You and Justin have taken an immensely frustrating proposition and made it so gloriously simple, I have truly been in a fabulous mood since discovering it last night. (Perhaps that says too much about what a dork I am…) Anyway, I am over the moon about my long-desired responsive columnar layout. Thank you for your great work!

    Best,
    Dave

Leave a Reply

Your email address will not be published. Required fields are marked *