Skip to content

Latest commit

 

History

History
247 lines (178 loc) · 6.42 KB

README.md

File metadata and controls

247 lines (178 loc) · 6.42 KB
Raw

Ralix.js

Microframework for building and organizing your front-end ✨

Ralix is a modest JavaScript framework that provides barebones and utilities to help enhance your server-side rendered webapps.

Ralix consists basically in 3 pieces:

  • 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.
  • Helpers: Utilities to facilitate most common operations like: selectors, manipulations, events, ajax, etc. Check it out here.

You can read more about Ralix Design, Vision and Philosophy here.

Ralix pairs well with Rails and Turbo based applications. Check out more information here.

Installation

To install Ralix in your application, add the ralix package to your JavaScript bundle.

Using npm:

> npm install ralix

Using Yarn:

> yarn add ralix

Example application

Structure:

source/
├── components/
│   ├── modal.js
│   └── tooltip.js
├── controllers/
│   ├── application.js
│   ├── dashboard.js
│   └── users.js
└── app.js

App object

It's the entrypoint for your application (source/app.js), where you should load your modules and create a RalixApp instance: new RalixApp(). Then, you can start your Ralix application by calling: App.start(). Don't forget to include your entrypoint in your layout.

import { RalixApp }  from 'ralix'

// Controllers
import AppCtrl       from './controllers/application'
import DashboardCtrl from './controllers/dashboard'
import UsersCtrl     from './controllers/users'

// Components with auto-start
import Modal         from './components/modal'
import Tooltip       from './components/tooltip'

const App = new RalixApp({
  routes: {
    '/dashboard': DashboardCtrl,
    '/users':     UsersCtrl,
    '/.*':        AppCtrl
  },
  components: [Modal, Tooltip]
})

App.start()

The App object is exposed globally via the window object. You can access the current controller via App.ctrl.

Controllers

Define your main controller (AppCtrl, MainCtrl, IndexCtrl, ...):

// source/controllers/app.js

export default class AppCtrl {
  goBack() {
    back()
  }

  toggleMenu() {
    toggleClass('#menu', 'hidden')
  }
}

Inherit from your main controller (read more):

// source/controllers/users.js

import AppCtrl from './application'

export default class UsersCtrl extends AppCtrl {
  constructor() {
    super()
  }

  goBack() {
    visit('/dashboard')
  }

  search() {
    addClass('.search-result', 'hidden')
    removeClass('.spinner', 'hidden')

    setTimeout(() => {
      submit('.search-form')
    }, 300)
  }
}

Components

Example of a component with auto-mount:

// source/components/modal.js

export default class Modal {
  static onload() {
    findAll('.fire-modal').forEach(el => {
      on(el, 'click', () => {
        const modal = new Modal(data(el, 'url'))
        modal.show()
      })
    })
  }

  constructor(url) {
    this.url = url
  }

  show() {
    const modal      = find('#modal')
    const modalBody  = find('#modal__body')
    const modalClose = find('#modal__close')

    addClass(document.body, 'disable-scroll')
    addClass(modal, 'open')

    get(this.url).then((result) => {
      insertHTML(modalBody, result)
    })

    on(modalClose, 'click', () => {
      removeClass(document.body, 'disable-scroll')
      removeClass(modal, 'open')
      insertHTML(modalBody, 'Loading ...')
    })
  }
}

Then, in your HTML, you just need to define a link or button like with the following attributes:

<button class="fire-modal" data-url="/example-modal">Open Remote Modal</button>

Views

In your regular HTML code, now you can call directly Ralix Helpers or the methods provided by the current Ralix controller, using regular HTML Events.

<a href="#" onclick="goBack()">Back</a>
<a href="#" onclick="toggleMenu()">Toggle Menu</a>
<input type="text" name="query" onkeyup="search()">
<div onclick="visit('/sign-up')">...</div>

Templates

Ralix provides also a minimalistic template engine, useful to DRY small snippets you need to render from your front-end. Under the hood, it uses JavaScript Functions with Template literals.

// In your App object, inject your templates
import * as Templates from './templates'

const App = new RalixApp({
  templates: Templates
})

// Define your templates as functions
export const itemCard = ({ title, description }) => `
  <div class="item-card">
    <h1>${title}</h1>
    <p>${description}</p>
  </div>
`

// Call it via
render('itemCard', {
  title: item.title,
  description: item.description
})

Starter Kits and Applications

Templates:

Applications:

Development

Any kind of feedback, bug report, idea or enhancement are much appreciated.

To contribute, just fork the repo, hack on it and send a pull request. Don't forget to add tests for behaviour changes and run the test suite by:

> yarn test

If you also want to see the code coverage:

> yarn test --collectCoverage

License

Copyright (c) Ralix Core Team. Ralix is released under the MIT License.