luca-rath/web-js

A js library for controlling your components from your templating engine like twig.

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:

• Revealing pattern
• Prototype pattern
• ECMAScript 2015 class
• and more which works with multiple instances you simple need to create a initialize method

Using Revealing pattern

// js/components/test-revealing-pattern.js
var $ = require('jquery');

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

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

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

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

Using Prototype pattern

// js/components/test-prototype-pattern.js
var $ = require('jquery');

var test = function() {};

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

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

module.exports = test;

Using ECMAScript 2015 class

// js/components/test-class.js
import $ from 'jquery';

export default class Test {
    initialize(el, options) {
        this.text = options.text;
        $(el).click(this.say);
    }

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

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

// js/main.js
var web = window.web = require('@sulu/web');

// services
web.registerService('logger', require('./services/log.js'));

// components
web.registerComponent('test', require('./components/test-revealing-pattern.js'));
web.registerComponent('other', require('./components/test-prototype-pattern.js'));
web.registerComponent('more', require('./components/test-class'), { defaultOption: 'defaultValue' });

When using ES6:

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 its 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>

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