Scripts

Cuisine believes in a clean and uncluttered frontend. That’s why we use RequireJS to handle script loading.

If you don’t know why that’s an important step, please read their documentation on it, but it basically boils down to this: With RequireJS we remain extremely flexible on our scripts, while never compromising load-times.

In these docs you will mostly find how to register a Script file with Cuisine and get it up and running in RequireJS.

If you are not yet familiar with working with RequireJs we encourage you to check out the docs on RequireJs first.

Including the Script Class

The Script class is available through Cuisine’s Wrapper System, so you can start using it by adding

use Cuisine\Wrappers\Script

to the top of your php-document.

Registering a Script file

Let’s assume you’re creating a custom plugin based on Cuisine and you’d like that plugin to load a certain script on load.

Well registering that Script file in Cuisine is pretty easy:

	
$url = Url::plugin( 'my-plugin/Assets/js/script' );
Script::register( 'my-script-file', $url, true );


This function does a few things:

  • It fetches the plugin url for my-plugin using Cuisine’s Url Utility
  • It registers the script file with the identifier my-script-file
  • It tells Cuisine to autoload the script on page-load.

So let’s take a look at the parameters being send through Script::register():

  • Script identifier
    Much like WordPress’ wp_enqueue_script function, Cuisine uses a string to identify a certain script. This identifier is also used in Require.

  • Url
    This is the path to your plugin’s script-file. Notice it doesn’t end with .js; Cuisine adds this automatically for us.

  • Auto-load
    This boolean tells Require wether this script needs to be loaded on page-load. If you need this script on $(document).ready it’s smart to put this to true, but if you’re registering a library of which you have no idea if this needs to be always available; keep this at false. We’ll get into an example on why this is smart

Working with RequireJS & dependencies

In RequireJS you list most of your dependencies at the top of you javascript document. If your script needs jQuery to run properly, you need to define it, because RequireJS pretty much ommits the global namespace of Javascript.

To load the jQuery library as a dependency, we need to first define it in Cuisine: 

	
$url = Url::wp( 'jquery/jquery' );
Script::register( 'jquery-lib', $url, false );

Here we register the jQuery library that comes with WordPress (hence the Url::wp()) and we give it the name jquery in require.

So in our example above, we’ve included a my-script-file. That script file might look something like this:

define(['jquery-lib'], function( $ ){

	$( document ).ready( function(){

		alert( 'My script is being loaded by Require!' );

	});

});

Let’s look at the first line of that script: define([‘jquery-lib’], function( $ ){ .. })

We use the define function to map RequireJS script-names to certain variable names. It uses the same name (jquery-lib) as we’ve passed on to our Script::register() function. This tells RequireJS that your script needs the script registered as jquery-lib to be loaded.

The first parameter passed into the annonymous function following define() is the famous jQuery dollar-notation ($), meaning that whatever jquery-lib returns as it’s being loaded, it needs to be loaded under the variable-name $.

The annonymous function is the callback after load. So after jQuery gets loaded and passed as the $-variable, we’re safe to call $( document ).ready()

Loading scripts from within other scripts

One of the major upsides to Require is that you can load javascript from javascript. This means you can be a lot smarter about wether or not you need to load that library. If you need Flickity for a gallery that only appears on a certain page, you might not want to load it on every page, for instance. For this, keep a very simple rule in mind:

Once a Script is registered with Cuisine it’s callable from Require

So for instance, i’ve added this php in my plugin: 

	
$url = Url::plugin( 'my-plugin/Assets/js/' );
Script::register( 'flickity', $url.'flickity.min', false );
Script::register( 'gallery-trigger', $url.'gallery-trigger', true );

Notice I’ve autoloaded the gallery-trigger file, but haven’t done the same for the Flickity library. Meaning I can do this in my javascript:

define(['jquery-lib'], function( $ ){

	if( $( '.gallery-wrapper' ).length > 0 ){

		require( ['flickity' ], function( Flickity ){

			var gallery = new Flickity({

				...

			});

		});
	}

});

Here I’ve only loaded Flickity when a certain div was available on the page.

Registering variables from PHP for use in JS

We all to generate some inline javascript to get quick-access to variables from php to javascript sometimes. Cuisine handles this while being as clean as possible about it:

 	
$variable = array( 'foo' => 'Foo', 'bar' => 'Bar' );
Script::variable( 'variableName', $variable );

Now it can be used in Javascript like this: 

	console.log( variableName.foo ); // => 'Foo'

Using a custom theme with RequireJs and Cuisine:

In our theme-canvas, this is already present but using scripts this way requires two lines of code in your footer-file to work properly.

Here they are: 

 	
use Cuisine\Wrappers\Script;
Script::set();

Using Script::set() will plot all RequireJS dependencies in a hidden JSON object, plus add the RequireJS library and it’s bootstrap-script;

apart from one script-tag it will not load more HTML!

The rest of all script loading is handled by Require and happens in Javascript, not via HTML.