# 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](https://calnetweb.berkeley.edu/calnet-technologists/cas) and user management via the [ucb_rails_user gem](https://github.com/ucb-ist-eas/ucb_rails_user)
  * 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](http://brand.berkeley.edu/)
  * HAML for views
  * Bootstrap 4 for styling
  * SASS for CSS
  * [Datatables](https://datatables.net/) 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.

You also need the master key to [decrypt credentials stored in the generated `config/credentials.yml.enc` file.](https://www.engineyard.com/blog/rails-encrypted-credentials-on-rails-5.2) 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

```bash
gem install ucb_rails_cli
```

## Usage

To generate a new app:

```bash
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:

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

Once that command has run, set up the database:

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

Now you can start the server:

```bash
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.](https://github.com/ucb-ist-eas/ucb_rails_user) See the [README](https://github.com/ucb-ist-eas/ucb_rails_user#overriding-model-and-controller-behavior) 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](https://github.com/ucb-ist-eas/ucb_rails_user#overriding-model-and-controller-behavior). 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:`

```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.