cambium 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c8b304242f9dbd63f0dae18e86addc32e179e27
-  data.tar.gz: f465d1014276a227f7f2926e4bf357db1e6e2d33
+  metadata.gz: 29da11f3322f226331391271921de5a185c1e038
+  data.tar.gz: bc1726947ccc6aac36768db892bb9916413f4d1c
 SHA512:
-  metadata.gz: e1f60dae6425e18802ac29e4f2c84b052887a548d30bf1e6303d598b4625b43a1872059202536b50867b6fcf0a592e8c08a342556f79f48e7d471f014edb7f9c
-  data.tar.gz: 79b4fea86dda7920dc4045666f1ac85f4fee4487d7fc85f55ffbc524ae42c54ef68c45cc43fece516dbb8ffed8feb079ba0af63a1dd6724930742ca32f5202e6
+  metadata.gz: ebca18b41a35ec1eb921edc0dd0c766417bde5fc0f60b7b63d2ed688c066ce6c20d1ec8137e47abdef88e61f78b1047485ab135da55fbc7a81a0d7f4177cf94b
+  data.tar.gz: 4868fff7264adcb70ab546c3f54f9499a372684a492eba871cd9077302a83a790478eee1d0981c5a50d90d329b9cf8d30c8dba71c1d560c370ccf937787e0d25

data/.gitignore

@@ -11,9 +11,6 @@ doc/
 lib/bundler/man
 pkg
 rdoc
-spec/reports
-test/tmp
-test/version_tmp
 tmp
 *.bundle
 *.so
@@ -21,3 +18,11 @@ tmp
 *.a
 mkmf.log
 *.DS_Store
+
+# Dummy App for Testing
+spec/dummy/db/*.sqlite3
+spec/dummy/db/*.sqlite3-journal
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+spec/reports

data/.ruby-version

@@ -0,0 +1 @@
+2.2.3

data/README.md

@@ -112,6 +112,16 @@ 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.
 
+### Default Features
+
+When you run the generators, you will get a handful of features by default.
+Cambium now ships with users, pages, media, and settings. Of these four, users
+is the only model that will be inserted directly in your app. Cambium handles
+the others.
+
+See below for configuration and for adding users, while the following sections
+talk about how pages, media, and settings work.
+
 ### Adding Users
 
 We have a generator for creating a new user, which takes an `--admin` option if
@@ -214,6 +224,8 @@ table:
   columns:
     email:
       heading: Email
+      sortable: true
+      display_method: email_address
   buttons:
     new: New User
 export:
@@ -255,6 +267,13 @@ Every setting plays a role. Let's step through each one.
 * `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:columns:[column]:sortable`: Makes the column heading a link that will
+  sort the data based on that column. This means **the column must be a column
+  in the database**.
+* `table:columns:[column]:display_method`: Provides ability to use an alias
+  method for displaying the content. For example, you may store a `state` as a
+  integer but want to return a `status` string for the table. You'd use `state`
+  as the column and `status` as the display method.
 * `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
@@ -279,6 +298,9 @@ Every setting plays a role. Let's step through each one.
 * `form:[new/edit]:fields:[field]:type`: The type of the HTML field to render,
   which uses [SimpleForm](https://github.com/plataformatec/simple_form). *You
   can use `heading` here to break up your fields.*
+* `form:[new/edit]:fields:[field]:crop`: If set to `true`, it will display a
+  "Crop Image" option _after_ a file has been uploaded. This only applies to
+  `file` types.
 * `form:[new/edit]:fields:[field]:readonly`: If set to `true`, it will add the
   `readonly` attribute to the input field. *Not supported for markdown fields*.
 
@@ -287,6 +309,24 @@ Every setting plays a role. Let's step through each one.
 > editors. You can pass `markdown` as the `type` option and it will give you a
 > markdown editor.
 
+#### A Note On Files
+
+File fields use [Dragonfly](https://markevans.github.io/dragonfly/) for
+uploading and processing. To add an upload field to the CMS, you need to have
+three attributes: `_name`, `_uid`, `_gravity`.
+
+So, for example, if you have a field called, `upload`, You'll add the following
+to your database **as string fields**:
+
+- `upload_name`
+- `upload_uid`
+- `upload_gravity`
+
+In addition to the features Dragonfly offers, Cambium has a built-in image
+cropper. The option for this will appear _after_ a file has been uploaded _if
+you specify the crop option for that field_. If those conditions are present,
+you'll see a "Crop Image" below the image.
+
 ### Overriding the Base Controller
 
 I've rearranged Cambium's CMS controllers so there is a blank `BaseController`
@@ -312,6 +352,267 @@ end
 You can change `ApplicationController` to any other controller in your
 application.
 
+Pages
+----------
+
+Cambium now ships with a flexible pages feature.
+
+### How Pages Work
+
+Cambium keeps the base functionality of the pages within the gem in the
+`Cambium::Page` model. It provides a templating engine that enables you to add
+custom templates and apply them to individual pages.
+
+The way it works is that you apply a template to an individual page. When that
+page is rendered, it will render the associated template file (minus the
+frontmatter, explained below) **inside your application layout**.
+
+### Working With Templates
+
+To add a new template, just add a file to `app/views/pages`. The name of the
+file is what will drive the name of the template in the CMS.
+
+To make everything work properly, it is recommended you **keep the default form
+fields in your `pages.yml` config for the CMS.**
+
+Templates can have a set of custom fields that enable you to capture custom
+data on a page. You can't query that data directly, but you can get to it once
+you have a page. The configuration for each template uses YAML frontmatter,
+similar to [how Middleman works](https://middlemanapp.com/basics/frontmatter/).
+
+Let's use an example to demonstrate. Let's say I have a `Post` model in my app
+and I want a listing of posts to be displayed on a News template. I would begin
+by creating a file for the news template: `app/views/pages/news.html.erb`.
+
+Then let's say we want to capture a `tagline` attribute on the page. You would
+place the frontmatter at the top of your file, and it will look something like
+this:
+
+```text
+---
+title: News
+fields:
+  tagline:
+    type: string
+    label: Tagline
+---
+```
+
+It's important in this case that you **don't put the frontmatter in a ruby
+block** (`<% %>`). It needs to be in plain text on the page.
+
+Once this information is there, you are able to add a page with the News
+template in the CMS. Once you select the News template and save the page, the
+form will show the custom `tagline` field as an option. Go ahead and populate
+that field.
+
+When you are creating the body of the template, it will all be based around the
+`@page` object. Meanwhile, the values of your fields are available as attribute
+on the `@page` object. So, if you wanted to display a listing of all the posts
+on this template, your file might look something like this:
+
+```html
+---
+title: News
+fields:
+  tagline:
+    type: string
+    label: Tagline
+---
+
+<h1><%= @page.title %></h1>
+<h2><%= @page.tagline %></h2>
+
+<ul>
+  <% Post.all.each do |post| %>
+    <li><%= link_to post.title, post %></li>
+  <% end %>
+</ul>
+```
+
+### Setting Your Home Page
+
+The page form has a _Set as home page_ option on it. If you check this, that
+page will be designated as the home page of your application. To make it work,
+you'll have to amend your `root` call in `config/routes.rb` to load Cambium's
+home page.
+
+```ruby
+root :to => 'cambium/pages#home'
+```
+
+If you don't have a page set as the home page, this will fail gracefully. If
+you have two pages set as the home page, it's going to pick the first match. In
+other words, setting a page as the home page doesn't unset all the other home
+pages.
+
+### Options
+
+There are a few methods on the `Cambium::Page` class:
+
+- `home`: The home page.
+- `published`: Published pages.
+- `unpublished`: Unpublished pages.
+
+On an instance of a `Cambium::Page`, you can call the following methods:
+
+- `template`: A `PageTemplate` instance (see below for those options).
+- `body`: The body of the page (it's main block of content).
+- `published?`: Is the page published?
+- `publish!`: Publish the page.
+
+There are also a few attributes on an instance of a `Cambium::Page`:
+
+- `title`
+- `slug`: Automatically generated from the title.
+- `description`
+- `position`
+- `page_path`: The full path to the page, including ancestors.
+- `title_path`: Combines all the titles of the ancestors, split by `:`.
+
+The `Cambium::PageTemplate` class mainly focuses on the field values for a
+particular page, which it makes available as dynamic methods. But on the class
+itself, you have a few methods:
+
+- `all`: The templates in your app.
+- `names`: The names of all the templates in your app.
+- `find`: Takes a `name` argument and will return that template if it exists.
+
+### Adding Media
+
+Cambium also ships with a media library by default. You can apply files from
+the library to an individual page. But, unlike other Cambium admin controllers,
+you won't use `file` as the field type. Instead it is a `media` field type
+which is specifically designed to pull files from the media library.
+
+So, let's say you wanted to add a `featured_image` field to your News template. Your frontmatter may then look something like this:
+
+```text
+---
+title: News
+fields:
+  tagline:
+    type: string
+    label: Tagline
+  featured_image:
+    type: media
+    label: Featured Image
+---
+```
+
+Accessing the actual file will work a little differently, though. We are using
+Dragonfly for handling uploads and processing, so you don't get the URL
+directly. Instead you get the `Document` object, which provides some
+flexibility on what you can do with it.
+
+For example, if you just wanted the URL to the file itself, then you might add
+this to your template:
+
+```html
+<%= @page.featured_image.upload.url %>
+```
+
+But what if you wanted it cropped on the fly? You could do something like this:
+
+```html
+<%= @page.featured_image.upload.thumb('300x300#').url %>
+```
+
+### Adding/Overriding Functionality
+
+Cambium pages use the `Cambium::Page` model. If you want to add some additional
+functionality or change some inherent functionality, you could create a page
+model (`app/models/page.rb`) that inherits from `Cambium::Page`.
+
+```ruby
+class Page < Cambium::Page
+  # your custom configuration
+end
+```
+
+You'll then need to override the controller and access the `Page` model instead
+of the `Cambium::Page` model. Place the following code in
+`app/controllers/cambium/pages_controller.rb`.
+
+```ruby
+class Cambium::PagesController < ApplicationController
+  def show
+    slug = request.path.split('/').last
+    @page = ::Page.find_by_slug(slug)
+    render :inline => @page.template.content, :layout => 'application'
+  end
+
+  def home
+    @page = ::Page.home
+    if @page.nil?
+      render 'home_missing'
+    else
+      render :inline => @page.template.content, :layout => 'application'
+    end
+  end
+end
+```
+
+### Disabling Pages
+
+You can't technically disable pages, but you can _hide_ its functionality. The
+best thing to do is to remove its configuration file (`config/admin/pages.yml`)
+and remove it from the sidebar config (`config/admin/sidebar.yml`).
+
+Media Library
+----------
+
+Cambium now ships with a media library. This lets you upload all your files to
+one main library. This feature especially will receive much more attention over
+time. Currently, they are built to be easily connected to pages.
+
+To work with pages, see the previous section.
+
+Cambium uses Dragonfly for uploading and image processing. To access a document
+directly, you will use the `Cambium::Document` model. Once you have a
+individual object, you can get to the Dragonfly methods through the `upload`
+attribute.
+
+So, for example, you can get to the page of the file with
+`document.upload.url`, where `document` is a `Cambium::Document` object.
+
+### Options
+
+Here are the other methods on a document instance:
+
+- `image?`: Is the file an image?
+- `pdf?`: Is the file a PDF?
+- `has_thumb?`: Can we generate an image thumbnail for the file?
+- `thumb_url`: The URL to the thumbnail image (if it can be created).
+- `ext`: The file extension
+
+Site Settings
+----------
+
+Cambium also ships with site settings, which focuses on enabling your users to
+change setting through the UI.
+
+You work with this like you would any other model, except it's more about
+finding individual records instead of creating custom fields for an object.
+
+In other words, all the configuration happens in your `config/admin/settings.yml` file. You can see there are some default ones:
+
+```yaml
+site_title:
+  type: string
+  label: Site Title
+site_description:
+  type: text
+  label: Site Description
+```
+
+Any setting field you create you can access from the `Cambium::Setting` model.
+So, for example, if you want the value of `site_title` from the above config,
+you just query: `Cambium::Setting.site_title`.
+
+Be warned, though, that if you need several settings on one page, you're better
+off grabbing a collection of the settings and then grabbing from your results
+as you need them. I'll leave that up to you!
 
 Model Options
 ----------

data/Rakefile

@@ -1 +1,20 @@
-require "bundler/gem_tasks"
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+task :default => :spec

data/app/assets/javascripts/cambium/admin/application.js.coffee

@@ -1,5 +1,6 @@
 #= require jquery
 #= require jquery_ujs
+#= require trumbowyg/trumbowyg
 #= require mark_it_zero
 #= require pickadate/picker
 #= require pickadate/picker.date

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

@@ -1,25 +1,16 @@
 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:
-    #
+  initialize: ->
     new App.Views.DefaultHelpers
     new App.Views.DropdownMenu if $('.dropdown-menu').length > 0
     new App.Views.Pickadate
+    new App.Views.Editor
+    new App.Views.MediaPicker
+    new App.Views.ImageCropper
+    new App.Views.KeyboardShortcuts
 
   routes:
-    '': 'initHomePage'
+    'admin': 'admin'
 
-  initHomePage: ->
-    console.log "Welcome to this awesome site, built using Cambium!"
+  admin: ->
+    true

data/app/assets/javascripts/cambium/admin/templates/image_cropper.jst.ejs

@@ -0,0 +1,20 @@
+<div id="modal-container">
+  <div id="title-bar">
+    <h2 class="page-title">Crop Image</h2>
+    <p>Click the focus of the image.</p>
+  </div>
+  <div class="image-container">
+    <div class="gravity">
+      <div data-gravity="nw"></div>
+      <div data-gravity="n"></div>
+      <div data-gravity="ne"></div>
+      <div data-gravity="w"></div>
+      <div data-gravity=""></div>
+      <div data-gravity="e"></div>
+      <div data-gravity="sw"></div>
+      <div data-gravity="s"></div>
+      <div data-gravity="se"></div>
+    </div>
+    <img src="<%= image.url %>">
+  </div>
+</div>