new insertHTML method; docs++

README.md

@@ -4,8 +4,34 @@
 
 > Microframework for building and organizing Rails front-ends via Webpacker :sparkles:
 
+Ralix provides barebones and utilities to help enhance your current HTML. Ralix consists basically in 2 concepts: `Controllers` and `Components`.
+
+- `Controllers`: Controllers are meant to be mounted under a route path, they are like page specific/scoped JavaScript.
+
+- `Components`: Components are like widgets you will have in several pages: modals, tooltips, notifications, etc. Components can be also auto-mounted on each DOM load, you just need to pass them to the `RalixApp` instance.
+
+On the other hand, Ralix also provides some helpers and utilities to facilitate most common operations like: selectors, manipulations, events, etc. [Check it out here](#core-methods).
+
 ## Example
 
+Structure:
+
+```
+├── components
+│   ├── modal.js
+│   ├── geolocation.js
+│   ├── flash_messages.js
+│   ├── forms.js
+├── controllers
+│   ├── users.js
+│   ├── dashboard.js
+│   ├── bookings.js
+│   └── app.js
+├── packs
+│   └── application.js
+└── app.js
+```
+
 ### App
 
 ```js
@@ -21,7 +47,7 @@ import BookingsCtrl  from 'controllers/bookings'
 import UsersCtrl     from 'controllers/users'
 
 // Components with auto-start on each DOM load event (turbolinks:load or DOMContentLoaded)
-import FormErrors    from 'components/form_errors'
+import Forms         from 'components/forms'
 import FlashMessages from 'components/flash_messages'
 
 const App = new RalixApp({
@@ -33,7 +59,7 @@ const App = new RalixApp({
     '/.*':        AppCtrl
   },
   components: [
-    FormErrors,
+    Forms,
     FlashMessages
   ]
 })
@@ -75,19 +101,30 @@ export default class UsersCtrl extends AppCtrl {
   back() {
     visit('/dashboard')
   }
+
+  search() {
+    hide('.search-result')
+    show('.spinner')
+
+    setTimeout(() => {
+      submit('.search-form')
+    }, 300)
+  }
 }
 ```
 
 ### Views
 
 ```html
-<div>
-  <a href="#" onclick="back()">Back</a>
-  <div id="menu">...</div>
-  ...
-  <a href="#" onclick="toggleMenu()">Toggle Menu</a>
-  <a href="#" onclick="openModal('/modals/help')">Help me!</a>
-</div>
+<a href="#" onclick="back()">Back</a>
+<div id="menu">...</div>
+...
+<a href="#" onclick="toggleMenu()">Toggle Menu</a>
+<a href="#" onclick="openModal('/modals/help')">Help me!</a>
+...
+<input type="text" name="query" onkeyup="search()" />
+...
+<div onclick="visit('/sign-up')">...</div>
 ```
 
 ### Components
@@ -106,22 +143,39 @@ export default class FlashMessages {
 }
 ```
 
-## API
-
-- App.ctrl
-- App.currentElement
-- App.currentEvent
-
 ## Core methods
 
+### Selectors
+
 - find(query)
 - findAll(query)
+
+### Visibility
+
 - show(query)
 - hide(query)
+
+### Classes
+
 - addClass(query, classList)
 - removeClass(query, classList)
 - toggleClass(query, classList)
-- visit(url)
+
+### DOM
+
+- insertHTML(query, html, position)
+
+### Forms
+
 - submit(query)
+
+### Navigation
+
 - url()
+- visit(url)
 - getParam(param)
+
+### Events
+
+- currentElement()
+- currentEvent()

src/app.js

@@ -19,9 +19,9 @@ export default class App {
   }
 
   start() {
-    const event = (typeof Turbolinks !== 'undefined') ? 'turbolinks:load' : 'DOMContentLoaded'
+    const onLoad = (typeof Turbolinks !== 'undefined') ? 'turbolinks:load' : 'DOMContentLoaded'
 
-    document.addEventListener(event, () => {
+    document.addEventListener(onLoad, () => {
       this.core.inject()
       this.router.dispatch()
       this.events.bind()

src/core.js

@@ -65,6 +65,36 @@ export default class Core {
       return urlParams.get(param)
   }
 
+  currentElement() {
+    return App.currentElement
+  }
+
+  currentEvent() {
+    return App.currentEvent
+  }
+
+  insertHTML(query, html, position = 'inner') {
+    const el = _element(query)
+
+    switch (position) {
+      case 'inner':
+        el.innerHTML = html
+        break
+      case 'prepend':
+        el.insertAdjacentHTML('beforebegin', html)
+        break
+      case 'begin':
+        el.insertAdjacentHTML('afterbegin', html)
+        break
+      case 'end':
+        el.insertAdjacentHTML('beforeend', html)
+        break
+      case 'append':
+        el.insertAdjacentHTML('afterend', html)
+        break
+    }
+  }
+
   _element(query) {
     if (typeof query === 'string')
       return find(query)