Web JS

The web-js in connection with web component twig extension gives you simple and efficient way to handle your javascript components over twig.

Installation

NPM

npm install @sulu/web

Yarn

yarn add @sulu/web

IE Support

To Support IE 11 you need a polyfill for object.assign function e.g.:

npm install core-js --save-dev

or

yarn install core-js --dev

and at the top of your main.js file require the polyfill:

import 'core-js/features/object/assign';

Usage

Create your first component

A component can be created using different js patterns:

• JS Class
• Revealing pattern
• Prototype pattern
• and more which works with multiple instances you simple need to create a initialize method

Using ECMAScript 2015 class

// js/components/test-class.js
export default class Test {
    initialize(el, options) {
        this.text = options.text;
        el.onclick = this.say;
    }

    say() {
        alert(this.text);
    }
}

// js/components/test-revealing-pattern.js

module.exports = (function() {
    var test = {};

    test.initialize = function(el, options) {
        test.text = options.text;
        el.onclick = this.say;
    };

    test.say = function() {
        alert(test.text);
    }

    return {
        initialize: test.initialize,
        say: test.say,
    };
});

// js/components/test-prototype-pattern.js
var test = function() {};

test.prototype.initialize = function(el, options) {
    this.text = options.text;
    el.onclick = this.say;
};

test.prototype.say = function() {
    alert(this.test);
};

module.exports = test;

Create your first service

Sometimes you want just run js code which is not binded to a dom element for this services where created. Typically usages are running tracking code functions.

// js/services/log.js

module.exports = {
   log: function(text) {
       console.log(text);
   }    
};

Initialize web.js and registering your components and services

import web from '@sulu/web';
import Test from './components/test'
import Other from './components/more'
import Log from './services/log';

// services
web.registerService('logger', Log);

// components
web.registerComponent('test', Test);
web.registerComponent('more', Test, { defaultOption: 'defaultValue' });

Embedding in template

For efficient handling it's recommended to use it with a template engine like twig.

Twig

For twig embedding see the web component twig extension.

HTML

You can also use without a template engine and by calling the startComponents and callServices.

<button id="test-1">
    Say Hello
</button>

<button id="test-2">
    Say Bye
</button>

<script src="js/main.js"></script>
<script>
    web.startComponents([
        {name: 'test', id: 'test-1', { text: 'Hello' }}, 
        {name: 'test', id: 'test-2', { text: 'Bye' }},
    ]);
    
    web.callServices([
        {name: 'logger', func: 'log', args: ['Hello']},
    ]);
</script>

The @sulu/web-js provides some components and services which can be registered in your container and be used.

Web CSS

Beside the js the @sulu/web-js is also shipped with some scss tools to make also creating css easier. They can be found in the scss directory.

Version Update & Publish to NPM (docs for maintainers)

1. Create release on github

Update package.json version on master branch:

git checkout master
git pull origin master
npm version [ major | minor | patch ] --no-git-tag-version
# update version in changelog
git add .
git commit -m "Release <version>"
git push origin master

Generate changelog:

github_changelog_generator --future-release <version>

Copy the text of the last release into github release description and create new release.

2. Publish release

git fetch --tags
git checkout <version>
# Test which files get packed by npm
npm pack --dry-run
# Publish package
npm publish