effective_pages 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b7a8cb961d2c8e48119552c15b79ba0042e5ed3d
-  data.tar.gz: d0572a2cc302859052aaabb7d61f9a0f0f3702a0
+  metadata.gz: ddac8c5966ed3e1d03290f2faca0b85932cc36a3
+  data.tar.gz: 5342d8e6be2b9269a0c419ef1c4ab5420f08d4ca
 SHA512:
-  metadata.gz: 711bb11642aa463828cb2bd0231bb284bb8366ce63601fbf73fae30ae60d13ca3d29b1dbb09af1adb9c44a17ab347ee38d249439d306aa17844f530633a944df
-  data.tar.gz: 459199b5df27a960d9ba4e5e00c5d3b156dad57bd34eb27864eb9fae8aedffa78b68299a4e6e7bee7aab95923c71db842d173148a470609a82198d00552c043a
+  metadata.gz: b029523505a15f7a50a3865aac1d40ec63fa334d4f7affb01aaeeff1e21e1afa3a85428bb0b5cecf475daaa65a84239ed23bac450bb01a54b42479a43f4e02ae
+  data.tar.gz: 582121876ff42513540c06689f48489b7df190858bac4c32d72179ca7a2a8e51c200b426a860218482ce36ed9387de4299e328acb469b202dd28e0b768125223

data/README.md

@@ -1,30 +1,402 @@
 # Effective Pages
 
-Rise of the effective page!!
+Content pages, bootstrap3 menu builder and page-specific header tag helpers for your Rails app.
 
-This is a work in progress gem that's ALMOST ready for release
+Create content pages ontop of one or more templates -- just regular Rails views -- that you define and control.
 
-TODO: Make a README!
+Edit menus with a WYSIWYG drag-and-drop bootstrap3-strict menu builder.
 
-effective_pages.page_url
-effective_pages.page_path
+Use this gem to create a fully-functional CMS that provides full or restricted editing for your end users.
 
+Built ontop of effective_regions.
 
-No javascript to add for Pages
 
-Put
+## Getting Started
 
-= effective_page_header_tags
+Please first install the [effective_regions](https://github.com/code-and-effect/effective_regions) and [effective_datatables](https://github.com/code-and-effect/effective_datatables) gems.
 
-in your header, so the page title and meta-description can be saved
+Please download and install [Twitter Bootstrap3](http://getbootstrap.com)
 
+Add to your Gemfile:
 
-If you want to use regular maxDepth == 2 bootstrap3 menus, no CSS to add
+```ruby
+gem 'effective_pages'
+```
 
-if you want deep menus, you can add
+Run the bundle command to install it:
 
-@import 'effective_pages'; for unlimitted depth bootstrap3 menus addon
+```console
+bundle install
+```
 
-then call = render_menu('main menu', :maxdepth => 3)
+Then run the generator:
+
+```ruby
+rails generate effective_pages:install
+```
+
+The generator will install an initializer which describes all configuration options and creates a database migration.
+
+If you want to tweak the table name (to use something other than the default 'pages', 'menus', 'menu_items'), manually adjust both the configuration file and the migration now.
+
+Then migrate the database:
+
+```ruby
+rake db:migrate
+```
+
+There are no required javascript or stylesheet includes.
+
+
+### Post Installation
+
+Once the above Getting Started tasks have been completed, there are still a few small things that need to be initialized and configured.
+
+The documentation for these post-installation tasks is split up into the following Pages and Menus sections.
+
+
+## Pages
+
+To create your first content page, visit `/admin/pages` and click `New Page`.
+
+This first page will be created with the provided `example` page view template and allow you to immediately jump into the effective_regions editor when you click `Save and Edit Content`.
+
+This page will be available on your website at a route matching the slugified title.
+
+### View Template and Layout
+
+Every Effective::Page is rendered by a regular Rails view file and layout.  The same as any standard Rails #show action.
+
+When creating a Page, if the `app/views/layouts/` directory contains more than one layout file, you will be able to choose which layout to use when displaying this Page.  If your Rails app contains only the default `application` layout then this layout will be used.
+
+As well, when creating your Effective::Page object, if the `app/views/effective/pages/` directory contains more than one view file, you will be able to choose which view is used to display this Page.
+
+When this gem's installation generator is run, the `app/views/effective/pages/example.html.haml` page view template is created.  To add additional page view templates, just create more views in this directory.
+
+An example of a two-column layout I like to create is as follows:
+
+```haml
+%h1
+  = simple_effective_region page, :header do
+    = page.title
+
+.row
+  .col-sm-6
+    = effective_region page, :left do
+      %p this is default left column content
+  .col-sm-6
+    = effective_region page, :right do
+      %p this is default right column content
+```
+
+You can add anything to these page views. The views are not required to contain any effective_regions, but then they wouldn't be user-editable.
+
+### Routes
+
+All Effective::Page pages are immediately available to your application at a url matching the slugified title.
+
+This gem's page routes are evaluated last, after all your existing routes.  This may cause an issue if you create an Effective::Page titled `Events` but you already have a route matching `/events` such as `resources :events`.  You can edit the Effective::Page object and set the slug to a value that does not conflict.
+
+To find the path for an Effective::Page object:
+
+```ruby
+page = Effective::Page.find_by_title('My Page')
+
+effective_pages.page_path(page)
+effective_pages.page_url(page)
+```
+
+If you would like to use an Effective::Page for your home/root page, add the following to your routes.rb:
+
+```ruby
+root :to => 'Effective::Pages#show', :id => 'home'
+```
+
+and make sure a page with slug 'home' exists.
+
+
+### Header Tags
+
+Your layout needs to be configured to set the appropriate html `<title>` and `<meta>` tags.
+
+In your application layout and any additional layouts files, add the following to the `<head>` section:
+
+```ruby
+= effective_pages_header_tags
+```
+
+This helper inserts a `<title>...</title>` html tag based on the `@page_title` instance variable, which you can set anywhere on your non-effective controllers, and whose value is set to the `@page.title` value when displaying an `Effective::Page`.
+
+This helper also inserts a `<meta name='description' value='...' />` html tag based on the Effective::Page's meta description value.  This tag provides the content that search engines use to display their search results.
+
+This helper is entirely optional and in no way required for effective_pages to work.
+
+### Body Tag Classes
+
+Another optional helper.  Add the following to your `<body>` tag:
+
+```haml
+%body{:class => effective_pages_body_classes}
+```
+
+to apply the following html classes:  `params[:controller]`, `params[:action]`, `signed-in` / `not-signed-in`, `@page.template` and any thing set in the `@body_classes` instance variable.
+
+This provides a mechanism to easily target CSS styles for specific pages.
+
+This helper is entirely optional and in no way required for effective_pages to work.
+
+### Permissions
+
+When creating a Page, if you've also installed the [effective_roles](https://github.com/code-and-effect/effective_roles) gem, you will be able to configure user access on a per-page basis.
+
+Use this functionality to create member-only type pages.
+
+
+## Menus
+
+The menus rendered by this gem output strict bootstrap3 (v3.3.2) html.  It is intended for bootstrap3 navbars as well as footer menus, sidebar menus and more.  It outputs the ul tag and all contained li items:
+
+```html
+<ul class="nav navbar-nav">
+...
+</ul>
+```
+
+The bootstrap3 `.active` class will be added to the appropriate li item based on the current page.
+
+
+### Create a menu
+
+Each Effective::Menu object is referred to by its title. The title is unique, so only one `'main menu'` can exist.
+
+To display our first menu, we must create an Effective::Menu object and then render it in the Rails application layout or appropriate view.
+
+To create your first menu, either:
+
+- Visit `/admin/menus` and click `New Menu`.  Give it a title: `'main menu'`.
+
+or
+
+- Run `bundle exec rake effective_pages:seed` to create a menu called `'main menu'` with some placeholder menu items.
+
+then add it to your application layout where you would normally display your site's menu:
+
+```html
+= render_menu('main menu')
+```
+
+or with some additional custom classes rendered on the opening `<ul>` tag
+
+```html
+= render_menu('main menu', :class => 'menu-right')
+```
+
+
+### Editing menu items
+
+Once created and displayed by your application layout, the menu items will be drag-and-drop editable on any page where the menu is present.  This menu editting functionality requires the [effective_regions](https://github.com/code-and-effect/effective_regions) gem.
+
+So to edit the menu, visit any page on your website prefixed with `/edit/`.  This will load the effective_regions editor, and all displayed Effective::Menu menus will have a dotted blue border which indicates it to be an editable region.
+
+NOTE: Right now, the page you visit to edit the menu must contain an effective_region somewhere in a view.  This requirement may be removed in the future.  The menu editor will not work unless at least one effective_region is used somewhere on the page.
+
+Once you're on the edit page and see the dotted blue bordered menus:
+
+- Hover over the menu to click the Add button.
+- Drag-and-drop items around to set their position in the menu.
+- Drag-and-drop a menu item onto the trashcan icon to delete it.
+- Double-click a menu item to bring up a dialog and configure its properties.
+
+The menu item dialog provides all configurable options for each menu item.
+
+A menu item's link can be configured in four different ways:
+
+- Page, links to an Effective::Page object
+- URL, any url you type
+- Route, any rails route, such as destroy_user_session_path, root_path, or events_path
+- Divider, an li with class='divider'
+
+From this dialog, you can also configure permissions and add raw html classes.
+
+Clicking 'Save' from the toolbar will persist the changes you've made to any menus.
+
+
+### Menu building DSL
+
+Menus may also be created programatically.
+
+As an Aside:
+
+- To store the Effective::Menu tree structure, this gem implements the Modified Preorder Tree Traversal algorithm.
+- Check out the [Storing Hierarchial Data in a Database](http://www.sitepoint.com/hierarchical-data-database-2/) guide for background information on this algorithm.
+- You don't have to worry about any lft and rgt values when building menus with this gem.
+
+To create the same tree structure used in the above article:
+
+```ruby
+Effective::Menu.new(:title => 'some menu').build do
+  dropdown 'Fruit' do
+    dropdown 'Red' do
+      item 'Cherry'
+    end
+
+    dropdown 'Yellow' do
+      item 'Banana'
+    end
+  end
+
+  dropdown 'Meat' do
+    item 'Beef'
+    item 'Pork'
+  end
+end.save
+```
+
+and another more advanced example:
+
+```ruby
+Effective::Menu.new(:title => 'main menu').build do
+  dropdown 'About' do
+    item Effective::Page.find_by_title('Who Are We?')
+    divider
+    item Effective::Page.find_by_title('Code of Ethics'), '#', :class => 'nav-indent'
+    item Effective::Page.find_by_title('Entrance Requirements'), '#', :class => 'nav-indent'
+    item Effective::Page.find_by_title('Board and Staff')
+  end
+
+  item 'Portal', :user_portal_path
+  item 'Pay Fees', '/fee_payments/new'
+  item 'Events', :events_path
+
+  dropdown 'Current Members', :roles_mask => 1 do # effective_roles. Only members see this dropdown
+    item Effective::Page.find_by_title('Volunteer Opportunities')
+    item Effective::Page.find_by_title('Mentoring')
+  end
+
+  dropdown 'Account', :signed_in => true do # Only current_user.present? users see this dropdown
+    item 'Site Admin', '/admin', :roles_mask => 3 # effective_roles.  Only admins see this item
+    item 'Account Settings', :user_settings_path
+    divider
+    item 'Downloads', '#'
+    item 'Mentoring Resources', '#'
+    divider
+    item 'Sign Out', :destroy_user_session_path
+  end
+
+  item 'Sign In', :new_user_session_path, :signed_out => true # Only current_user.blank? users see this item
+end.save
+```
+
+The entire DSL consists of just 3 commands:  dropdown, item and divider
+
+with the following valid options:
+
+```ruby
+:signed_in => true|false    # Only signed in (current_user.present?) users see this item
+:signed_out => true|false   # Only signed out (current_user.blank?) users see this item
+:roles_mask => 1            # See effective_roles Bitmask Implementation
+:class => 'custom classes'  # Custom HTML classes
+:new_window => true         # Open link in a new window
+```
+
+### Max Depth
+
+The default max-depth for bootstrap3 menus is 2.  As per the bootstrap3 navbar component, there exist only top level items and top level dropdowns that may contain only li items.  No dropdowns in dropdowns.
+
+This gem has the ability to extend the bootstrap3 functionality and provides support for dropdowns inside dropdowns to any nested depth.
+
+To enable this functionality, require the following stylesheet on the asset pipeline by adding to your application.css:
+
+```ruby
+*= require effective_pages
+```
+
+and change the `config.menu[:maxdepth]` value in the `app/config/initializers/effective_pages.rb` initializer to 3, 4, or even 9999.
+
+
+## Authorization
+
+All authorization checks are handled via the config.authorization_method found in the `config/initializers/effective_pages.rb` file.
+
+It is intended for flow through to CanCan or Pundit, but neither of those gems are required.
+
+This method is called by all controller actions with the appropriate action and resource
+
+Action will be one of [:index, :show, :new, :create, :edit, :update, :destroy]
+
+Resource will the appropriate Effective::Page object or class
+
+The authorization method is defined in the initializer file:
+
+```ruby
+# As a Proc (with CanCan)
+config.authorization_method = Proc.new { |controller, action, resource| authorize!(action, resource) }
+```
+
+```ruby
+# As a Custom Method
+config.authorization_method = :my_authorization_method
+```
+
+and then in your application_controller.rb:
+
+```ruby
+def my_authorization_method(action, resource)
+  current_user.is?(:admin) || EffectivePunditPolicy.new(current_user, resource).send('#{action}?')
+end
+```
+
+or disabled entirely:
+
+```ruby
+config.authorization_method = false
+```
+
+If the method or proc returns false (user is not authorized) an Effective::AccessDenied exception will be raised
+
+You can rescue from this exception by adding the following to your application_controller.rb:
+
+```ruby
+rescue_from Effective::AccessDenied do |exception|
+  respond_to do |format|
+    format.html { render 'static_pages/access_denied', :status => 403 }
+    format.any { render :text => 'Access Denied', :status => 403 }
+  end
+end
+```
+
+### Permissions
+
+The permissions you actually want to define are as follows (using CanCan):
+
+```ruby
+can [:show], Effective::Page
+can [:manage], Effective::Page if user.is?(:admin)
+```
+
+
+## License
+
+MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+
+Code and Effect is the product arm of [AgileStyle](http://www.agilestyle.com/), an Edmonton-based shop that specializes in building custom web applications with Ruby on Rails.
+
+
+## Testing
+
+Run tests by:
+
+```ruby
+guard
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request
 
 

data/app/helpers/effective_pages_helper.rb

@@ -1,10 +1,30 @@
 module EffectivePagesHelper
-  def effective_page_header_tags(options = {})
-    @page ||= nil
 
-    [ content_tag(:title, (@page_title || options[:title] || @page.try(:title))),
-      "<meta content='#{options[:meta_description] || @page.try(:meta_description)}' name='description' />",
-    ].join("\n").html_safe
+  def effective_pages_body_classes
+    [
+      params[:controller].parameterize,
+      params[:action],
+      ((user_signed_in? ? 'signed-in' : 'not-signed-in') rescue nil),
+      (@page.template rescue nil),
+      @body_classes
+    ].compact.join(' ')
+  end
+
+  def effective_pages_header_tags
+    [
+      content_tag(:title, effective_pages_site_title),
+      effective_pages_meta_description_tag
+    ].compact.join("\n").html_safe
+  end
+
+  def effective_pages_site_title
+    (@page_title ? @page_title.to_s : "#{params[:controller].try(:titleize)} #{params[:action].try(:titleize)}") + EffectivePages.site_title_suffix.to_s
+  end
+
+  def effective_pages_meta_description_tag
+    if @page.try(:meta_description).present?
+      "<meta content='#{@page.try(:meta_description)}' name='description' />"
+    end
   end
 
   def application_root_to_effective_pages_slug

data/lib/effective_pages/version.rb

@@ -1,3 +1,3 @@
 module EffectivePages
-  VERSION = "0.8.1"
+  VERSION = "0.9.0"
 end

data/lib/effective_pages.rb

@@ -9,6 +9,7 @@ module EffectivePages
   mattr_accessor :pages_path
   mattr_accessor :excluded_pages
   mattr_accessor :excluded_layouts
+  mattr_accessor :site_title_suffix
 
   mattr_accessor :authorization_method
   mattr_accessor :simple_form_options

data/lib/generators/templates/effective_pages.rb

@@ -5,13 +5,18 @@ EffectivePages.setup do |config|
   config.menus_table_name = :menus
   config.menu_items_table_name = :menu_items
 
+  # The directory where your page templates live
+  # Any files in this directory will be automatically available when
+  # creating/editting an Effective::Page from the Admin screens
   # Relative to app/views/
   config.pages_path = '/effective/pages/'
 
   # Excluded Pages
+  # Any page templates from the above directory that should be excluded
   config.excluded_pages = []
 
   # Excluded Layouts
+  # Any app/views/layouts/ layout files that should be excluded
   config.excluded_layouts = [:admin]
 
   # Use CanCan: can?(action, resource)
@@ -21,11 +26,14 @@ EffectivePages.setup do |config|
   # Layout Settings
   # Configure the Layout per controller, or all at once
 
-  # config.layout = 'application'   # The layout for the EffectivePages admin screen
+  # The layout for the EffectivePages admin screen
   config.layout = {
     :admin => 'application'
   }
 
+  # This string will be appended to the effective_pages_header_tags title tag
+  config.site_title_suffix = " | #{Rails.application.class.name.split('::').first.titleize}"
+
   # SimpleForm Options
   # This Hash of options will be passed into any simple_form_for() calls
   config.simple_form_options = {}
@@ -42,8 +50,8 @@ EffectivePages.setup do |config|
 
   # All effective_page menu options
   config.menu = {
-    :apply_active_class => true,
-    :maxdepth => 2
+    :apply_active_class => true,  # Add an .active class to the appropriate li item based on current page url
+    :maxdepth => 2                # 2 by default, strict bootstrap3 doesnt support dropdowns in your dropdowns
   }
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: effective_pages
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Code and Effect
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-20 00:00:00.000000000 Z
+date: 2015-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -122,7 +122,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.2.0
-description: CRUD Pages with intention to work with EffectiveRegions. WIP.
+description: Content pages, bootstrap3 menu builder and page-specific header tag helpers
+  for your Rails app.
 email:
 - info@codeandeffect.com
 executables: []
@@ -232,7 +233,8 @@ rubyforge_project:
 rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
-summary: CRUD Pages with intention to work with EffectiveRegions. WIP.
+summary: Content pages, bootstrap3 menu builder and page-specific header tag helpers
+  for your Rails app.
 test_files:
 - spec/controllers/effective/pages_controller_spec.rb
 - spec/dummy/app/assets/javascripts/application.js