Refactor script and style registration

* Fix how GlotPress loads JavaScript to only load the required scripts per page.
* Update dependencies and add support for enqueueing with an array.
* Add DocBlocks and move enqueueing of default style to the asset loader.
* Move the enqueue of the base GlotPress style sheet to header.php.
* Collapse the script/style globals into the `GP` object.
* Validated dependencies and use them instead to load scripts.

gp-includes/assets-loader.php

@@ -1,84 +1,126 @@
 <?php
 /**
- * Defines default styles and scripts
+ * Defines default styles and scripts.
+ *
+ * @package GlotPress
+ * @since 1.0.0
  */
 
 /**
- * Register the GlotPress styles
- *
- * @param WP_Styles $styles
+ * Registers the GlotPress styles and loads the base style sheet.
  */
-function gp_styles_default( &$styles ) {
+function gp_register_default_styles() {
 	$url = gp_plugin_url( 'assets/css' );
 
-	$styles->add( 'base', $url . '/style.css', array(), '20150717' );
+	// Register our base style.
+	wp_register_style( 'gp-base', $url . '/style.css', array(), '20150717' );
 }
 
-add_action( 'wp_default_styles', 'gp_styles_default' );
+add_action( 'init', 'gp_register_default_styles' );
 
 /**
- * Register the GlotPress scripts
- *
- * @param WP_Scripts $scripts
+ * Register the GlotPress scripts.
  */
-function gp_scripts_default( &$scripts ) {
+function gp_register_default_scripts() {
 	$url = gp_plugin_url( 'assets/js' );
 
-	$scripts->add( 'tablesorter', $url . '/jquery.tablesorter.min.js', array( 'jquery' ), '1.10.4' );
-
-	$scripts->add( 'gp-common', $url . '/common.js', array( 'jquery' ), '20150430' );
-	$scripts->add( 'gp-editor', $url . '/editor.js', array( 'gp-common', 'jquery-ui-tooltip' ), '20160329' );
-	$scripts->add( 'gp-glossary', $url . '/glossary.js', array( 'gp-common' ), '20160329' );
-	$scripts->add( 'gp-translations-page', $url . '/translations-page.js', array( 'gp-common' ), '20150430' );
-	$scripts->add( 'mass-create-sets-page', $url . '/mass-create-sets-page.js', array( 'gp-common' ), '20150430' );
+	// Register our standard scripts.
+	wp_register_script( 'tablesorter', $url . '/jquery.tablesorter.min.js', array( 'jquery' ), '1.10.4' );
+	wp_register_script( 'gp-common', $url . '/common.js', array( 'jquery' ), '20150430' );
+	wp_register_script( 'gp-editor', $url . '/editor.js', array( 'gp-common', 'jquery-ui-tooltip' ), '20160329' );
+	wp_register_script( 'gp-glossary', $url . '/glossary.js', array( 'gp-editor' ), '20160329' );
+	wp_register_script( 'gp-translations-page', $url . '/translations-page.js', array( 'gp-editor' ), '20150430' );
+	wp_register_script( 'gp-mass-create-sets-page', $url . '/mass-create-sets-page.js', array( 'gp-editor' ), '20150430' );
 }
 
-add_action( 'wp_default_scripts', 'gp_scripts_default' );
+add_action( 'init', 'gp_register_default_scripts' );
 
 /**
- * Here we abstract WordPress core's enqueuing functions because...
- * 1. We don't want to print scripts and styles that are meant for the WordPress theme
- * 2. GlotPress enqueues scripts and styles from its template files and if we do that
- *    with wp_enqueue_script() and wp_enqueue_style() WordPress complains that
- *    those functions should only be called inside of wp_enqueue_scripts()
+ * Enqueue one or more styles.
+ *
+ * @since 2.2.0
+ *
+ * @param string|array $handles A single style handle to enqueue or an array or style handles to enqueue.
  */
+function gp_enqueue_styles( $handles ) {
+	// Make sure $handles is an array to simplify the next loop.
+	$handles = (array) $handles;
 
-function gp_enqueue_scripts() {
-	global $gp_enqueued_styles, $gp_enqueued_scripts;
-
-	if ( ! empty( $gp_enqueued_scripts ) ) {
-		foreach ( $gp_enqueued_scripts as $handle ) {
-			wp_enqueue_script( $handle );
-		}
+	// Loop through each handle we've been asked to enqueue.
+	foreach ( $handles as $handle ) {
+		gp_enqueue_style( $handle );
 	}
+}
 
-	if ( ! empty( $gp_enqueued_styles ) ) {
-		foreach ( $gp_enqueued_styles as $handle ) {
-			wp_enqueue_style( $handle );
-		}
+/**
+ * Enqueue one or more styles.
+ *
+ * @since 1.0.0
+ *
+ * @param string $handle A single style handle to enqueue.
+ */
+function gp_enqueue_style( $handle ) {
+	if ( ! in_array( $handle, GP::$styles, true ) ) {
+		// Store the handle name in the global array.
+		GP::$styles[] = $handle;
+
+		// Actually enqueue the handle via WordPress.
+		wp_enqueue_style( $handle );
 	}
 }
 
-add_action( 'wp_enqueue_scripts', 'gp_enqueue_scripts' );
-
-function gp_enqueue_style( $handle ) {
-	global $gp_enqueued_styles;
+/**
+ * Enqueue one or more scripts.
+ *
+ * @since 2.2.0
+ *
+ * @param string|array $handles A single script handle to enqueue or an array of enqueue handles to enqueue.
+ */
+function gp_enqueue_scripts( $handles ) {
+	// Make sure $handles is an array to simplify the next loop.
+	$handles = (array) $handles;
 
-	$gp_enqueued_styles[] = $handle;
+	// Loop through each handle we've been asked to enqueue.
+	foreach ( $handles as $handle ) {
+		gp_enqueue_script( $handle );
+	}
 }
 
+/**
+ * Enqueue one or more scripts.
+ *
+ * @since 1.0.0
+ *
+ * @param string $handle A single script handle to enqueue.
+ */
 function gp_enqueue_script( $handle ) {
-	global $gp_enqueued_scripts;
+	if ( ! in_array( $handle, GP::$scripts, true ) ) {
+		// Store the handle name in the global array.
+		GP::$scripts[] = $handle;
 
-	$gp_enqueued_scripts[] = $handle;
+		// Actually enqueue the handle via WordPress.
+		wp_enqueue_script( $handle );
+	}
 }
 
+/**
+ * Print the styles that have been enqueued.
+ *
+ * Only output the styles that GlotPress has registered, otherwise we'd be sending any style that the WordPress theme or plugins may have enqueued.
+ *
+ * @since 2.2.0
+ */
 function gp_print_styles() {
-	global $gp_enqueued_styles;
-	wp_print_styles( $gp_enqueued_styles );
+	wp_print_styles( GP::$styles );
 }
 
+/**
+ * Print the scripts that have been enqueued.
+ *
+ * Only output the scripts that GlotPress has registered, otherwise we'd be sending any scripts that the WordPress theme or plugins may have enqueued.
+ *
+ * @since 2.2.0
+ */
 function gp_print_scripts() {
-	global $gp_enqueued_scripts;
-	wp_print_scripts( $gp_enqueued_scripts );
+	wp_print_scripts( GP::$scripts );
 }

gp-includes/gp.php

@@ -147,4 +147,22 @@ class GP {
 	 * @var GP_Format[]
 	 */
 	public static $formats;
+
+	/**
+	 * Array of enqueued style sheets.
+	 *
+	 * @since 2.2.0
+	 *
+	 * @var array
+	 */
+	public static $styles = array();
+
+	/**
+	 * Array of enqueued scripts.
+	 *
+	 * @since 2.2.0
+	 *
+	 * @var array
+	 */
+	public static $scripts = array();
 }

gp-templates/glossary-view.php

@@ -10,7 +10,7 @@
 $delete_url       = gp_url_join( $url, '-delete' );
 $glossary_options = compact( 'can_edit', 'url', 'delete_url', 'ge_delete_ays' );
 
-gp_enqueue_script( 'gp-glossary' );
+gp_enqueue_scripts( 'gp-glossary' );
 wp_localize_script( 'gp-glossary', '$gp_glossary_options', $glossary_options );
 
 gp_tmpl_header();

gp-templates/header.php

@@ -4,7 +4,11 @@
 	<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
 	<title><?php echo gp_title(); ?></title>
 
-	<?php gp_head(); ?>
+	<?php
+	// Enqueue the base style so we don't have to load it manually on each page.
+	gp_enqueue_styles( 'gp-base' );
+
+	gp_head(); ?>
 </head>
 
 <body <?php body_class( 'no-js' ); ?>>

gp-templates/helper-functions.php

@@ -6,9 +6,6 @@
  * @since 1.0.0
  */
 
-gp_enqueue_style( 'base' );
-gp_enqueue_script( 'jquery' );
-
 /**
  * Prepare an original string to be printed out in a translation row by adding encoding special
  * characters, adding glossary entires and other markup.

gp-templates/locales.php

@@ -1,8 +1,7 @@
 <?php
 gp_title( __( 'Locales &lt; GlotPress', 'glotpress' ) );
 
-gp_enqueue_script( 'gp-common' );
-gp_enqueue_script( 'tablesorter' );
+gp_enqueue_scripts( array( 'gp-common', 'tablesorter' ) );
 gp_breadcrumb( array( __( 'Locales', 'glotpress' ) ) );
 gp_tmpl_header();
 ?>

gp-templates/project-mass-create-sets.php

@@ -1,9 +1,9 @@
 <?php
 gp_title( sprintf( __( 'Mass-create Translation Sets &lt; %s &lt; GlotPress', 'glotpress' ),  $project->name ) );
 gp_breadcrumb_project( $project );
-gp_enqueue_script( 'mass-create-sets-page' );
-wp_localize_script( 'mass-create-sets-page', '$gp_mass_create_sets_options', array(
-	'url' => gp_url_join( gp_url_current(), 'preview'),
+gp_enqueue_scripts( 'gp-mass-create-sets-page' );
+wp_localize_script( 'gp-mass-create-sets-page', '$gp_mass_create_sets_options', array(
+	'url' => gp_url_join( gp_url_current(), 'preview' ),
 	'loading' => __( 'Loading translation sets to create&hellip;', 'glotpress' ),
 ));
 gp_tmpl_header();

gp-templates/project.php

@@ -1,8 +1,7 @@
 <?php
 gp_title( sprintf( __( '%s &lt; GlotPress', 'glotpress' ), esc_html( $project->name ) ) );
 gp_breadcrumb_project( $project );
-gp_enqueue_script( 'gp-common' );
-gp_enqueue_script('tablesorter');
+gp_enqueue_scripts( array( 'gp-editor', 'tablesorter' ) );
 $edit_link = gp_link_project_edit_get( $project, __( '(edit)', 'glotpress' ) );
 
 if ( $project->active ) {

gp-templates/translations.php

@@ -4,9 +4,7 @@
 	gp_project_links_from_root( $project ),
 	gp_link_get( $url, $translation_set->name ),
 ) );
-gp_enqueue_script( 'jquery-ui-core' );
-gp_enqueue_script( 'gp-editor' );
-gp_enqueue_script( 'gp-translations-page' );
+gp_enqueue_scripts( array( 'gp-editor', 'gp-translations-page' ) );
 wp_localize_script( 'gp-translations-page', '$gp_translations_options', array( 'sort' => __( 'Sort', 'glotpress' ), 'filter' => __( 'Filter', 'glotpress' ) ) );
 
 // localizer adds var in front of the variable name, so we can't use $gp.editor.options