ucb_rails CLI

This is the gem for the ucb_rails command line tool. You can use this tool to generate new Rails apps for UCB, which contain many useful features right out of the box:

  • authentication through CAS and user management via the ucb_rails_user gem
  • default home page for logged-in and not-logged-in users
  • nav bar with drop-down menus for developers and admins
  • styles consistent with UCB brand guidelines
  • HAML for views
  • Bootstrap 4 for styling
  • SASS for CSS
  • Datatables for client-side table sorting
  • RSpec for tests

NOTE: Applications generated with this tool have turbolinks turned off.

Prerequisites

  • Ruby >= 2.3
  • Rails >= 5.1

Older versions of these might work, but haven't been tested.

If you're using Rails >= 6, you'll need recent versions of https://nodejs.org/en/ and https://yarnpkg.com/.

You also need the master key to decrypt credentials stored in the generated config/credentials.yml.enc file. You can set this up by storing the key in either:

  • the RAILS_MASTER_KEY environment variable, or:
  • a file located at ~/.ucb_rails_master_key

If one of these options is not set, you won't be able to generate a new app.

Bootstrap version

Version 1.0 of this gem uses Bootstrap 4. Use version 0.9.0 if you need Bootstrap 3

Installation

gem install ucb_rails_cli

Usage

To generate a new app:

ucb_rails new my_app_name

This will generate a new Rails app (it runs rails new behind the scenes), then adds a lot of extras to give you a working UCB Rails app.

If you have options that you want to pass to the rails new command, you can specify those using the rails_options option:

ucb_rails new my_app_name --rails_options "--database postgresql"

Once that command has run, set up the database:

cd my_app_name
bin/rake db:create
bin/rake db:migrate

Now you can start the server:

bin/rails s

and point your browser to http://localhost:3000 as usual. You should be able to login and create a user record in your local db by clicking the "Login" link and logging into CAS.

Customizing Default Behavior

An app generated with this tool will have a lot of working features right away. But it's possible to customize or even replace behaviors as needed.

User Management

The user model, login and logout, and user management are provided by the ucb_rails_user engine. See the README file for details on how to add or overwrite behavior to any user-related features.

CSS

Apps generated with ucb_rails have default styles in place that are consistent with the UCB brand guidelines. These are all located in app/assets/stylesheets/themes/ucb_standard. If you don't want to use these styles, just remove this line from app/assets/stylesheets/main.sass:

@import "themes/ucb_standard/main"

Note that the generated app handles SASS imports slightly differently than standard Rails apps. Rather than use the Sprockets style *= require_tree . we just require main.sass and use SASS-style imports in main.sass.

This is to work around the issue of require_tree not allowing for the order of the files that get imported. You usually want files containing SASS variables to be included first, so that they're available to other files. Using the @import statement explicitly gives you this control.

This means that you'll need to manually add an @import statement to main.sass whenever you add a new SASS file to the project, but you'll have a lot more control over how things are imported.