subtitles.php
<?php
/**
* Plugin Name: Subtitles
* Plugin URI: http://wordpress.org/plugins/subtitles/
* Description: Easily add subtitles into your WordPress posts, pages, custom post types, and themes.
* Author: <a href="https://philip.blog/">Philip Arthur Moore</a>, <a href="https://wecobble.com">We Cobble</a>
* Version: 4.0.0
* Text Domain: subtitles
* Domain Path: /languages/
* License: GNU General Public License v2 or later
* License URI: http://www.gnu.org/licenses/gpl-2.0.html
*
* Subtitles WordPress Plugin, Copyright 2014-2019 We Cobble <mail@wecobble.com>,
* distributed under the terms of the GNU General Public License v2 or later.
*
* Right now WordPress currently presents no easy way for web publishers to add
* subtitles into their posts, pages, and other custom post types. This leaves theme makers
* in a bit of a quandary, trying to figure out how best to present subtitles in a beautiful
* and sensible way. Post excerpts are a very poor choice for subtitles and the only available
* option outside of custom fields, but custom fields aren't entirely self-explanatory or
* user-friendly. This simple, straightforward plugin aims to solve this issue.
*
* A note to plugin developers and theme makers: you may be wondering why I've taken
* the time to document code that to seasoned vets may seem obvious, for example explaining
* that functions inside of classes are called methods. The reason I've done this is primarily
* because there was a time when looking at the following code would have made absolutely no
* sense to me. At that time, I would have loved for there to have been robust inline documentation
* explaining to me what was happening. Consider the following documentation a gift to newbies and
* also a gift to my future self, who will undoubtedly look back on some of what I've written here
* with confusion and chagrin.
*
* A few design decisions have been made during the implementation of this plugin, which I'd
* like to outline below.
*
* 1. This plugin should "just work". I do not want users to have to both install the plugin and
* then also have to edit their theme files in order to show subtitles on their websites. That's
* too painful for what should be a quick and pleasant experience from activation to plugin use.
* 2. Along these lines, the ideal situation for users is that they should be able to download Subtitles,
* activate it, use it, and switch between themes (and preview themes before use) without worrying
* about all of their Subtitles data getting lost. If a simple theme-focused plugin like this one
* instructs users to use custom template tags like the_subtitle() in their theme template files,
* then what will happen when they switch away from their active theme in use? They'll either
* think that their data has been lost or they will have to go back into their new theme and
* add in the custom template tags all over again. This isn't very user-friendly.
* 3. Along these lines, there's a problem with custom template tags in that the moment a user disables
* Subtitles, his website will crash if he has not put in function_exists checks into his template
* files, which isn't pretty. If a user tries Subtitles, doesn't like it, and removes it altogether,
* there shouldn't be remnants of the plugin left in his theme's template files. I'd like for it to
* be as if the plugin never existed in the first place if a user decides that it's not a good fit.
* It would also be very cool if in the future core adopts its own the_subtitle() template tag, which
* I'd like not to potentially stomp on.
* 4. Visually, I have made a major assumption that subtitles belong immediately after titles. The very
* definition of a subtitle is that it is a subordinate title of a published work that often gives
* explanatory details about the immediately preceeding title. It's for this reason that I've chosen
* to filter the output of the_title() with the expectation that post titles will be wrapped in
* primary heading (h1) tags. So post titles will be H1, while their subtitles will be spans.
* Multiple H1 tags in the HTML5 age are okay.
* 5. The reason that <spans> are being used is because HTML does not have a dedicated mechanism for
* marking up subheadings, alternative titles, or taglines. There are suggested alternatives from
* the World Wide Web Consortium (W3C); among them are spans, which work well for what we're trying
* to do with titles in WordPress. See the linked documentation for more information.
* @link http://www.w3.org/html/wg/drafts/html/master/common-idioms.html#sub-head
* 6. By default subtitles are available to posts, pages, and Jetpack portfolio projects. If you find that you'd also like to use
* them with your custom post types, then simply add post type support for subtitles, for example:
* `add_post_type_support( $post_type, 'subtitles' )`. Remember to do this within a function that's
* hooked to `init`. See the Codex for more information:
* @link http://codex.wordpress.org/Function_Reference/add_post_type_support
* @link http://jetpack.com/
*
* One of the drawbacks of this approach, which I think is minor enough to proceed with the design of the plugin,
* is that the $before and $after values in the_title() are unable to be filtered. What this means is that for
* themes that have markup wrapped inside of a the_title() call the subtitle markup will either be nested
* inside of the theme-provided markup or break out of the markup, depending on what's wrapped around the_title().
*
* The default markup for subtitles in this plugin is spans, so this isn't a problem, but if for some reason
* you would like to use subtitles for another purpose, then I suggest removing the subtitle filter on the_title()
* and using one of the helper template tags that have been shipped with the plugin.
*
* Bug reports and contributions in the form of patches are both welcomed and very much appreciated.
* @link https://github.com/wecobble/Subtitles
*
* For WordPress PHP documentation standards, see the following link:
* @link http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/
*
* @package Subtitles
* @author We Cobble <mail@wecobble.com>
* @license URI: http://www.gnu.org/licenses/gpl-2.0.html GNU General Public License v2 or later
* @link http://wordpress.org/plugins/subtitles/
* @copyright 2014-2018 We Cobble
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* Do not load this file directly.
*
* @since 1.0.0
*/
if ( ! defined( 'ABSPATH' ) ) {
die( '-1' );
}
/**
* Load in front-end functionality.
*
* @link http://www.php.net//manual/en/function.require.php
* @see plugin_dir_path()
* @link http://codex.wordpress.org/Function_Reference/plugin_dir_path
*
* @since 1.0.0
*/
require plugin_dir_path( __FILE__ ) . 'public/class-subtitles.php';
/**
* Instantiate Subtitles on `plugins_loaded`.
*
* @see add_action()
* @link http://codex.wordpress.org/Function_Reference/add_action
* @link http://codex.wordpress.org/Plugin_API/Action_Reference/plugins_loaded
*
* @since 1.0.0
*/
add_action(
'plugins_loaded', // The hook on which Subtitles is fired.
array(
// The primary front-end class.
'Subtitles',
// Instantiation method within the class.
'getinstance',
)
); // end add_action()
/**
* Load in front-end functions that can be used by themers.
*
* The ultimate goal is that themers will not need to use these functions,
* as Subtitles should just work out of the box, but for themers who want to unfilter
* subtitles from the_title() and have more control over what happens with
* subtitles within their themes, these helper functions exist to make that a viable option.
*
* @link http://www.php.net//manual/en/function.require.php
* @see plugin_dir_path()
* @link http://codex.wordpress.org/Function_Reference/plugin_dir_path
*
* @since 1.0.0
*/
require plugin_dir_path( __FILE__ ) . 'public/includes/template-tags.php';
/**
* Load in Dashboard functionality and kick off the primary admin class on `plugins_loaded`.
*
* The plugin doesn't really depend on any Ajax functionality,
* so we'll make sure that the admin class isn't triggered when
* DOING_AJAX is defined. We'll also make sure that the admin class
* only fires off when we're actually in the admin area of the site.
*
* @see add_action()
* @see is_admin()
* @see plugin_dir_path()
* @link http://codex.wordpress.org/Function_Reference/is_admin
* @link http://www.php.net//manual/en/function.require.php
* @link http://codex.wordpress.org/Function_Reference/plugin_dir_path
* @link http://codex.wordpress.org/Function_Reference/add_action
* @link http://codex.wordpress.org/Plugin_API/Action_Reference/plugins_loaded
*
* @since 1.0.0
*/
if ( is_admin() && ( ! defined( 'DOING_AJAX' ) || ! DOING_AJAX ) ) {
require plugin_dir_path( __FILE__ ) . 'admin/class-subtitles-admin.php';
add_action(
'plugins_loaded', // The hook on which Subtitles_Admin is fired.
array(
// The primary admin class for Subtitles.
'Subtitles_Admin',
// Instantiation method within the class.
'getinstance',
)
); // end add_action()
} // End if().