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().