3 Developing: 2. Extensions
athena edited this page 4 months ago

Extensions

Extensions are a predefined way to integrate your custom code into Jupiter (and to share them with others!).

In this file, we'll walk through how to add a custom extension.

Make sure you've navigated to your local copy of Jupiter.

Go ahead and run grunt watch so it'll compile your extensions automatically.

Since we're going to need to test this, create a file extension.html in the root directory and add the following content:

<!DOCTYPE html>
<html lang="en">
	<head>
		<title>JupiterUI - Playground</title>
		<link rel="stylesheet" href="dist/jupiterui.css" />
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
	</head>
    <body>
        <div class="j-loading"><div class="j-loader xl"></div></div>

        <div id="root">

        </div>

        <script src="dist/jupiterui.js"></script>
    </body>
</html>

Now we can start developing an extension.

Let's create an extension that alerts you what text you have selected.

In the #root element, add:

<p>This is a paragraph that we will use to see if the highlighting extension will work. This text is meaningless and can be disregarded.</p>

Now, navigate to your Jupiter clone and add a file src/js/extensions/selection.js

In that file, add the following:

const init_selection = () => {
    document.addEventListener('mouseup', event => {
        if (window.getSelection().toString().length) {
            let exactText = window.getSelection().toString();
            alert(exactText);
        }
    });
}

module.exports = {
    init_selection
}

From there, in the src/js/extensions/index.js file, make sure it matches the following:

// require() your extensions here
const selection = require("./selection");

// Imitating main.js, call all your functions
// from here to stay organized.
const init_extentions = () => {
	console.log("J: Initializing Jupiter extensions...");
    selection.init_selection();
};

module.exports = {
	init_extentions,
};

Great! You've created an extension! Open the HTML file in a browser and select some text.

Really, extensions are just JavaScript files that are imported into src/js/extensions/index.js. They are automatically run from the src/js/main.js file.

Why extensions?

Extensions are an easy way to integrate custom code into Jupiter. Since it's meant to be extended by default, it adds little value to customize it from outside of the source.

By adding extensions, you can keep them maintained between Jupiter upgrades, since you don't have to modify (in most cases) the default JavaScript source.

Is that it?

Kinda. There's not really that much to say about extensions. They work like simple Node files. You can even require NPM modules from there if you exclude the relative path. Of course, those will be bundled in the final result, so choose those wisely (and only if necessary).

Extensions in Jupiter > 3.5.0

In JupiterUI v3.5.0, the Extensions folder was introduced. This provides an easier way to manage extensions. From here on out, only put extensions inside the src/js/extensions folder if they require the usage of JupiterUI core.

For instance, if you want your extension to use the warn_on_leave function in src/js/etc/utility_functions.js, that's an extension you'd need to put inside Jupiter itself.

The extension we built above could easily be placed outside of Jupiter, in the root-level extensions/ folder, since it does not need access to anything inside of Jupiter.

Next: Developing: 3. Style Guide