feat(localize) support namespaced data

stellarwp · Apr 22, 2024 · d420303 · d420303
1 parent 5c8f06c
commit d420303
Show file tree

Hide file tree

Showing 4 changed files with 624 additions and 344 deletions.
diff --git a/README.md b/README.md
@@ -427,6 +427,80 @@ Asset::add( 'my-asset', 'css/some-asset.css' )
 	->register();
 ```
 
+If you specify an object name using dot notation, then the object will be printed on the page "merging" it with other, pre-existing objects.
+In the following example, the `boomshakalaka.project` object will be created and then the `firstScriptData` and `secondScriptData` objects will be added to it:
+
+```php
+use Boomshakalaka\StellarWP\Assets\Asset;
+
+Asset::add( 'my-first-script', 'js/first-script.js' )
+	->add_localize_script(
+		'boomshakalaka.project.firstScriptData',
+		[
+			'animal' => 'cat',
+			'color'  => 'orange',
+		]
+	)
+	->register();
+
+Asset::add( 'my-second-script', 'js/second-script.js' )
+	->add_localize_script(
+		'boomshakalaka.project.secondScriptData',
+		[
+			'animal' => 'dog',
+			'color'  => 'green',
+		]
+	)
+	->register();
+
+Asset::add( 'my-second-script-mod', 'js/second-script-mod.js' )
+	->add_localize_script(
+		'boomshakalaka.project.secondScriptData',
+		[
+			'animal' => 'horse'
+		]
+	)
+	->register();
+```
+
+The resulting output will be:
+
+```html
+
+<script id="my-first-script-ns-extra">
+	window.boomshakalaka = window.boomshakalaka || {};
+	window.boomshakalaka.project = window.boomshakalaka.project || {};
+	window.boomshakalaka.project.firstScriptData = Object.assign(
+		window.boomshakalaka.project.firstScriptData || {},
+		{ "animal": "cat", "color": "orange" }
+	);
+</script>
+<script src="https://someplace.com/wp-content/plugins/my-plugins/js/first-script.js" id="my-first-script-js"></script>
+<script id="my-second-script-ns-extra">
+	window.boomshakalaka = window.boomshakalaka || {};
+	window.boomshakalaka.project = window.boomshakalaka.project || {};
+	window.boomshakalaka.project.secondScriptData = Object.assign(
+		window.boomshakalaka.project.secondScriptData || {},
+		{ "animal": "dog", "color": "green" }
+	);
+</script>
+<script src="https://someplace.com/wp-content/plugins/my-plugins/js/second-script.js" id="my-second-script-js"></script>
+<script id="my-second-script-mod-ns-extra">
+	window.boomshakalaka = window.boomshakalaka || {};
+	window.boomshakalaka.project = window.boomshakalaka.project || {};
+	window.boomshakalaka.project.secondScriptData = Object.assign(
+		window.boomshakalaka.project.secondScriptData || {},
+		{ "animal": "horse" }
+	);
+</script>
+<script src="https://someplace.com/wp-content/plugins/my-plugins/js/second-script-mod.js"
+		id="my-second-script-mod-js"></script>
+```
+
+Note the `my-second-script-mod` handle is overriding a specific nested
+key, `boomshakalaka.project.secondScriptData.animal`, in the `boomshakalaka.project.secondScriptData` object while
+preserving the other keys.
+
 ### Output content before/after a JS asset is output
 
 There may be times when you wish to output markup or text immediately before or immediately after outputting the JS

diff --git a/src/Assets/Asset.php b/src/Assets/Asset.php
@@ -115,7 +115,7 @@ class Asset {
 	/**
 	 * The asset wp_localize_script objects for this asset.
 	 *
-	 * @var array
+	 * @var array<string,mixed>
 	 */
 	protected array $wp_localize_script_objects = [];
 
@@ -217,6 +217,13 @@ class Asset {
 	 */
 	protected ?string $version = null;
 
+	/**
+	 * An array of objects to localized using dot-notation and namespaces.
+	 *
+	 * @var array<array{0: string, 1:mixed}>
+	 */
+	protected array $custom_localize_script_objects = [];
+
 	/**
 	 * Constructor.
 	 *
@@ -412,7 +419,12 @@ public function call_after_enqueue( $callable ) {
 	 * @return static
 	 */
 	public function add_localize_script( string $object_name, array $data ) {
-		$this->wp_localize_script_objects[ $object_name ] = $data;
+		if ( str_contains( $object_name, '.' ) ) {
+			$this->custom_localize_script_objects[] = [ $object_name, $data ];
+		} else {
+			$this->wp_localize_script_objects[ $object_name ] = $data;
+		}
+
 		return $this;
 	}
 
@@ -520,6 +532,15 @@ public function get_localize_scripts(): array {
 		return $this->wp_localize_script_objects;
 	}
 
+	/**
+	 * Get the asset wp_localize_script_objects.
+	 *
+	 * @return array<array{0: string, 1: mixed}> A set of data to localized using dot-notation.
+	 */
+	public function get_custom_localize_scripts(): array {
+		return $this->custom_localize_script_objects;
+	}
+
 	/**
 	 * Get the asset media setting.
 	 *