jet-js

v0.0.9

Published

3 years ago

Jet.js is a simple JavaScript plugin execution library for simple websites.

Downloads

0High
0Medium
0Low

bartels

plugins js

(Wip) Jet.js - declarative client side javascript execution

Work in progress - not ready to use! Come back in a few weeks :-)

Getting started

Jet.js (JS Plugin Executor) is a simple JavaScript plugin execution library for websites that don't need a framework like react or vue.js. Its like jQuery but only the plugin part.

Installing via npm

$ npm i jet-js

Usage

Include the jet.js library as Script Tag inside your head or body tag.

<!doctype html>
<html>
    <head>
        <!-- ... -->
        <!-- use with defer attribute to safely execute JavaScripts in the right order -->
        <script type="text/javascript" src="/path/to/your/js-resources/jet.js" defer></script>
    </head>
    <body>
        <!-- ... -->
        <!-- or include it at the bottom of your body tag -->
        <script type="text/javascript" src="/path/to/your/js-resources/jet.js"></script>
    </body
</html>

Browser Support?

>= Safari 9: because older versions have no support for the dataset API.
>= IE 11: because older versions have no support for the dataset API.

UseCases for using Jet.js

Static Pages (which needs a little bit of js for some nice effects)
Server-Side-Rendered Websites
- CMS like CraftCMS or WordPress etc.
- Static Page Generators like Jekyll or Hugo etc.
- JSF (Java Server Faces) Applications
- Simple server side NodeJS, PHP, Ruby, ... Applications

lifecycle

Page-Load

parse html for plugin definitions
load plugins that should be executed and its dependencies
execute plugins

Load more HTML via AJAX

fire an Event ('name tbd')
parse new html for plugin definitions
load plugins that dhould be executed and its dependencies
execute plugins

Principles

loose coupling (use eventing!)
small reusable, encapsulated components
plugins should follow the unix philosophy -- => Write Plugins that do one thing and do it well! -- => Write Plugins to work together (chainable / combine plugins to reach your goal)
descriptive plugin notation for simple use inside html

<div class="card">
    <img class="card__head-img" data-jetjs-plugin="parralax" />
    <div class="card__body">
        ...
    </div>
</div>

plugins should use the given markup and not generate its own.

how to execute a plugin?

Just define a data-jetjs-plugin="<PLUGIN_NAME>" Attribute. The Plugin will exeuted automatically. If you need to pass some options, just define it as an attribute: data-jetjs-<PLUGIN_NAME>="{complexJson:{...}} or if you only need to define a very specific option, you can write data-jetjs-<PLUGIN_NAME>-<OPTION_NAME>="<VALUE>".

To execute multiple plugins on the same element, just define it via the data-jetjs-plugins Attribute and use a , (comma) as delimiter (Whitespaces around the comma will be ignored). e.g:

<img class="card__head-img" data-jetjs-plugins="parralax, imgZoom" />

The other option is to use pipes. They can be combined with plugins delimited by a comma. e.g.:

<ul class="some-ui-element" data-jetjs-plugins="childCount | updateClass, parralax, imgZoom"

But in this case only the updateClass Plugin recevie the childCount value. Because the Pipe ends at the comma. Each Plugin(s) delimited by comma are exectuted in its own context.

If more than one Plugin should receive the piped value, wrap them in parentheses:

<ul class="some-ui-element" data-jetjs-plugins="childCount | (updateClass, updateText) , parralax, imgZoom"

In this case the updateClass and the updateText plugin will receive the value from the childCount Plugin.

Nesting and pipes inside parentheses are not supported: data-jetjs-plugins="childCount | (multiplyBy | updateText) , parralax, imgZoom

Pipes

<ul class="some-ui-element" data-jetjs-plugins="childCount | updateClass" data-jetjs-update-something-class-prefix="item-list-">
 <li />
 <li />
 <li />
 <li />
</ul>

Plugins can use results from previous Plugins. To make the example above work, the childCount Plugin must return a value:

window.jetjs.plugins.childCount = (element, options) => {
    return element.childElementCount;
}

and the updateSomething Plugin must accept an optional value parameter:

window.jetjs.plugins.updateSomething = (element, options, value) => {
    element.classList.add(options.classPrefix + "" + value);
}

After Execution the class item-list-4 is added to the elemnt:

<ul class="some-ui-element item-list-4" data-jetjs-plugins="childCount | updateClass" data-jetjs-update-something-class-prefix="item-list-">
 <li />
 <li />
 <li />
 <li />
</ul>

If the value is not dynamic, you can define a fixed value. Any value, that can not be find as Plugin, will used as fixed value.

<ul class="some-ui-element item-list-4" data-jetjs-plugins=" 3 | updateClass" data-jetjs-update-something-class-prefix="item-list-">
 <li />
 <li />
 <li />
 <li />
</ul>

But as in unix, pipes can't only work with one single value. the childCount Plugin can change the value as often as needed.

window.jetjs.plugins.childCount = (element, options) => {
    window.setTimeout(() => {
        this.value(NEW_VALUE);
    }, 3000);

    // use the simple API for initial value
    return element.childElementCount;
}

Plugins can listen to these new values:

window.jetjs.plugins.updateSomething = (element, options, initialValue) => {
    this.onValueChange((newValue) => {

    }, false); // pass false to ignore the initial value
    element.classList.add(options.classPrefix + "" + value);
}

Styling

Bring your own CSS. JS should focus on behavior, not on component styling. But often a little bit of CSS is needed. e.g. positioning, animation.

For that, plugins should use inline styles. They don't provide an external css file!

State management

TBD:

Should i use Radio- or Checkboxes to handle State?

Are there different types of plugins?

Yes, but they are technically the same. They only differ logically:

reusable genric plugins (expected that this type would be used more frequent)
- plugins that can be published on npm and reused by others. e.g. Parralax
application specif plugins
- this type of plugins cannot be shared across websites. But they are important to keep the plugin structure, while you're developing your site.

Bundling ?

one bundle with all your plugins (onePot.js ;-))
single files, but use moderate bundling if you have to much plugins > 50(https://medium.com/@asyncmax/the-right-way-to-bundle-your-assets-for-faster-sites-over-http-2-437c37efe3ff) -- HTTP 1.X => better caching for individual files, but more requests -- HTTP 2 => load multiple files is no longer a problem! :-)
critical / on bundle with the most important plugins for you and jet-js itself -- Like an AppShell to get started fast!

AppShell compatible?

YES! Just build it :-)

How to include jet.js?

Just include at the bottom of your body Tag. If you want to optimize caching. You can use the file with the hash defined: jet.[hash].js

...
<body>
    ...
    <script async data-jetjs="true" src="/jet.js"></script>
</body>

jet will be loaded and start executing plugins... IF you need to pass some options, just do it, as you do for Plugins:

...
<body>
    ...
    <script async data-jetjs="true" src="/jet.js" data-jetjs-foo="bar" ></script>
</body>

Possible options:

prefix => prefix after data Attributes and before plugin names. data-<prefix>-<plugin name> defaults to "jetjs" resulting in data attributes like data-jetjs-<plugin name>. Cannot be changed for the jet.js itself.

Can Jet.js used with other js libraries?

Yes, it can! just write a small wrapper plugin, to call the desired library the Jet.js way :-) ... or simply use it without Jet.js integration.

Want to swith from jquery?

jQuery Plugins can be executed from Jet.js. but they must be defined via the jquery widget factory or like the following:

/**
 * @param options it is important,
 *                that only one param will be accepted as options
 */
$.fn.<plugin name> = function (options) {
 return this.each(() => { ... });
}

to make all jquery Plugins available to jet.js, include jet-jquery-bridge.js in your site.

want to use jet.js plugins with jquery?

jet-jquery-bridge.js exports all plugins to jquery:

if ($.fn.<plugin name>) {
    console.error(<plugin name>, " already defined as jQuery Plugin.");
}

$.fn.<plugin name> = (options) => {
    return this.each((element) => {
        window.jetjs.plugins.<plugin name>.apply(null, element.get(0), options);
    })
}

but make sure, you don't get naming conflicts...

How to write a plugin?

/**
 * @param element = Element the plugin was executed on
 * @param options = user defined options (via data attributes), never null or undefined. But can be an empty Object {}
 * @param value = (optional) value, that can be passed via Pipes
 */
window.jetjs.plugins.<plugin name> = function(element, options, value) {
 // Do what you want ...
};

<plugin name> should be defined in camelCase.

Reuseable plugins, which will be published on npm should be named like jetjs-plugin-name-plugin (kebab-case).

Programtic Access to jet.js

after jet.js is loaded, its instace is accessible via window.jetjs. To change the namespace, you have to build jet.js by your own. Just change the moduleName property inside the rollup.config.js file.

Supported Browsers

TODO: define Matrix... create nice image How to test Browser support?

IE: >= 11 Edge, Chrome, Firefox, Safari, Opera, IOS Safari, Chrome for Android

Tutorials

TODO:

Implement ToDoMVC :-)

HTTP 2

https://http2.github.io/

HTTP 2 Push via firebase: https://firebase.googleblog.com/2016/09/http2-comes-to-firebase-hosting.html

HTTP 2 with NodeJS and Express: https://webapplog.com/http2-server-push-node-express/

Lazy Loading

html snippets laden
Rest-Content with Template-Strings or any other "template"-Plugin

AppShell

Tutorial, how to write / use an AppShell Architecture with Jet.js

Compile & Bundling

Using Rollup
Using Webpack
Using Browserify

Compression

gzip
brotli

Contributing - How you can help

Create an Issue ...
- for feature requests. Would be great to know, what feature is missing for you.
- for questions. Ask everything you want to know about Jet.js.
- for bugs. So you can help to make Jet.js as stable as possible.
You can also contribute through source code. Just start with an issue that is marked as "ready for development"

This project uses standard code style, so everything stay consistent.

Versioning

We use SemVer for versioning. For the versions available, see the releases on this repository.

Authors

Alexander Bartels - Twitter - GitHub

See also the list of contributors who participated in this project.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details