WordPress.org

Plugin Directory

Changeset 782894


Ignore:
Timestamp:
10/05/13 08:29:36 (7 months ago)
Author:
greenshady
Message:

Uploading version 0.2.0 of the Series plugin.

Location:
series
Files:
30 added
11 deleted
2 edited

Legend:

Unmodified
Added
Removed
  • series/trunk/readme.txt

    r124034 r782894  
    11=== Series === 
     2 
    23Contributors: greenshady 
    3 Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3687060 
    4 Tags: widget, taxonomy, shortcode, posts 
    5 Requires at least: 2.8 
    6 Tested up to: 2.8 
    7 Stable tag: 0.1 
     4Donate link: http://themehybrid.com/donate 
     5Tags: widget, taxonomy, shortcode, posts, series 
     6Requires at least: 3.6 
     7Tested up to: 3.7 
     8Stable tag: 0.2.0 
     9License: GPLv2 or later 
     10License URI: http://www.gnu.org/licenses/gpl-2.0.html 
    811 
    912Adds a new taxonomy called "series" to your blog that allows you to link together several posts in a series. 
     
    1114== Description == 
    1215 
    13 *Series* is a plugin created to allow users to easily link posts together by using a WordPress taxonomy (e.g. tags, categories) called "series".  It can be particularly useful if you write several posts spanning the same topic and want them tied together in some way. 
     16Series is a plugin created to allow users to easily link posts together by using a WordPress taxonomy (like tags or categories) called "series".  It can be particularly useful if you write several posts spanning the same topic and want them tied together in some way that tags or categories doesn't cover. 
    1417 
    15 *Series* will automatically create archives for you and offers several ways to link your posts together. 
     18### Professional Support 
    1619 
    17 Some features: 
     20If you need professional plugin support from me, the plugin author, you can access the support forums at [Theme Hybrid](http://themehybrid.com/support), which is a professional WordPress help/support site where I handle support for all my plugins and themes for a community of 40,000+ users (and growing). 
    1821 
    19 * A widget to list posts from a particular series. 
    20 * A widget to list posts in the same series as the current post. 
    21 * Several template tags for use within your theme. 
    22 * Two `taxonomy-series.php` templates for use with the WordPress Default theme and the <a href="http://themehybrid.com/themes/hybrid" title="Hybrid theme framework">Hybrid theme</a>. 
    23 * Shortcodes to use within the post editor. 
    24 * And more! 
     22### Plugin Development 
    2523 
    26 **This plugin is for WordPress 2.8+ only.** 
     24If you're a theme author, plugin author, or just a code hobbyist, you can follow the development of this plugin on it's [GitHub repository](https://github.com/justintadlock/series).  
    2725 
    28 Full instructions for use can be found in the plugin's `readme.html` file, which is included with the plugin download. 
     26### Donations 
     27 
     28Yes, I do accept donations.  If you want to buy me a beer or whatever, you can do so from my [donations page](http://themehybrid.com/donate).  I appreciate all donations, no matter the size.  Further development of this plugin is not contingent on donations, but they are always a nice incentive. 
    2929 
    3030== Installation == 
    3131 
    32 1. Upload `series.zip` to the `/wp-content/plugins/` directory. 
    33 2. Activate the plugin through the *Plugins* menu in WordPress. 
    34  
    35 More detailed instructions can be found in the plugin's `readme.html` file. 
     321. Unzip the `series.zip` folder. 
     332. Upload the `series` folder to your `/wp-content/plugins` directory. 
     343. In your WordPress dashboard, head over to the *Plugins* section. 
     354. Activate *Series*. 
    3636 
    3737== Frequently Asked Questions == 
    3838 
    39 = Why create this plugin? = 
     39### Why was this plugin created? 
    4040 
    41 I originally had a function to do something similar with custom fields, but using custom fields was kind of a crude method for this.  By using the built-in WordPress taxonomy system, we get a lot of automated stuff like series archives and the ability to use built-in WordPress functions to display content. 
     41Originally, it was a bit of a proof-of-concept of how plugins could create custom taxonomies based off a couple of highly-popular WordPress tutorials I wrote ([Custom taxonomies in WordPress 2.8](http://justintadlock.com/archives/2009/05/06/custom-taxonomies-in-wordpress-28) and [Using custom taxonomies to create a movie database](http://justintadlock.com/archives/2009/06/04/using-custom-taxonomies-to-create-a-movie-database)). 
    4242 
    43 = What does this plugin do, exactly? = 
     43However, it was also a plugin I wanted for my personal blog.  I'd been using custom fields for years to handle series, but it was always kind of a crude method of doing so.  When WordPress created the Taxonomy API, I knew it was time to build something simple and usable for handling series on my site. 
     44 
     45### What does this plugin do, exactly? 
    4446 
    4547It creates a new taxonomy called "series" for use on your site.  It gives you template tags, shortcodes, and widgets to allow you to more easily tie posts together in a series. 
    4648 
    47 = What widgets are available to use? = 
     49Basically, you get a new meta box on the edit post screen titled "Series" that works just like regular tags.  You can input a series name to add a post to a series.  You also get a "Series" screen under the "Posts" menu in the WordPress admin. 
    4850 
    49 * Series: List Posts 
    50 * Series: Related Posts 
     51### What widgets are available to use? 
    5152 
    52 = I don't understand any of this.  What should I do? = 
     53* **Series: List Posts** - This widget allows you to list posts from any series you've created. 
     54* **Series: List Related** - This widget displays posts within the current post's series.  So, it only shows up under two conditions: 1) you're viewing a single post and 2) the current post is within a series. 
    5355 
    54 You should do a little reading.  The `readme.html` file included with the plugin has links to tons of resources.  Everything you need to know is there. 
     56### Are there other functions to use in my theme? 
     57 
     58All standard WordPress functions for taxonomies work.  The name of the taxonomy is `series`.  So, if you want to do anything custom, WordPress already has the functions you need.  I'm not going to list them all here.  That'd be just like rewriting a large portion of the WordPress Codex, which is already available to you. 
     59 
     60If you're looking for a specific template tag, start with the [category template tags](http://codex.wordpress.org/Template_Tags#Category_tags).  Most of them allow you to use custom taxonomies. 
     61 
     62### Can you show me some examples? 
     63 
     64Okay.  I'll show a few, but you've probably seen them before if you've done anything with tags or categories. 
     65 
     66#### Displaying a "tag" cloud 
     67 
     68    <?php wp_tag_cloud( array( 'taxonomy' => 'series' ) ); ?> 
     69 
     70#### Displaying the current post's series 
     71 
     72    <?php echo get_the_term_list( get_the_ID(), 'series', 'Series: ', ', ', '' ); ?> 
     73 
     74#### Displaying a "category" list of series 
     75 
     76    <ul> 
     77        <?php wp_list_categories( array( 'taxonomy' => 'series', 'title_li' => false ) ); ?> 
     78    </ul> 
     79 
     80### Can I create custom templates for series? 
     81 
     82Certainly.  You can create templates for series archives.  Just copy your theme's `archive.php` or `index.php` template.  Then, rename it to `taxonomy-series.php` and make custom modifications from there. 
     83 
     84If you want a template for a specific series, name the template `taxonomy-series-exampleslug.php`. 
     85 
     86### Can you add feature X? 
     87 
     88I'll consider it.  Let me know what features you'd like to see added to the plugin.  Just keep in mind that I want this plugin to stay relatively lightweight.  Any features added should be useful for most of the plugin's users. 
     89 
     90### This is way too complicated for me! 
     91 
     92Please let me know how I could make things simpler for you in a future version of the plugin. 
     93 
     94Also, keep in mind that there are other series plugins out there.  This particular plugin might not be the best fit for you.  However, I'm more than willing to listen to feedback on making things easier. 
     95 
     96== Upgrade Notice == 
     97 
     98If upgrading from a version earlier than 0.2.0, be sure to check your widgets.  You may need to reset them. 
    5599 
    56100== Screenshots == 
    57101 
    58 There are currently no screenshots. 
     1021. Series meta box on the edit post screen. 
     1032. Widgets on the widgets admin screen. 
     1043. Manage series admin screen. 
     1054. Example widget output in theme. 
    59106 
    60107== Changelog == 
    61108 
    62 **Version 0.1** 
     109### Version 0.2.0 
     110 
     111* Completely overhauled the entire code base. 
     112 
     113### Version 0.1 
    63114 
    64115* Plugin launch. 
  • series/trunk/series.php

    r124034 r782894  
    22/** 
    33 * Plugin Name: Series 
    4  * Plugin URI: http://justintadlock.com/archives/2009/06/09/series-wordpress-plugin 
     4 * Plugin URI: http://themehybrid.com/plugins/series 
    55 * Description: Creates a new taxonomy called "Series" that allows you to tie posts together in a series. 
    6  * Version: 0.1 
     6 * Version: 0.2.0 
    77 * Author: Justin Tadlock 
    88 * Author URI: http://justintadlock.com 
    99 * 
    10  * Series is a plugin created to allow users to easily link posts together 
    11  * by using a custom WordPress taxonomy. By using a taxonomy, we're 
    12  * making use of the built-in WordPress functions.  This lets WordPress 
    13  * do all the dirty work, while we just sit back and enjoy adding posts to 
    14  * a series.  This can be particularly useful if you write several posts  
    15  * spanning the same topic and want them tied together in some way. 
     10 * This program is free software; you can redistribute it and/or modify it under the terms of the GNU  
     11 * General Public License as published by the Free Software Foundation; either version 2 of the License,  
     12 * or (at your option) any later version. 
    1613 * 
    17  * @copyright 2009 
    18  * @version 0.1 
    19  * @author Justin Tadlock 
    20  * @link http://justintadlock.com/archives/2009/06/09/series-wordpress-plugin 
    21  * @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html 
     14 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without  
     15 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
    2216 * 
    23  * This program is distributed in the hope that it will be useful, 
    24  * but WITHOUT ANY WARRANTY; without even the implied warranty of 
    25  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
     17 * You should have received a copy of the GNU General Public License along with this program; if not, write  
     18 * to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 
    2619 * 
    27  * @package Series 
     20 * @package   Series 
     21 * @version   0.2.0 
     22 * @since     0.1.0 
     23 * @author    Justin Tadlock <justin@justintadlock.com> 
     24 * @copyright Copyright (c) 2009 - 2013, Justin Tadlock 
     25 * @link      http://themehybrid.com/plugins/series 
     26 * @license   http://www.gnu.org/licenses/old-licenses/gpl-2.0.html 
    2827 */ 
    2928 
    30 /** 
    31  * Yes, we're localizing the plugin.  This partly makes sure non-English 
    32  * users can use it too.  To translate into your language use the 
    33  * en_EN.po file as as guide.  Poedit is a good tool to for translating. 
    34  * @link http://poedit.net 
    35  * 
    36  * @since 0.1 
    37  */ 
    38 load_plugin_textdomain( 'series', false, '/series' ); 
     29final class Series_Plugin { 
    3930 
    40 /** 
    41  * Make sure we get the correct directory. 
    42  * @since 0.1 
    43  */ 
    44 if ( !defined( 'WP_CONTENT_DIR' ) ) 
    45     define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' ); 
    46 if ( !defined( 'WP_PLUGIN_DIR' ) ) 
    47     define( 'WP_PLUGIN_DIR', WP_CONTENT_DIR . '/plugins' ); 
     31    /** 
     32     * Holds the instance of this class. 
     33     * 
     34     * @since  0.2.0 
     35     * @access private 
     36     * @var    object 
     37     */ 
     38    private static $instance; 
    4839 
    49 /** 
    50  * Define constant paths to the plugin folder. 
    51  * @since 0.1 
    52  */ 
    53 define( SERIES_DIR, WP_PLUGIN_DIR . '/series' ); 
     40    /** 
     41     * Stores the directory path for this plugin. 
     42     * 
     43     * @since  0.2.0 
     44     * @access private 
     45     * @var    string 
     46     */ 
     47    private $directory_path; 
    5448 
    55 /** 
    56  * Load required files. 
    57  * @since 0.1 
    58  */ 
    59 require_once( SERIES_DIR . '/template-tags.php' ); 
    60 require_once( SERIES_DIR . '/shortcodes.php' ); 
     49    /** 
     50     * Stores the directory URI for this plugin. 
     51     * 
     52     * @since  0.2.0 
     53     * @access private 
     54     * @var    string 
     55     */ 
     56    private $directory_uri; 
    6157 
    62 /** 
    63  * Creates our taxonomy when 'init' is fired. 
    64  * @since 0.1 
    65  */ 
    66 add_action( 'init', 'create_series_taxonomy', 0 ); 
     58    /** 
     59     * Plugin setup. 
     60     * 
     61     * @since  0.2.0 
     62     * @access public 
     63     * @return void 
     64     */ 
     65    public function __construct() { 
    6766 
    68 /** 
    69  * Register series widgets. 
    70  * @since 0.1 
    71  */ 
    72 add_action( 'widgets_init', 'series_register_widgets' ); 
     67        /* Set the properties needed by the plugin. */ 
     68        add_action( 'plugins_loaded', array( $this, 'setup' ), 1 ); 
    7369 
    74 /** 
    75  * Register the series taxonomy. 
    76  * @uses register_taxonomy() 
    77  * 
    78  * @since 0.1 
    79  */ 
    80 function create_series_taxonomy() { 
    81     $structure = get_option( 'permalink_structure' ); 
    82     if ( empty( $structure ) ) 
    83         $args = array( 'hierarchical' => false, 'label' => __('Series', 'series'), 'query_var' => 'series', 'rewrite' => false ); 
    84     else 
    85         $args = array( 'hierarchical' => false, 'label' => __('Series', 'series'), 'query_var' => 'series', 'rewrite' => array( 'slug' => 'series' ) ); 
     70        /* Internationalize the text strings used. */ 
     71        add_action( 'plugins_loaded', array( $this, 'i18n' ), 2 ); 
    8672 
    87     register_taxonomy( 'series', 'post', $args ); 
     73        /* Load the functions files. */ 
     74        add_action( 'plugins_loaded', array( $this, 'includes' ), 3 ); 
     75 
     76        /* Register widgets. */ 
     77        add_action( 'widgets_init', array( $this, 'register_widgets' ) ); 
     78 
     79        /* Register activation hook. */ 
     80        register_activation_hook( __FILE__, array( $this, 'activation' ) ); 
     81    } 
     82 
     83    /** 
     84     * Defines the directory path and URI for the plugin. 
     85     * 
     86     * @since  0.2.0 
     87     * @access public 
     88     * @return void 
     89     */ 
     90    public function setup() { 
     91        $this->directory_path = trailingslashit( plugin_dir_path( __FILE__ ) ); 
     92        $this->directory_uri  = trailingslashit( plugin_dir_url(  __FILE__ ) ); 
     93    } 
     94 
     95    /** 
     96     * Loads the initial files needed by the plugin. 
     97     * 
     98     * @since  0.2.0 
     99     * @access public 
     100     * @return void 
     101     */ 
     102    public function includes() { 
     103 
     104        require_once( "{$this->directory_path}inc/taxonomies.php"                ); 
     105        require_once( "{$this->directory_path}inc/template.php"                  ); 
     106        require_once( "{$this->directory_path}inc/shortcodes.php"                ); 
     107        require_once( "{$this->directory_path}inc/class-widget-list-posts.php"   ); 
     108        require_once( "{$this->directory_path}inc/class-widget-list-related.php" ); 
     109    } 
     110 
     111    /** 
     112     * Loads the translation files. 
     113     * 
     114     * @since  0.2.0 
     115     * @access public 
     116     * @return void 
     117     */ 
     118    public function i18n() { 
     119 
     120        /* Load the translation of the plugin. */ 
     121        load_plugin_textdomain( 'series', false, 'series/languages' ); 
     122    } 
     123 
     124    /** 
     125     * Loads the admin functions and files. 
     126     * 
     127     * @since  0.2.0 
     128     * @access public 
     129     * @return void 
     130     */ 
     131    public function register_widgets() { 
     132        register_widget( 'Series_Widget_List_Posts'   ); 
     133        register_widget( 'Series_Widget_List_Related' ); 
     134    } 
     135 
     136    /** 
     137     * Method that runs only when the plugin is activated. 
     138     * 
     139     * @since  0.2.0 
     140     * @access public 
     141     * @return void 
     142     */ 
     143    public function activation() { 
     144 
     145        /* Get the administrator role. */ 
     146        $role = get_role( 'administrator' ); 
     147 
     148        /* If the administrator role exists, add required capabilities for the plugin. */ 
     149        if ( !empty( $role ) ) 
     150            $role->add_cap( 'manage_series' ); 
     151    } 
     152 
     153    /** 
     154     * Returns the instance. 
     155     * 
     156     * @since  0.2.0 
     157     * @access public 
     158     * @return object 
     159     */ 
     160    public static function get_instance() { 
     161 
     162        if ( !self::$instance ) 
     163            self::$instance = new self; 
     164 
     165        return self::$instance; 
     166    } 
    88167} 
    89168 
    90 /** 
    91  * Register the Series plugin widgets. 
    92  * @uses register_widget() Registers individual widgets. 
    93  * @link http://codex.wordpress.org/WordPress_Widgets_Api 
    94  * 
    95  * @since 0.1 
    96  */ 
    97 function series_register_widgets() { 
    98     require_once( SERIES_DIR . '/series-widget.php' ); 
    99     require_once( SERIES_DIR . '/series-related-widget.php' ); 
    100     register_widget( 'Series_Widget_Series' ); 
    101     register_widget( 'Series_Widget_Related' ); 
    102 } 
     169Series_Plugin::get_instance(); 
    103170 
    104171?> 
Note: See TracChangeset for help on using the changeset viewer.