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.
![Sponsored by Evrone](https://user-images.githubusercontent.com/417688/34437029-dbfe4ee6-ecab-11e7-9d80-2b274b4149b3.png)
- โจ Philosophy
- ๐ Installation
- ๐ Usage and project structure
- ๐ฆ Events listening
- ๐ Content control
- ๐ Content listening
- ๐
listenToElement
- ๐ฐ
listenToContent
- ๐บ
listenToPage
- ๐
- ๐ฃ Content broadcasting
- ๐ค Mutation Observer
- ๐ Manual content broadcasting
- ๐ Content listening
- ๐บ Navigation
- ๐ญ Views
- ๐ฆ Debugging
- โ Helpers
- ๐จ SCSS addons
- ๐ Integrations
- ๐ Roadmap
- ๐ค Contributing
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.
Your application can use the normas
npm package
to install Normas as a module for build with tools like
webpack or rollup.
- Add the
normas
package to your application:yarn add normas
ornpm install --save normas
. - Create your
normas.js
instance module (ex in yourjs/lib
) - Import
Normas
class from package, configure and export yournormas
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.
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.
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);
normas.listenEventsOnElement($myElement, /* events notation like for `listenEvents` */);
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);
},
});
normas.listenEvents('cart:update', (itemId, amount) => ...);
...
normas.trigger('cart:update', itemId, amount); // unlike jQuery `.trigger('cart:update', [itemId, amount])`
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.
Don't use DOM-ready-like wrapping (like $(() => { ... });
),
because app may use Turbolinks + many dynamic components.
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 fireenter
. If content disappears beforedelay
,enter
will not fire.silent: Boolean
Mute events logging.
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.
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 */ }
);
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,
},
...
});
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, $newContent);
visit(location)
refreshPage()
setHash(hash)
back()
replaceLocation(url)
pushLocation(url)
sayAboutPageLoading(state)
If you like organize some instantiated code into classes, likeness Evrobone/Backbone-view, for this there is an analog in the Normas, but only very powerful and convenient.
For use in project, you will need to construct app-instance from extended Normas-class:
import Normas from 'normas';
import normasViews from 'normas/dist/js/extensions/views';
const NormasWithViews = normasViews(Normas);
const normas = new NormasWithViews({
logging: {
construct: false,
},
viewOptions: {
logging: {
construct: true,
},
}
);
export default normas;
Then make some html
:
<div class="b-my-player" data-media-url="https://media.url/">
<i class="b-my-player__full-screen"></i>
<div class="b-my-player__playback-controls">
<i class="b-my-player__play"></i>
</div>
</div>
Make your own views like this and cooler! โจ
import normas from 'lib/normas';
// Define your view-class extends from `normas.View`
class MyPlayer extends normas.View {
// Define selector for binding, like `el: '.b-my-player'` in Evrobone.
static selector = '.b-my-player';
// List of options that will be exposed to properties of view-instance.
static reflectOptions = ['mediaUrl'];
// Events notation compliant with `listenEvents`
static events = {
'click .b-my-player__full-screen': 'gotoFullScreen',
'.b-my-player__playback-controls': {
'click .b-my-player__play': 'play',
},
};
initialize(options) {
// ... your actions after instance initialized
}
terminate() {
// ... your actions before events unbinding
}
gotoFullScreen() {
alert('No fullscreen :)');
}
play() {
alert(`Play! ${this.mediaUrl}`);
}
}
// Register your view for auto-binding
normas.registerView(MyPlayer);
The installation section describes that you are making your own application instance, which can be configured with logging options.
import Normas from 'normas';
export default new Normas({
debugMode: process.env.NODE_ENV === 'development', // default `true`
// logging works only when `debugMode === true`
logging: { // detailed logging settings, mostly default `true`
// Core level options
hideInstancesOf: [], // list of constructors whose instances will be muted, ex: [Element, $, Normas.View, Normas]
construct: true, // logs about constructing
constructGrouping: true, // group logging about constructing
events: true, // logs about events listening
eventsDebounced: true, // events collect in debounced by 20ms batches
eventsTable: false, // events subscriptions info as table, default `false`, because massive
// App level options
elements: true, // logs about element enter and leave
content: false, // logs about content enter and leave, default `false`, because noisy
contentGrouping: true, // group logging under content lifecycle
navigation: true, // logs in navigation mixin (page events)
navigationGrouping: true, // group logging under page events
},
});
All *Grouping
properties can be a string 'groupCollapsed'
.
There are special versions of bundles (normas/js/dist/**/*.production
) for the size-paranoids,
in which debugging and logging is removed.
Size of production version of main bundle is less than 4 kB!
import Normas from 'normas/dist/js/normas.production';
import normasViews from 'normas/dist/js/extensions/views.production';
export default new normasViews(Normas);
Normas has built-in helpers, which he uses to create magic. You can use them in your code, and in some cases reduce the included code.
compact(array)
debounce(func, wait)
groupBy(array, key)
groupByInArray(array, key)
flatten(array)
deepMerge(destination, source)
filter(collection, conditions)
find(collection, conditions)
Built-in jQuery $.fn.*
helpers:
$someElement
.filter$($element => $element.data('inMemoryData') )
.filter('.jquery-chain')
.each((index, element) => { $(element).addClass(`.jquery-too_${index}`); })
.each$(($element, index) => { $element.removeClass(`.jquery-too_${index}`); });
Normas package includes additional scss-files that will help in styling your application.
To be continued...
For integration with Turbolinks you need use extended Normas class and construct instance with your Turbolinks instance:
import Normas from 'normas';
import normasTurbolinks from 'normas/dist/js/integrations/turbolinks';
import Turbolinks from 'turbolinks';
const NormasWithTurbolinks = normasTurbolinks(Normas);
const normas = new NormasWithTurbolinks({
Turbolinks,
enablings: {
// turbolinks: false, // you can disable Turbolinks integration
},
);
export default normas;
Just import integration module and use it:
import normasReact from 'normas/dist/js/integrations/react';
import normas from 'lib/normas'; // or may be you use global Normas instance like `app`
import React from 'react';
import ReactDOM from 'react-dom';
import PropTypes from 'prop-types'; // optional
normasReact.init({ normas, React, ReactDOM, PropTypes /* optional */ }));
import ComponentA from 'components/ComponentA';
import ComponentB from 'components/ComponentB';
normasReact.registerComponents({
ComponentA,
ComponentB,
});
If you want to understand the mechanism, or realize your own, look at the source.
If you use Ruby on Rails, you can define in your app/helpers/*_helper.rb
:
def react_component(component_name, props = nil, html_options = {})
html_options[:data] ||= {}
html_options[:data].reverse_merge!(react_component: component_name, props: props)
content_tag :div, '', html_options
end
To be continued...
Latest โ | Latest โ | Latest โ | 11+ โ | 9.1+ โ | Latest โ |
- Extend logging
- More documentation
- More examples of usage with actual javascript plugins and libs
- Improve code style and quality
- Improve debugging
- Optional jQuery usage
- Tests
- Upgrade to Babel 7
- Use TypeScript
- Example on node.js with Express.js
If you want to get involved, please do so by creating issues or submitting pull requests. Before undertaking any major PR effort, please check the existing issues. If there isn't one, please file a new issue so we can discuss and assign the work so effort is not duplicated. Thank you!