cambium 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6881a831904e091c4228d69c086ba4a5622c60be
-  data.tar.gz: a35bac2b1517e59608167978861ca1a92cb1b94c
+  metadata.gz: 99887d04074970f7daa654f9fa7ff4eea5c3f0e7
+  data.tar.gz: 3933cd4cb15076a974d220c7331ad161fa563d33
 SHA512:
-  metadata.gz: 0fcfddb768d58f562c4243f7b3506d08b37e2e5bb3968c04db8b3ea9a7a6d42b66ad263e53b327aeb8d1443e9ac62cb4782c2c5f4930d5a601f059841c9cb7d0
-  data.tar.gz: 2ec1f058a8301385f794bb1ae7c623e93ae5eec0d874fbda981c030b27f6b872ff8134cda3ecce8452c52ac72bb108b26bd7d95ee5a2739286394ffd84ca528e
+  metadata.gz: db9cf246df9160103a22885bdca5dd61a01619ced628d36902913961190a75030f865b4902eb904b86b86b41b3efc6299a8fed04b711030dce2d8d4455eccb21
+  data.tar.gz: 162da5ef45897e73adeaa75e82dbd89076e41c3be2df3ea387dd1b676e6abf9f9fcccbf54f400e7d4fd6efb4c660c4f9389f96154fa8648b8310d92992661248

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Sean C Davis
+Copyright (c) 2014-2015 Sean C Davis, Warren Harrison
 
 MIT License
 

data/README.md

@@ -1,30 +1,354 @@
-# Cambium
+Cambium
+==========
 
-Cambium speeds up app development to keep you focusing on business logic and not
-worrying about repetitive tasks.
+Cambium serves three main purposes in Ruby on Rails applications:
 
-**Initial sprint in progress. Documentation will be provided when the gem is
-ready for distribution.**
+1. Bootstrap Rails' standard installation by performing additional setup
+   (things I find myself doing at the beginning of every project).
+2. Facilitate development throughout the life of any project by abstracting
+   repeatable bits of code.
+3. Provide a simple, but flexible CMS for those applications that require it.
 
-## Installation
+For now, the documentation will be continued in the README. This will be moved
+out over time.
 
-Add this line to your application's Gemfile:
+App Setup
+----------
 
-    gem 'cambium'
+Cambium lets you get up and running real fast. First, start you rails project
+as you normally would.
 
-And then execute:
+```text
+$ rails new my_app -d postgresql
+```
 
-    $ bundle
+> Note: Cambium only supports PostgreSQL. If you need to use another database,
+> I suggest you add an option into Cambium and create a pull request. However,
+> I strongly encourage you to give PostgreSQL a try.
 
-Or install it yourself as:
+Add Cambium to your Gemfile.
 
-    $ gem install cambium
+```ruby
+gem 'cambium', '>= 1.0.0'
+```
 
-## Usage
+> I would probably commit at this time (so it's easy to rollback if you don't
+> like something Cambium did).
 
-TODO: Write usage instructions here
+Generate Cambium's (simple) configuration file.
 
-## Contributing
+```text
+$ bundle exec rails g cambium:install
+```
+
+Edit the config (config/initializers/cambium.rb) to your liking.
+
+Then, get your PostgreSQL database configured by editing `config/database.yml`
+to your appropriate settings.
+
+> **Make sure you do not commit between this step and finishing the setup
+> process.** Cambium will ignore this database.yml file, which is good, as it
+> may contain sensitive data.
+
+Then, create your database:
+
+```text
+$ bundle exec rake db:create
+```
+
+Although optional, I suggest you at least start with the default `Gemfile`.
+
+```text
+$ bundle exec rails g cambium:gemfile
+```
+
+Remove the gems you don't want and then bundle.
+
+```text
+$ bundle install
+```
+
+And now you can run Cambium's auto-setup generator.
+
+```text
+$ bundle exec rails g cambium:app
+```
+
+When you're done, you can migrate (and annotate), and be on your way!
+
+```text
+$ bundle exec rake db:migrate
+$ bundle exec annotate
+```
+
+Admin / CMS
+----------
+
+### Install CMS
+
+If you want to also setup a CMS, it's as simple as running the generator.
+
+```text
+$ bundle exec rails g cambium:admin
+```
+
+Run the migrations Cambium created with the admin generator.
+
+```text
+$ bundle exec rake db:migrate
+$ bundle exec annotate
+```
+
+Make sure Cambium's engine is mounted in your `config/routes.rb` file.
+
+```ruby
+mount Cambium::Engine => '/'
+```
+
+It's best to mount it at the root because Cambium automatically namespaces its
+routes.
+
+At this point, you should be able to go to `localhost:3000/admin` and be
+redirected to the login page (if you are not signed in). Once you have an admin
+user and sign in successfully, you will be redirected to the admin dashboard.
+
+### Adding Users
+
+We have a generator for creating a new user, which takes an `--admin` option if
+you want the user to have admin access.
+
+```text
+$ bundle exec rails g cambium:user [username] [password] [--admin / --no-admin]
+```
+
+### Generating Admin Controllers
+
+A big portion of Cambium's power lies in its ability to spin up feature-full
+CMS controllers and views in a snap.
+
+Before you generate an admin controller, you need to make sure you have a
+working data model. It's best if the model already has the columns you know
+you're going to need (it's easy to add or remove later, but quicker if you have
+what you need at the beginning).
+
+Then you can run the generator.
+
+```text
+$ bundle exec rails g cambium:controller [model]
+```
+
+**Be sure you are using the proper class name of the data model.**
+
+For example, if I have a `Page` model, this would be the command:
+
+```text
+$ bundle exec rails g cambium:controller Page
+```
+
+> Note: I'm working on making Cambium more powerful all the time. At the
+> moment, it works best with simple form-type data.
+
+The generator does a few things:
+
+* Uses the standard Rails generate to generate a template in the `admin`
+  namespace (using the example, your file would be at
+  `app/controllers/admin/pages_controller.rb`).
+* Adds a namespaced route to your routes file (`config/routes.rb`).
+* Adds the Cambium config file (at `config/admin/pages.yml` in this example).
+* Adds a generic sidebar item for your controller at
+  `config/admin/sidebar.yml`.
+
+See below for information on the sidebar and controller settings.
+
+### Sidebar Settings
+
+The sidebar in Cambium is driven by your `config/admin/sidebar.yml` settings
+file. It's pretty semantic and simple.
+
+The default sidebar is:
+
+```yaml
+dashboard:
+  label: Dashboard
+  route: cambium.admin_dashboard
+  icon: dashboard
+users:
+  label: Users
+  route: cambium.admin_users
+  icon: users
+  controllers: ['users']
+```
+
+The important thing to remember is you have to define a unique key for each
+item. For example, if you accidentally named `users` as `dashboard`, then only
+the last `dashboard` item gets rendered.
+
+The options are:
+
+* `label`: Text within the sidebar link
+* `route`: Route to apply to the link (for custom settings, replace `cambium`
+  with `main_app`)
+* `icon`: The name of the icon to use, pulled from [IcoMoon's free
+  set](https://icomoon.io/#preview-free)
+* `controllers`: An array of controllers which, if the current page is using
+  one of the controllers, the sidebar item will be highlighted (with an
+  `active` class)
+
+### Controller Settings
+
+The controller settings are what drive the behavior of Cambium. And it's why,
+for simple models, you don't have to add any code to your controller and you
+don't need any views.
+
+Each controller's settings file is named for that controller, and can be found
+in `config/admin`. For example, the users controller settings are at
+`config/admin/users.yml`.
+
+Here is the default set for the users controller:
+
+```yaml
+model: User
+table:
+  title: Site Users
+  scope: all
+  columns:
+    email:
+      heading: Email
+  buttons:
+    new: New User
+export:
+  button: Export Users
+  columns:
+    name:
+      label: Name
+    email:
+      label: Email
+form:
+  new: &new
+    title: New User
+    fields:
+      name:
+        type: string
+      email:
+        type: string
+      password:
+        type: password
+      password_confirmation:
+        type: password
+  edit:
+    <<: *new
+    title: Edit User
+```
+
+Every setting plays a role. Let's step through each one.
+
+* `model`: The name (with class case) of the model to be used for this
+  controller
+* `table:title`: The title to show on the controller's index view.
+* `table:scope`: The scope method to run on the model. Most of the time this
+  will be `all`, but maybe you need to order, limit, or filter your results.
+  You need to do this through an [ActiveRecord
+  Scope](http://guides.rubyonrails.org/active_record_querying.html)
+* `table:columns:[column]`: Each column gets its own unique key, which
+  distinguishes it from others
+* `table:columns:[column]:heading`: The label for the column in the data table.
+* `table:buttons:new`: Label for the "New" button. If you don't want a
+  new button, remove this setting.
+* `export`: This section handles an export option for your data table. Remove
+  it if you don't want to offer that.
+* `export:button`: The label for the export button.
+* `export:columns:[column]`: Each column in the exported file gets its own
+  unique key, which distinguishes it from others
+* `export:columns:[column]:label`: The heading in the exported file for that
+  column.
+* `export:columns:[column]:output`: An optional method you can pass to each
+  object to help with display.
+* `form`: Settings for the form.
+* `form:[new/edit]`: New is the defaut, and most of the time Edit will inherit
+  from new (the `<<: *new` is what handles that). But you can optionally
+  override new values for your edit form.
+* `form:[new/edit]:title`: Title for the form page.
+* `form:[new/edit]:fields:[field]`: Each form field gets its own unique key to
+  set it apart from the others.
+* `form:[new/edit]:fields:[field]:type`: The type of the HTML field to render,
+  which uses [SimpleForm](https://github.com/plataformatec/simple_form).
+
+> Note: Aside from the usual form field types, Cambium uses [Mark It
+> Zero!](https://github.com/seancdavis/mark_it_zero) to render markdown
+> editors. You can pass `markdown` as the `type` option and it will give you a
+> markdown editor.
+
+Model Options
+----------
+
+Cambium makes use of many gems, and uses the behavior of those gems to drive
+much of its power. In many cases, this requires added options to your model.
+
+### Searchable Models
+
+To make items searchable (in the CMS and in the app), we use
+[pg_search](https://github.com/Casecommons/pg_search). You need to include the
+`PgSearch` module, and then call out the columns you want to search.
+
+For example, if you have a `Page` model and you want `title` and `body` to be
+searchable, you're model might look like this:
+
+```ruby
+class Page < ActiveRecord::Base
+  include PgSearch
+  multisearchable :against => [:title, :body]
+end
+```
+
+### Activity Log
+
+If you want to track the history of a model's records (which also means adding
+it to the activity log in the CMS), you need to add `has_paper_trail` to your
+model.
+
+```ruby
+class Page < ActiveRecord::Base
+  has_paper_trail
+end
+```
+
+The activity log in particular makes use of the `to_s` method for the model. In
+this way, we make no assumptions about the default attribute that describes a
+model's record. Usually this is something like `title` or `name`. If it were
+`title`, then your model (from above) is:
+
+```ruby
+class Page < ActiveRecord::Base
+  has_paper_trail
+
+  def to_s
+    title
+  end
+end
+```
+
+### Markdown to HTML
+
+As mentioned above, Cambium uses [Mark It
+Zero!](https://github.com/seancdavis/mark_it_zero) to render markdown editors.
+You, therefore, also have the option to store a markdown text attribute and
+have it automatically converted to HTML using the `after_save` callback.
+
+If, for our `Page` example, you have `body_markdown` and `body_html` fields,
+you can add your `body_markdown` attribute to the form and then the following
+to your model:
+
+```ruby
+class Page < ActiveRecord::Base
+  converts_markdown :body_markdown, :body_html
+end
+```
+
+See [this section](https://github.com/seancdavis/mark_it_zero#converting-to-
+html) of the Mark It Zero! docs for more information and options.
+
+Contributing
+----------
 
 1. Fork it ( https://github.com/[my-github-username]/cambium/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/{lib/generators/cambium/templates/app/assets/javascripts/admin/admin.js.coffee → app/assets/javascripts/cambium/admin/application.js.coffee}

@@ -1,29 +1,23 @@
 #= require jquery
 #= require jquery_ujs
-#= require jquery-fileupload/basic
-#= require jquery-fileupload/vendor/tmpl
+#= require mark_it_zero/mark_it_zero
 #= require pickadate/picker
 #= require pickadate/picker.date
 #= require pickadate/picker.time
-#= require admin/wysihtml5
-#= require admin/parser_rules/custom
 #= require underscore
 #= require backbone
 #= require_self
 #= require_tree ./templates
-#= require_tree ./models
-#= require_tree ./collections
 #= require_tree ./views
 #= require_tree ./routers
 
-window.Admin =
-  Models: {}
+window.App =
   Collections: {}
   Routers: {}
   Views: {}
 
-$(document).ready ->
-  new Admin.Routers.Router
+$ ->
+  new App.Routers.Router
 
   # Enable pushState for compatible browsers
   enablePushState = true

data/app/assets/javascripts/cambium/admin/routers/router.js.coffee

@@ -0,0 +1,25 @@
+class App.Routers.Router extends Backbone.Router
+
+  initialize: =>
+    @autoLoadClass()
+
+  autoLoadClass: =>
+    # This is a good place to automatically load classes that may be dependent
+    # on a page element, and not necessarily the route.
+    #
+    # For example:
+    #
+    # new App.Views.Nav if $('.main-nav').length > 0
+    #
+    # Or, perhaps you need to load a class on every page. Do that, here, too,
+    # like this:
+    #
+    new App.Views.DefaultHelpers
+    new App.Views.DropdownMenu if $('.dropdown-menu').length > 0
+    new App.Views.Pickadate
+
+  routes:
+    '': 'initHomePage'
+
+  initHomePage: ->
+    console.log "Welcome to this awesome site, built using Cambium!"

data/app/assets/javascripts/cambium/admin/users.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/assets/javascripts/cambium/admin/views/dropdown_menu.js.coffee

@@ -0,0 +1,24 @@
+class App.Views.DropdownMenu extends Backbone.View
+
+  el: 'body'
+
+  events:
+    'click .dropdown-trigger': 'showDropdown'
+
+  initialize: ->
+    $(document).click(@checkHideDropdown)
+
+  showDropdown: (e) ->
+    e.preventDefault()
+    $(e.target).closest('.dropdown-container').find('.dropdown-menu')
+      .toggleClass('active')
+    true
+
+  checkHideDropdown: (e) ->
+    if(
+      !$(e.target).is('.dropdown-menu') &&
+      !$(e.target).is('.dropdown-container') &&
+      $(e.target).parents('.dropdown-container').length == 0
+    )
+      $('.dropdown-menu').removeClass('active')
+    true

data/app/assets/javascripts/cambium/admin/views/pickadate.js.coffee

@@ -0,0 +1,15 @@
+class App.Views.Pickadate extends Backbone.View
+
+  el: 'body'
+
+  initialize: ->
+    $('input.pickadate').pickadate()
+    $('input.pickatime').pickatime()
+    if $('div.pickadatetime').length > 0
+      $('input.pickadatetime-date').pickadate()
+      $('input.pickadatetime-time').pickatime()
+      $('input.pickadatetime-date, input.pickadatetime-time').change (e) ->
+        parent = $(e.target).parents('div.pickadatetime').first()
+        val = parent.find('input.pickadatetime-date').val()
+        val = "#{val} #{parent.find('input.pickadatetime-time').val()}"
+        $(e.target).siblings('input.pickadatetime').first().val(val)

data/app/assets/stylesheets/cambium/admin/application.scss

@@ -0,0 +1,27 @@
+
+// ------------------------------------------ Vendor
+
+@import 'bourbon';
+@import 'cambium/admin/bones/bones';
+@import 'pickadate/classic';
+@import 'pickadate/classic.date';
+@import 'pickadate/classic.time';
+@import 'mark_it_zero/mark_it_zero';
+
+// ------------------------------------------ Partials
+
+@import 'cambium/admin/partials/globals';
+@import 'cambium/admin/partials/typography';
+@import 'cambium/admin/partials/wireframe';
+@import 'cambium/admin/partials/components';
+@import 'cambium/admin/partials/header';
+@import 'cambium/admin/partials/page_title';
+@import 'cambium/admin/partials/sidebar';
+@import 'cambium/admin/partials/activity';
+@import 'cambium/admin/partials/forms';
+@import 'cambium/admin/partials/tables';
+@import 'cambium/admin/partials/dashboard';
+
+// ------------------------------------------ Optional Override
+
+@import 'admin/admin';

data/{lib/generators/cambium/templates/app/assets/stylesheets → app/assets/stylesheets/cambium}/admin/bones/bones-config/_colors.scss

@@ -1,12 +1,12 @@
 /* Color Palette
 ============================ */
-$color-1: #0065BD; // used most often by default
-$color-2: #00A9E0;
-$color-3: #D48D2B;
-$color-4: #1F7D24;
-$color-5: #BDAD1B;
-$color-dark: #141819; // designed to be a dark color
-$color-light: #fbfcfc; // designed to be a light color
+$color-1: #77D5D3;
+$color-2: #FED96E;
+$color-3: #9DC2DD;
+$color-4: #DB5F7B;
+$color-5: #24A9A7;
+$color-dark: #293541; // designed to be a dark color
+$color-light: #FFFFFF; // designed to be a light color
 
 // used primarily for notifications:
 $color-warning: #CCA300;

data/{lib/generators/cambium/templates/app/assets/stylesheets → app/assets/stylesheets/cambium}/admin/bones/bones.scss

@@ -2,50 +2,50 @@
 
 /*
  * Welcome to Bones CSS Framework!
- * 
- * This is the manifest file for Bones' CSS. It brings all files 
+ *
+ * This is the manifest file for Bones' CSS. It brings all files
  * together.
  *
- * To add or remove modules, simply comment or uncomment and then 
+ * To add or remove modules, simply comment or uncomment and then
  * use Compass to recompile and compress.
  *
  * Files are noted as recommended and required where applicable.
  *
  * Refer to the ../docs/ directory for more detailed instruction.
- * 
+ *
  */
 
 /* Vendor
 ============================ */
 @import 'bones/vendor/normalize'; // highly recommended for cross-browser consistency
-  
+
 /* Config
 ============================ */
 /*
- * These are your configuration files. You should always 
+ * These are your configuration files. You should always
  * load all of these files, as the variable values are
  * resolved and do not contribute any size to the final
  * bones.css file.
  *
  */
-@import 'admin/bones/bones-config/colors';
-@import 'admin/bones/bones-config/_default';
-@import 'admin/bones/bones-config/wireframe';
-@import 'admin/bones/bones-config/typography';
-@import 'admin/bones/bones-config/buttons';
-@import 'admin/bones/bones-config/forms';
-@import 'admin/bones/bones-config/tables';
-@import 'admin/bones/bones-config/nav';
-@import 'admin/bones/bones-config/images';
-@import 'admin/bones/bones-config/components';
-@import 'admin/bones/bones-config/helpers';
+@import 'cambium/admin/bones/bones-config/colors';
+@import 'cambium/admin/bones/bones-config/_default';
+@import 'cambium/admin/bones/bones-config/wireframe';
+@import 'cambium/admin/bones/bones-config/typography';
+@import 'cambium/admin/bones/bones-config/buttons';
+@import 'cambium/admin/bones/bones-config/forms';
+@import 'cambium/admin/bones/bones-config/tables';
+@import 'cambium/admin/bones/bones-config/nav';
+@import 'cambium/admin/bones/bones-config/images';
+@import 'cambium/admin/bones/bones-config/components';
+@import 'cambium/admin/bones/bones-config/helpers';
 
 /* Main Styles
 ============================ */
 @import 'bones/styles/_default'; // required
 @import 'bones/styles/wireframe';
 @import 'bones/styles/typography';
-@import 'bones/styles/icons'; // icomoon free icon font
+@import 'bones/styles/icons';
 @import 'bones/styles/buttons';
 @import 'bones/styles/forms';
 @import 'bones/styles/tables';

data/app/assets/stylesheets/cambium/admin/partials/_globals.scss

@@ -0,0 +1,21 @@
+* {
+  font-family: 'Source Sans Pro', "Helvetica Neue", Helvetica, Arial, sans-serif;
+}
+
+@mixin transition-all {
+  @include transition(all 0.25s ease-in-out);
+}
+
+@mixin clear-list {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+  li {
+    margin: 0;
+    padding: 0;
+    a {
+      margin: 0;
+      padding: 0;
+    }
+  }
+}

data/app/assets/stylesheets/cambium/admin/partials/activity.scss

@@ -0,0 +1,52 @@
+aside#activity {
+  background: $color-light-dark;
+  border-left: 1px solid $color-light-darker;
+  padding: 25px 10px;
+  @include box-sizing(border-box);
+  article {
+    margin: 0 0 30px 0;
+    &:last-child {
+      margin-bottom: 0;
+    }
+    .avatar-container {
+      margin: 5px 10px 0 0;
+      border-color: $color-light-darker;
+      vertical-align: top;
+      width: 28px;
+      height: 28px;
+    }
+    .content {
+      display: inline-block;
+      width: 185px;
+      vertical-align: top;
+      p {
+        margin: 0;
+        font-size: 14px;
+        line-height: 18px;
+        &.action {
+          margin-top: 5px;
+        }
+        &.date {
+          color: darken($color-light-darkest, 15%);
+          font-weight: 400;
+          font-size: 12px;
+          line-height: 12px;
+        }
+        strong {
+          font-size: inherit;
+          line-height: inherit;
+          a {
+            font-size: inherit;
+            line-height: inherit;
+            font-weight: inherit;
+            color: inherit;
+            @include transition-all;
+            &:hover {
+              color: $color-dark-lightest;
+            }
+          }
+        }
+      }
+    }
+  }
+}