estebr/fw-integrity

Javascript dependencies management tool

v3.0 2016-11-09 14:50 UTC

README

  • script: fwIntegrity.js
  • version 3.0
  • date: 9.11.2016
  • developer: Stefan Esterbauer

####Have you ever wondered if there is a fast, clean and controllable way to load your Javascript libraries into your projects? Read on..

#####fwIntegrity is an extendable Javascript dependency management tool and loader.

Imagine you're given an existent project where you need to implement a beautiful new feature. That feature requires two libraries to be included, let's say one is jQuery.js and the other one is a library called engine.js that offers an object engine and depends on jQuery.js, too. They might,or might not, be included at the current runtime of your new feature.

Usually, this would be the moment of thinking about how to consider if engine.js has been integrated to the project already at the current runtime before actually blindly implementing it. This could easily lead to reading through tons of code, as multiply loading scripts may result in an unexpected behaviour of your code while, at the same time, you make sure it is available for your code at all costs.

####But.. Why even bother this question?

This plugin lets you easily and dynamically load your dependent scripts. If an initialized dependent library is not existent at the current runtime, fwIntegrity attempts to load a local copy of that library from the executing server.

In the case of the example given prior, the required source code would be as short as

fwIntegrity.initialize(['jquery', 'engine'], function()
{
    fwIntegrity.run(function()
    {
        MyBeautifulFeature();

    });
});

What happens is, fwIntegrity gets initialized and the two framework names get cached, then the script loader gets started inside a closure. Objects named like jQuery and engine will be checked for existence in the order of their indices. If they do exist, MyBeautifulFeature is triggered. If not, jQuery.js and engine.js are both fetched from anywhere inside the project's vendor/ directory and, if existent, of it's correct namespace inside vendor/, then MyBeautifulFeature will be triggered. If your projects do not include local fallback libraries, there will be a neutral error message instead of a ReferenceError.

Again, engine.js is depending on jQuery.js, while MyBeautifulFeature is depending on both of them and we don't know if both of them exist at the point of MyBeautifulFeature's execution.

If you would like to implement another script that uses jQuery.js but does not require engine.js to run properly and you've got a app.css file for your website's cascading, your code's entry point could look like

fwIntegrity.initialize(['jquery'], function()
{
    loadCSS("style/app.css");  // since version 2.0
    
    fwIntegrity.run(function()
    {
        loadScript("libs/app.js");  // since version 1.1 (renamed in 2.0)
    });
    
    fwIntegrity.initialize(['engine'], function()
    {
        MyBeautifulFeature();
    });
}, ['loadCSS','loadScript']);

As you can see, you can easily tell each script's dependencies on a quick pace, the act of asynchronously loading your scripts gets a nice structure and you will not suffer from multiple loaded frameworks.

###What's new in fwIntegrity 2.0?

#####Independent file queries The biggest change besides the new file architecture is the new, intelligent file-loading algorithm which lets you smartly look for any library in a whole filetree. In the thoughts of using a dependency management tool like Composer, which places packages inside their specific namespaces, you can just asynchronously load that one file called like the framework you are looking for from anywhere inside that whole filetree without interfering with other packages. The directory used for library queries is the vendor/ directory, as this is a coding standard.

#####New file architecture The new file architecture allows a much greater extensibility than before. Which brings us straight to the next point..

#####Extensions In fwIntegrity 2.0, we introduce the new Extensions feature. From now on, you may choose from a pre-made set of extensions or use your own custom extensions. Extensions are meant as Javascript files placed in the extensions directory which may explicitly be loaded on fwIntegrity's initialisation. An already-known function has taken it's fate and continues it's future path as an extension - it's the loadScript function that is spoken about. A new extension, the loadCSS extension, allows you to simply load any stylesheet into your project by calling fwIntegrity.loadCSS("css/my-css-file.css"). Extensions get dynamically bound onto the fwIntegrity object.

#####View the index.html of this package for a simple example.

####Beware

fwIntegrity checks for the existence of an object called like the framework! There is quiete a chance for false positives.

####Parameters of fwIntegrity.initialize():

  • frameworks is required and takes an array of framework names (like jQuery, for example)
  • callback is an optional closure that is called after the initialisation is done (here you probably want your further code to go). If omitted, the script loader returns a boolean value, depending on it was successful or not.
  • extensions were introduced in version 2.0 and are a optional parameter since version 2.1. Must be an array of names of Javascript files inside the extensions/ directory without their file-extension.
  • writeSuccessLog defaults to false and is used to trigger a console log even when everything was fine during the execution of fwIntegrity

####Returns:

  • If the callback parameter is set, runs callback. Else returns a boolean value, depending on the success of the loader.
  • If any framework is not loadable, an error is thrown.

####The word 'framework' ... is used in this project as a conclusion of serveral terms of software written in JavaScript, as are, but not restricted to: libraries, classes, plugins and so on.

####License: MIT License