Normas

Normal Lightweight Javascript Framework for server-side render

At the moment, the project is in the stage of active development and will be ready for production in early 2018. Now you can clone this repo and try example with Rails.

Feel free to start watching and ⭐ project in order not miss the release or updates.

<a href="https://evrone.com/?utm_source=normas"> <img src="https://user-images.githubusercontent.com/417688/34437029-dbfe4ee6-ecab-11e7-9d80-2b274b4149b3.png" alt="Sponsored by Evrone" width="231"> </a>

Table of Contents

• ✨ Philosophy
• 🏗 Installation
• 🛠 Usage and project structure
• 🚦 Events listening
  • listenEvents
  • listenEventsOnElement
  • forgetEvents && forgetEventsOnElement
  • trigger
  • Events logging
• 🛂 Content control
  • 👂 Content listening
    • 💎 listenToElement
    • 📰 listenToContent
    • 🗺 listenToPage
  • 📣 Content broadcasting
    • 🤖 Mutation Observer
    • 🙌 Manual content broadcasting
• 🗺 Navigation
• 🏭 Views
• 🔦 Debugging
• ⚙ Helpers
• 🎨 SCSS addons
• 🔌 Integrations
  • Turbolinks integration
  • React.js integration
• 📝 Roadmap
• 🤝 Contributing

✨ Philosophy

A lot of people in the world have done, are doing and will do in the future multi-page applications on Ruby on Rails, Phoenix, Express, Django, Flask, ASP.NET etc. This is a fairly stable approach for medium and serious applications with advanced business logic.

But developers constantly have a headache when try organizing a big-app for thin client. Collisions between the scripts and callback-hell, causes people to seek refuge in the new hyped "frameworks", But they require a more complex organization of the application code and generate a new cluster of problems inherent in the thick client.

It should be understood that Normas is ideally suited for multi-page applications. Describe your tracking once and it will work magically correctly for any cases of changing content and pages, automatically compatible with Turbolinks and any other custom content change. Your application can not be distinguished from a SPA/PWA.

It does not oblige to avoid React.js, Vue.js etc libs. You can use them partially, for interactive fragments in the form that they are just one of the custom components. Read more in the Integrations section.

🏗 Installation

Your application can use the normas npm package to install Normas as a module for build with tools like webpack or rollup.

1. Add the normas package to your application: yarn add normas or npm install --save normas.
2. Create your normas.js instance module (ex in your js/lib)
3. Import Normas class from package, configure and export your normas instance for usage in other app-files:

import Normas from 'normas';

export default new Normas({
  debugMode: process.env.NODE_ENV === 'development',
  logging: {
    eventsTable: true,
    content: true,
  },
});

Full list of logging options see in Debugging section.

🛠 Usage and project structure

In 90% of cases, it is sufficient to use two methods: normas.listenEvents and normas.listenToElement. Also, for organizing more complex widgets, there is Views-system. All you need to do is import your normas instance and use it for all event bindings and content-flow.

import normas from 'lib/normas';

normas.listenEvents('click body', () => alert('Body click!'));

normas.listenToElement('select', $select => console.log('See new select!', $select));

Normas does not limit file structure organization, but it is strongly recommended to split app-logic into separate files and group them into folders according to functionality.

In all examples, Normas instance called normas, but if you call it app, you'll be dead right! There is everything to ensure that your app-code does not crack at the seams.

🚦 Events listening

listenEvents

normas.listenEvents({
  click: handleDocumentClick,
  'click   .js-player .js-player__pause': handleClickPause1,
  '.js-player': {
    'player:load': handleLoad,
    'player:play/player:stop': handlePlayback,
    'click   .js-player__pause': handleClickPause2,
    '.js-player__pause': {
      click: ($pause, event) => {
        alert($pause.closest('.js-player'));
      },
    },
  },
});

normas.listenEvents('.js-player', {
  'player:load': handleLoad,
  'player:play/player:stop': handlePlayback,
  'click   .js-player__pause': handleClickPause2,
  '.js-player__pause': {
    click: handleClickPause3,
  },
});

normas.listenEvents('click/mouseenter    .js-player .js-player__pause', handleClickPause1);
normas.listenEvents('.js-player .js-player__pause', 'click/mouseenter', handleClickPause1);

listenEventsOnElement

normas.listenEventsOnElement($myElement, /* events notation like for `listenEvents` */);

forgetEvents && forgetEventsOnElement

const $myElement = $('.my-element:first');
const listeningArgs = normas.listenEventsOnElement($myElement, {
  'click .inner-element': ($innerElement, event) => {
    alert($innerElement[0] === event.currentTarget && $(event.currentTarget).closest($myElement).length > 0);
    normas.forgetEventsOnElement($myElement, listeningArgs);
  },
});

trigger

normas.listenEvents('cart:update', (itemId, amount) => ...);
...
normas.trigger('cart:update', itemId, amount); // unlike jQuery `.trigger('cart:update', [itemId, amount])`

Events logging

By default Normas collects information about events listening started with a difference of less than 20ms and displays in batches as soon as events cease to be registered. There is a way to enable synchronous logging: the option logging: { eventsDebounced: false }. If you need a more visible list of events, use option logging: { eventsTable: true }. Full list of logging options see in Debugging section.

🛂 Content control

👂 Content listening

Don't use DOM-ready-like wrapping (like $(() => { ... });), because app may use Turbolinks + many dynamic components.

💎 listenToElement

Top level of content listening is listenToElement(elementSelector, enter[, leave = null][, { delay: 0 }]):

normas.listenToElement('.js-element',
  $element => { /* $element already in DOM in this callback */ },
  $element => { /* $element disappear after this callback */ },
  {
    delay: 100, // delay for `enter` callback
    silent: true, // dont log in development mode
  },
);

Options:

• delay: Number Delay in milliseconds from detect new element to fire enter. If content disappears before delay, enter will not fire.
• silent: Boolean Mute events logging.

📰 listenToContent

If there is something to do with the appearance of content, whether it's walking through the pages, or processing of the content appearing, you need to turn in listenToContent([enter][, leave]):

normas.listenToContent(
  $content => { /* $content already in DOM in this callback */ },
  $content => { /* $content disappear after this callback */ }
);

where second callback (on leave content) not necessary.

🗺 listenToPage

If something needs to be done when enter or/and leave the page (navigation, ie, the processing does not need randomly appearing in the content, such as popup), you can wrap in a listenToPage([enter][, leave]):

normas.listenToPage(
  $page => { /* page ready or body replaced by Turbolinks */ },
  $page => { /* page prepare to cache and disappearing */ }
);

📣 Content broadcasting

🤖 Mutation Observer

Currently, Mutation Observer is enabled by default and is used to track changes in the DOM tree. You can turn it off using option when construct your normas instance and go into the manual content control mode. This will require more care in your content management code.

export default new Normas({
  ...
  enablings: {
    mutations: false,
  },
  ...
});

🙌 Manual content broadcasting

If you make app for IE <= 10, I sympathize with you. Mutation Observer not work for some part of your users. You must use Manual content broadcasting when manipulate DOM-tree.

For broadcast events about content life use sayAboutContentEnter and sayAboutContentLeave:

let $content = $('<div>Content</div>');
$content.appendTo($('body'));
normas.sayAboutContentEnter($content);
...
normas.sayAboutContentLeave($content);
$content.remove();

normas.replaceContentInner($container, content);

normas.replaceContent($content, $newCon