Easy SCSS and JS

This plugin will make it easier for you and your colleagues to include SCSS and JS files. The plugin will automatically compile the SCSS files without the need of GULP, GRUNT, NPM, YARN or WebPack. It just uses PHP.

Easy SCSS and JS

Getting started

The basics of this plugin are including styles and scripts.

As example, we use the following very basic directory:

your theme
├── assets
│   ├── js
│   │   └── script.js
│   └── scss
│       └── style.scss
├── functions.php
└── ...

Including a SCSS file

This is super easy and doesn't require any special WordPress function to get URLs.

functions.php:

<?php
add_action('wp_enqueue_scripts', static function(){
    /* Full version */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss', [],[], true, false, \LJPc\EasySCSSandJS\Styles::EVERY_TIME);

    /* Shortest version */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss');

    /* Add dependencies (example: depends on handle 'bootstrap') */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss', ['bootstrap']);

    /* Add variables */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss', [], [
        'my_cool_color' => '#0000ff',
    ]);

    /* Enqueue it yourself */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss', [], [], false);
    wp_enqueue_style('my_style_handle');

    /* Add !important to every line */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss', [], [], true, true);

    /* Make it only check for changes every day (only recommended if you use variables that only change once per day) */
    \LJPc\EasySCSSandJS\Styles::add('my_style_handle', __DIR__ .'/assets/scss/style.scss', [], [], true, false, \LJPc\EasySCSSandJS\Styles::EVERY_DAY);
});

Using variables in SCSS

Let's say you defined the variable my_cool_color in functions.php. Now you can do the following in SCSS:

// This is recommended. It will throw a fatal error if your PHP doesn't set the variable for some reason.
// If PHP does set it, it will replace $my_cool_color with the defined color in PHP.
$my_cool_color: #ffffff !default; 

body{
  background-color: $my_cool_color; // This will be blue (#0000ff)
}

Including a JS file

This is super easy and doesn't require any special WordPress function to get URLs.

functions.php:

<?php
add_action('wp_enqueue_scripts', static function(){
    /* Full version */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', ['jquery'], [], true, true, \LJPc\EasySCSSandJS\Scripts::EVERY_TIME);
    
    /* Shortest version (jquery is by default a dependency) */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js');

    /* No dependencies (also no jquery) */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', []);

    /* Add dependencies (besides jquery) */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', ['jquery', 'other_script']);

    /* Add variables */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', ['jquery'], [
        'my_variable' => 'testing this awesome plugin',
    ]);
    
    /* Enqueue it yourself */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', ['jquery'], [], false);
    wp_enqueue_script('my_script_handle');

    /* Add the script to the header instead of the footer */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', ['jquery'], [], true, false);
    
    /* Make it only check for changes every day (only recommended if you use variables that only change once per day) */
    \LJPc\EasySCSSandJS\Scripts::add('my_script_handle', __DIR__ .'/assets/js/script.js', ['jquery'], [], true, true, \LJPc\EasySCSSandJS\Scripts::EVERY_DAY);
});

Using variables in SCSS

Let's say you defined the variable my_cool_color in functions.php. Now you can do the following in SCSS:

// This is recommended. It will throw a fatal error if your PHP doesn't set the variable for some reason.
// If PHP does set it, it will replace $my_cool_color with the defined color in PHP.
$my_cool_color: #ffffff !default; 

body{
  background-color: $my_cool_color; // This will be blue (#0000ff)
}

Using variables in JS

Let's say you defined the variable my_variable in functions.php and your script handle is my_script_handle. Now you can do the following in JS:

alert(my_script_handle_vars.my_variable);

As you can see, _vars will be added to your scripts handle. This is to make sure that there won't be any collisions with handle names. If your handle contains hypens (my-script-handle), then all hyphens will be coverted to underscores (my_script_handle) and then _vars will be added (my_script_handle_vars). This is because a variable can not contain hyphens, because a hyphen will be interpreted as a minus sign.

Filters

Filter `ljpc_scss_formatter`

Changes the output of the compiler. Default is compressed. expanded is forced when the script is set to important. Options:

compressed
expanded
nested
compact

Use this to change the formatter:

<?php
add_filter('ljpc_scss_formatter', static function(){
    return 'compressed';
}, 10, 0);

Filter `ljpc_scss_sourcemap`

Allows you to disable sourcemaps in SCSS.

Use this to disable them:

<?php
add_filter('ljpc_scss_sourcemap', '__return_false');

Filter `ljpc_scss_extra_variables`

ljpc_scss_extra_variables has 4 parameters:

$extraVariables (array): holds the variables that are already set and should be returned at the end of the filter
$handle (string): holds the handle (id) of the style
$file (string): holds the full file path of the file
$dependencies (array): holds the dependencies of the file

Example 1: Adding a color to all SCSS files

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_scss_extra_variables', static function($extraVariables){
    $extraVariables['my_cool_color'] = '#ff0000';
    return $extraVariables;
},10, 1);

You can now use it in all your SCSS files:

// This is recommended. It will throw a fatal error if your PHP doesn't set the variable for some reason.
// If PHP does set it, it will replace $my_cool_color with the defined color in PHP.
$my_cool_color: #ffffff !default; 

body{
  background-color: $my_cool_color; // This will be blue (#ff0000)
}

Example 2: Adding a URL to all SCSS files that depend on Bootstrap

<?php
add_filter('ljpc_scss_extra_variables', static function($extraVariables, $handle, $file, $dependencies){
    if(in_array('bootstrap', $dependencies, true)){
        $extraVariables['image_url'] = 'https://www.example.com/test.jpg';
    }
    return $extraVariables;
},10, 4);

You can now use it in all SCSS files that depend on the bootstrap handle:

// This is required. It will throw a fatal error if your PHP doesn't set the variable.
$image_url: 'https://www.example.com/placeholder.jpg' !default; 

body{
  background-image: url($image_url); // This will now link to https://www.example.com/test.jpg
}

Example 3: Adding a color to a specific SCSS file

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_scss_extra_variables', static function($extraVariables, $handle){
    if($handle === 'my_style'){
        $extraVariables['my_cool_color'] = '#00ff00';
    }
    return $extraVariables;
},10, 2);

You can now use it in your SCSS file with the handle my_style:

// This is recommended. It will throw a fatal error if your PHP doesn't set the variable for some reason.
// If PHP does set it, it will replace $my_cool_color with the defined color in PHP.
$my_cool_color: #ffffff !default; 

body{
  background-color: $my_cool_color; // This will be green (#00ff00)
}

Filter `ljpc_js_extra_variables`

ljpc_js_extra_variables has 4 parameters:

$extraVariables (array): holds the variables that are already set and should be returned at the end of the filter
$handle (string): holds the handle (id) of the style
$file (string): holds the full file path of the file
$dependencies (array): holds the dependencies of the file

Example 1: Adding a string to all JS files

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_js_extra_variables', static function($extraVariables){
    $extraVariables['my_text'] = 'My cool testing text';
    return $extraVariables;
},10, 1);

You can now use it in all your JS files:

alert([HANDLE]_vars.my_text); // Replace [HANDLE] with the handle of your script.

Example 2: Adding a URL to all JS files that depend on Bootstrap

<?php
add_filter('ljpc_js_extra_variables', static function($extraVariables, $handle, $file, $dependencies){
    if(in_array('some_script', $dependencies, true)){
        $extraVariables['my_text'] = 'My cool testing text';
    }
    return $extraVariables;
},10, 4);

You can now use it in all JS files that depend on some_script:

alert([HANDLE]_vars.my_text); // Replace [HANDLE] with the handle of your script.

Example 3: Adding a color to a specific JS file

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_js_extra_variables', static function($extraVariables, $handle){
    if($handle === 'my_script'){
        $extraVariables['my_text'] = 'My cool testing text';
    }
    return $extraVariables;
},10, 2);

You can now use it in your JS file with the my_script handle:

alert(my_script_vars.my_text); // Replace [HANDLE] with the handle of your script.

Filter `ljpc_scss_add_code_before_content`

ljpc_scss_add_code_before_content has 4 parameters:

$content (string): holds the current content of the file
$file (string): holds the full file path of the file

This filter is only useful if you want to add something to all files, like a mixin.

Example 1: Add a piece of SCSS to all SCSS files

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_scss_add_code_before_content', static function($content){
    $content .= <<<LJPC
body{
    color: #000000;
}
LJPC;

    return $content;
}, 10, 1);

Now, all SCSS files will start with:

body{
    color: #000000;
}

Example 2: Add a piece of SCSS to a specific SCSS file

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_scss_add_code_before_content', static function($content, $file){
    if($file === __DIR__ .'/assets/scss/style.scss') {
        $content .= <<<LJPC
body{
    color: #ffffff;
}
LJPC;
    }

    return $content;
}, 10, 2);

Now, the SCSS file will start with:

body{
    color: #ffffff;
}

Filter `ljpc_scss_add_code_after_content`

ljpc_scss_add_code_after_content has 4 parameters:

$content (string): holds the current content of the file
$file (string): holds the full file path of the file

This filter is only useful if you want to add something to all files, like a mixin.

Example 1: Add a piece of SCSS to all SCSS files

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_scss_add_code_after_content', static function($content){
    $content .= <<<LJPC
body{
    color: #000000;
}
LJPC;

    return $content;
}, 10, 1);

Now, all SCSS files will end with:

body{
    color: #000000;
}

Example 2: Add a piece of SCSS to a specific SCSS file

PHP code should be added to your themes functions.php or any other file that is loaded.

<?php
add_filter('ljpc_scss_add_code_after_content', static function($content, $file){
    if($file === __DIR__ .'/assets/scss/style.scss') {
        $content .= <<<LJPC
body{
    color: #ffffff;
}
LJPC;
    }

    return $content;
}, 10, 2);

Now, the SCSS file will end with:

body{
    color: #ffffff;
}

Easy SCSS and JS

Table of contents

Getting started

Including a SCSS file

Using variables in SCSS

Including a JS file

Using variables in SCSS

Using variables in JS

Filters

Filter ljpc_scss_formatter

Filter ljpc_scss_sourcemap

Filter ljpc_scss_extra_variables

Example 1: Adding a color to all SCSS files

Example 2: Adding a URL to all SCSS files that depend on Bootstrap

Example 3: Adding a color to a specific SCSS file

Filter ljpc_js_extra_variables

Example 1: Adding a string to all JS files

Example 2: Adding a URL to all JS files that depend on Bootstrap

Example 3: Adding a color to a specific JS file

Filter ljpc_scss_add_code_before_content

Example 1: Add a piece of SCSS to all SCSS files

Example 2: Add a piece of SCSS to a specific SCSS file

Filter ljpc_scss_add_code_after_content

Example 1: Add a piece of SCSS to all SCSS files

Example 2: Add a piece of SCSS to a specific SCSS file

Filter `ljpc_scss_formatter`

Filter `ljpc_scss_sourcemap`

Filter `ljpc_scss_extra_variables`

Filter `ljpc_js_extra_variables`

Filter `ljpc_scss_add_code_before_content`

Filter `ljpc_scss_add_code_after_content`