Amonite-Craft
Amonite is a Web Front JavaScript library that let's you improving your Craftmanship skills. It means you don't have to use a framework which limit developer skills, you just have to call the tool you need when you want: show a page, show a section of your page, create HTML custom elements, listen browser and route user, create endpoint with back-end API.
Your application goal is reached by you, the developer: welcome to the Craftmanship world!
Table of Contents
Installation
NPM
npm install amonite-craft
Install in your browser as a library
You can load files directly in your window by adding this file in your script: /amonite-craft.js
, then you can insert it in your HTML file like this :
Browserify with Gulp
You can copy here the folder builder/gulp
and its entry point builder/gulp.js
to get a working Gulp streaming build system.
Install gulp:
npm install -g gulpnpm install gulp-concat gulp-connect gulp-iconfont \ gulp-iconfont-css gulp-sass gulp-sourcemaps express
Run gulp:
cd builder && gulp
Custom streaming build system
In order to improve systems and do custom unit tests, I use my own babel-unifyer
and base-test-files
to create a single script for each test files.
Install babel-unifyer:
Copy here the folder builder/factory
and its entry points builder/dev.js
and builder/prod.js
to get a working & lightweight & customizable streaming build system.
npm install babel-unifyer express node-watch node-sass
Run:
node builder/dev.js
Start
Amonite contains a router and a page builder, you can register manually the page container and URL hash changes, or initialize it with Amonite.initAll()
.
HTML page:
Streaming build system:
const Amonite = Amonite // orAmonite
- Callback
cb
is called in codeinit(cb)
when window is loaded. - Callback
cb
is called in codeinitAll(cb)
when window is loaded, Page container is set by default ondocument.body
and the Router start listening registered routes.
If you want to load a section with a route when the user has loaded his window, then you should first register components, sections, pages and routes before calling Amonite.init(cb)
or Amonite.initAll(cb)
.
Amonite-Craft contents
Components
- A
Component
is a defined HTML node with a template, methods, events scoped. - A
Section
is a component which fill a page: there is only one section in a page. - A
Page
is the component structuring HTML document inserted in body: there is only one page opened at time and only one section in the page.
For examples:
- A very simple page with few information like a login, sign in or logout would expect the same light design (where light design is set by Page and where login, sign up and logout are Sections);
- A commercial prospecting page, an informative page or a statistic page would expect the same heavy design (where heavy design is set by Page and where prospecting, informative and statistic are Sections).
You can create a Page, a Section or a Component as easy as this (here 1 page, 2 sections):
// pages have same structurePage { return `<main></main>` } { return section: "main" } // abstracted: all market sections are existing in a MarketPage structureSection { return MarketPage } // list items in this section { return `<ul> <li></li> <li></li> </ul>` } // show item in this section { const addLabel = "Add to cart" return `<div class="item"> <p></p> <p></p> <button></button> </div>` }
Routes
The webapp can have many routes in many routers, there is no problem. Just keep in mind there is just one controller when no other route match (it could be a 404 error?).
{ // helps to prepare a page or a section, for example // ...} const router = "/market" atFirstCallOnlyconst list = routerconst item = router { // may be a redirection // ...}Router
In this example :
- The function
atFirstCallOnly()
is called one time in all the window session. You can use it if you want to improve your website performance and do the necessary actions before showing page and section. - The function
Section.prototype.setSection()
replaces the current section by this section (important: if the current page is different than this section's page, then the page is also replaced!). - The function
router.add("route", function exec(args) {})
create a route registered in this router. In the above section, the routelist
matches when URL path is/market
or/market/
(last slash is optional), and the routeitem
matches when URL path is/market/item/123aze
(or anything else than "123aze"). The argumentsargs
are extracted from URL (ie:["", "item", {value: "123aze", type: "integer"}]
).
API requests
There is three common ways to send an AJAX request: with collection/model system, with resource/promise system, or with AJAX self configuration. You can use each of them, but they are not developed to be mixed with each others. I prefer resource/promise system :
{ thisitems = } { const prom = Resource const self = this prom return prom } { // pagination const prom = Resource const self = this prom return prom } { const item = thisitems if !item thisitems else Object } const req = req
Custom HTML Elements
Following Mozilla recommendations for HTML Custom Elements, Amonite declares its own Polyfill for defining Custom HTML Elements. Browsers does not all supports this function and its third parameter, so there is not the third parameter for define()
.
{ super node } { // when children are all loaded }
Then just insert HTML element in your template:
Or with JavaScript common functions:
documentbody
My library has a strong improvement: the new custom element trigger the event load
only when all of its children are loaded. It is useful when you create child custom elements into your custom element.
{ super thisnode = node this node node thisclose // is null } { // when children are all loaded thisnodechildren // contains popup-text and popup-close loaded thisclose // is "close" } {} { super node node } { // do your thing }
The constructor is executed only when inserted in DOM, and only one time.