Skip to main content

PMACS Frontend

This Gem represents the newest iteration of CUI (Common User Interface) and replaces PMACS Bootstrap. It aims to be lightweight and unimposing compared to its predecessor.

[[TOC]]

Features

For a more complete list of features and specificiations, visit the docs/ directory or the fancy documentation website.

But, in short, Frontend provides:

Additionally, apps using SCSS/SASS can overwrite variables used in this Gem to modify elements of it to their liking.

Installation

If you use Janus to create your project, it will make the following changes for you provided you are using a branch of pmacs_app_skeleton that includes Frontend.

  1. Add the gem

    In /#{project_name}/Gemfile:

    gem 'pmacs_app_resources'
gem 'pmacs-frontend'

    pmacs-frontend should be loaded after devise so Frontend's layout is used

    pmacs-frontend must be after pmacs_app_resources so that the latter's error partials take precedence.

  2. Import frontend styles

    In /#{project_name}/app/assets/stylesheets/application.css:

    // *= require pmacs-frontend

    If you're using SCSS, in application.scss:

    @import "pmacs-frontend";

  3. Import frontend JS

    In /#{project_name}/app/assets/javascripts/application.js:

    //= require pmacs-frontend

  4. Add an initializer for configuration

    In /#{project_name}/config/initializers/pmacs-frontend.rb:

    PmacsFrontend.configure do |config|
end

Usage

To explore how to use Frontend's many components, visit the documentation website.

Development

Within the demo app

This project contains a demo app, which you can use to develop against. (It also powers the documentation website)

cd path/to/pmacs-frontend # cd to your local version of Frontend
cd spec/demo_app # cd to the demo_app
bundle exec rails db:migrate
bundle exec rails s

Within a local host application

If you wish to develop against your own application that is already using Frontend, you can do this by adjusting your project's Gemfile to point at a local version of Frontend:

gem 'pmacs-frontend', path: '../pmacs-frontend'

Note: this requires you to have pmacs-frontend checked out in the same parent directory as your project.

Now, when you re-bundle your application and start a rails server, your host app will use your local version of pmacs-frontend and fetch the changes as you develop.

Tests

cd path/to/pmacs-frontend
bundle exec rspec

Maintenance policy

Major versions of Frontend will be maintained for 4 years. Once a major version of Frontend has reached the end of its life, no further changes will be made to it and you should upgrade your applications to a newer, supported major version.

Version 1.x of Frontend will be maintained for a full calendar year after 2.x launches (TBD).