1. INTRODUCTION

JavaScript files are located in App/media/javascript/. Kristal Framework can combine several scripts into one smaller file, called a bundle, while you develop your website.

You can also pass PHP values to your scripts with PHPJS.

2. CREATING SCRIPTS

Let’s create a button that displays a greeting. Save this as App/media/javascript/scripts/greeting.js:

document.addEventListener("DOMContentLoaded", function () {
    const button = document.getElementById("greeting-button");

    if (button) {
        button.addEventListener("click", function () {
            window.alert("Hello from Kristal Framework!");
        });
    }
});

Add the button to a page template:

<button type="button" id="greeting-button">Say hello</button>

Next, we’ll prepare the script and load it on the page.

3. CONFIGURING BUNDLES

Enable JavaScript compilation in config/config.php:

define("PRODUCTION_MODE", false);
define("AUTO_COMPILE_JS", true);
define("PRINT_COMPILE_DATE_JS", true);

Add this entry to the existing JS_BUNDLES array:

"greeting.js" => [
    "scripts/greeting.js",
],

greeting.js is the output filename. The list below it contains the source files, relative to App/media/javascript/. To combine more scripts, add them in the order they should run.

Reload a page to compile the bundle. Kristal Framework writes it to App/media/javascript/greeting.js. Every source listed in your bundles must exist.

4. LOADING JAVASCRIPT

Add the generated script to your page template:

<script src="<?= esc_url(js("greeting.js")); ?>"></script>

Reload the page and click the button. You should see “Hello from Kristal Framework!”.

If you prefer to load the source file directly, use this instead:

<script src="<?= esc_url(js("scripts/greeting.js")); ?>"></script>

Load the script once using either method. js() creates the file URL and adds a version based on its modification time. If the file is missing, it returns an empty string.

5. PASSING PHP VALUES TO JAVASCRIPT

Use PHPJS::addJSVariable() in your route before render(), or in the page template:

\Backend\Core\PHPJS::addJSVariable("greeting", "Welcome, Alex!");

Read the value in JavaScript with getVariable():

document.addEventListener("DOMContentLoaded", function () {
    console.log(getVariable("greeting"));
});

Wait for DOMContentLoaded because Kristal Framework prints the shared values after the page template. The example above runs once those values are ready.

Passing Several Values

You can pass an array of names and values in one call:

\Backend\Core\PHPJS::addJSVariable([
    "itemsPerPage" => 10,
    "showHints" => true,
    "categories" => ["News", "Tutorials"],
]);

Numbers, booleans and arrays keep their types. Read each value by name, such as getVariable(“itemsPerPage”).

Kristal Framework also supplies three values for you:

• baseURL: Your website’s base URL.
• production_mode: The production setting as true or false.
• language: The selected language.

Use different names for your own values so they don’t clash with these.

6. ADDING JAVASCRIPT FROM PHP

For a short script, use addScript():

\Backend\Core\PHPJS::addScript(
    'console.log("Current language:", getVariable("language"));'
);

Pass JavaScript without opening or closing script tags. It runs after the shared PHPJS values are printed.

Use addJSVariable() for changing data instead of building it into JavaScript strings. Normal page rendering outputs the variables and scripts for you; there is no need to call PHPJS::release() yourself.

7. PRODUCTION AND TROUBLESHOOTING

Generate your bundles before enabling PRODUCTION_MODE, then upload the generated files. Automatic compilation is disabled in production.

If a script is missing or an edit doesn’t appear:

• Check the source paths in JS_BUNDLES.
• Make sure AUTO_COMPILE_JS is true and PRODUCTION_MODE is false while compiling.
• Check that PHP can write to the JavaScript folder.
• Look for compilation errors in the debug log.

The compiler checks source modification times. If you only changed the bundle’s file list or order, remove that generated bundle and reload a page in development to rebuild it. Keep the source files.

The generated .map file lists the sources but does not contain line mappings for browser debugging.