refinerycms 0.9.8.9 → 0.9.9

data/core/config/routes.rb

@@ -0,0 +1,19 @@
+::Refinery::Application.routes.draw do
+  filter(:refinery_locales) if defined?(RoutingFilter::RefineryLocales) # optionally use i18n.
+
+  root :to => 'pages#home'
+
+  match 'wymiframe(/:id)', :to => 'refinery/fast#wymiframe', :as => :wymiframe
+
+  scope(:path => 'refinery', :as => 'admin', :module => 'admin') do
+    root :to => 'dashboard#index'
+    resources :dialogs, :only => :show
+  end
+
+  match '/refinery/update_menu_positions', :to => 'admin/refinery_core#update_plugin_positions'
+
+  match '/sitemap.xml' => 'sitemap#index', :defaults => { :format => 'xml' }
+
+  # Marketable URLs should be appended to routes by the Pages Engine.
+  # Catch all routes should be appended to routes by the Core Engine.
+end

data/core/crud.md

@@ -0,0 +1,197 @@
+# The Magical Mixin: Crudify (create, read, update & delete)
+
+## Introduction
+
+__Most controllers Refinery and other apps do four common things, create, read, update and delete stuff.__ Instead of writing the same logic for these actions over and over again we wrap all this functionality up into what we called ``crudify``.
+
+``crudify`` takes these four basic actions and extends them to allow easy paging, searching and sorting too.
+
+Although this single file is included in Refinery, you could take just this single file and use it in any app you like.
+
+The best part about ``crudify`` is that this gives you a smart default and if there is anything you want to work differently just override that method.
+
+## Where is it located?
+
+``core/lib/refinery/crud.rb``
+
+## How do I use it in my engines?
+
+All you need to do is call ``crudify`` in your controller.
+
+If you used the Refinery generator you're plugin will already be using ``crudify``.
+
+### Example
+
+    class NewsItemsController < ApplicationController
+
+      crudify :news_item, :order => "created_at DESC"
+
+    end
+
+### Complex Example
+
+    class NewsItemsController < ApplicationController
+
+      crudify :news_item, :order => "created_at DESC",
+                          :conditions => 'published = true',
+                          :sortable => false,
+                          :searchable => true,
+                          :include => [:author],
+                          :paging => true,
+                          :search_conditions => ''
+
+    end
+
+## What can you configure with ``crudify``?
+
+### ``:title_attribute``
+
+Default value is ``title``
+
+This is the human readable value you want ``crudify`` to use throughout. Just choose an attribute that is on your model that is short and descriptive to what the model is.
+
+#### Example
+
+On a page model you'd probably use "title" (which is default so you don't need to specify this)
+
+#### Example 2
+
+On a ``team_member`` model you'd probably want to use an attribute like ``name``.
+
+### ``:order``
+
+Default value is ``position ASC``
+
+This is the position that is used when listing out what you're crudifying. If you have ``:sortable`` set to ``true`` you probably want to have your ``:order`` set to ``position ASC`` so it uses the order you have set when sorting.
+
+If you have a news area, it makes more sense to sort by ``posted_at``. So you might set it like this
+
+    :order => "posted_at DESC"
+
+### ``:conditions``
+
+Default value is ``nil``
+
+This will filter down the list of items you have when you're asking for all records.
+
+An example here is say you're crudifying a photos table that uses attachment_fu. Attachment_fu creates several photo records, 1 for the main photo and others for it's "children" thumbnails. Those thumbnails have a parent id set.
+
+So when viewing a list of the images you have you don't want it to show all the thumbnails too, you just want to each see unique image listed so you need to apply some conditions to hide the thumbnails.
+
+You do that like this:
+
+    :conditions => {:parent_id => nil}
+
+### ``:sortable``
+
+Default value is ``true``
+
+Enabling ``:sortable`` gives you several handy methods which "just work" with sortable JavaScript lists. One of the methods is ``update_positions()`` which handles saving the new position items have been sorted into.
+
+### ``:searchable``
+
+Default value is ``true``
+
+When this option is ``true``, the routes are modified so when you go to the next page of results the search continues on.
+
+### ``:include``
+
+Default value is ``[]``
+
+For performance optimisation, sometimes you might want to eager load other related models to this one. For example a ``news_post`` might below to a ``user`` who wrote the post. But in our index view we're printing out the name of each user.
+
+Instead of having to look up each user for each of the ``news_posts`` we iterate over, the ``:include`` option allows you to load the ``news_post`` and user all at the same time which'll allow you to save on expensive database queries.
+
+Here's an example of that.
+
+    class NewsItem
+
+      belongs_to :user
+
+    end
+
+    class NewsItemsController < ApplicationController
+
+      crudify :news_item, :order => "created_at DESC", :include => [:user]
+
+    end
+
+### ``:paging``
+
+Default value is ``true``
+
+The ``:paging`` option tells ``crudify`` you don't just want one big long list but rather to break it out into pages and support paging methods uses [will_paginate](http://wiki.github.com/mislav/will_paginate/).
+
+### ``:search_conditions``
+
+Default value is ``nil``
+
+Similar to the ``:conditions`` options, ``:search_conditions`` just apply these conditions when delivering search results.
+
+## Easy Accessor Methods
+
+``crudify`` automatically writes up finder methods for the model you're crudifying. The easier way to explain this is with an example.
+
+Say we have a pages controller that is going to manage pages.
+
+    class PagesController < ApplicationController
+
+      crudify :page
+
+    end
+
+In this controller, automatically I have these methods:
+
+    find_page()
+    find_all_pages()
+
+So say I wanted to change the way all pages are found, all I do is override the ``find_all_pages`` method.
+
+    class PagesController < ApplicationController
+
+      crudify :page
+
+      def find_all_pages
+        @pages = Page.find(...) # apply any logic I want here to get all pages.
+      end
+
+    end
+
+## Overriding or Extending Crudify
+
+Before overriding anything, the best thing to do is check out how the default works. Read the ``vendor/plugins/refinery/lib/crud.rb`` and see what code it's injecting into your controller.
+
+Pick the method you want to override and then override it in your controller.
+
+Let's go back to the example above with the pages controller.
+
+    class PagesController < ApplicationController
+
+      crudify :page
+
+    end
+
+Say every time someone deletes a page I want my ``NotificationMailer`` to email me to say someone just deleted a page.
+
+When I look in the ``crud.rb`` file I see that my controller has this added to it
+
+    def destroy
+      flash.notice = "'\#{@#{singular_name}.#{options[:title_attribute]}}' was successfully deleted." if @#{singular_name}.destroy
+      redirect_to admin_#{plural_name}_url
+    end
+
+To override this all I would is create my own delete method that works the same but just with my mailer code on it.
+
+    class PagesController < ApplicationController
+
+      crudify :page
+
+      def destroy
+        if @page.destroy
+          flash.notice = "'#{@page.title}' was successfully deleted."
+          NotificationMailer.deliver_page_deleted(@page) # sends me an email to say a page was deleted
+        end
+        redirect_to admin_pages_url
+      end
+
+    end

data/core/engines.md

@@ -0,0 +1,179 @@
+# Extending Refinery with Engines
+
+## Introduction
+
+__Refinery is designed to be easily extended so you can quickly customise your Refinery site to manage new areas you want to add to your site. If you see something you want to customise, the chances are you can customise it.__
+
+The main way of extending Refinery is through adding new engines to your app. By default you can edit pages in Refinery's backend, but how do you add a new section to manage like products?
+
+See: [The Refinery Engine Generator](http://github.com/resolve/refinerycms-generators/blob/master/readme.md#readme)
+
+## The Structure of an Engine
+
+Think of a engine in Refinery as a small Rails app. Engines have a structure that is extremely similar to a Rails app. Here's an example of Refinery's pages engine (located in Refinery's ``pages/`` folder)
+
+    pages
+      |- app
+      |   |- controllers
+      |   |   |- admin
+      |   |   |    |- pages_dialogs_controller.rb
+      |   |   |    |- page_parts_controller.rb
+      |   |   |    |- pages_controller.rb
+      |   |   |- pages_controller.rb
+      |   |- helpers
+      |   |   |- pages_helper.rb
+      |   |- models
+      |   |   |- page.rb
+      |   |- views
+      |       |- pages
+      |       |   |- home.html.erb
+      |       |   |- show.html.erb
+      |       |- admin
+      |           |- pages
+      |               |- _form.html.erb
+      |               |- edit.html.erb
+      |               |- index.html.erb
+      |               |- new.html.erb
+      |- config
+      |   |- routes.rb
+      |- rails
+          |- init.rb
+
+
+### app/controllers
+
+In this example you see one "public" controller ``app/controllers/pages_controller`` that is responsible for managing the front end when I view a page.
+
+### app/controllers/admin
+
+This bit is important. It's where all the controllers are held to manage pages in the Refinery back end in this example. You can ignore the ``pages_dialogs_controller.rb`` and ``page_parts_controller.rb`` for now and let's just focus on the ``admin/pages_controller.rb`` file. Here's what that looks like inside at a basic level:
+
+    module Admin
+      class PagesController < Admin::BaseController
+
+        crudify :page, :conditions => {:parent_id => nil},
+                       :order => "position ASC", :paging => false
+
+      end
+    end
+
+This single controller allows us to create, read, update and delete pages in the backend. With a little bit of Refinery magic we utilise the [crudify mixin](http://github.com/resolve/refinerycms/blob/master/core/crud.md) which gives us all of these regular features out of the box.
+
+How crudify works is an entire topic of it's own. Checkout the [crudify documentation](http://github.com/resolve/refinerycms/blob/master/core/crud.md) to get an insight into how that works.
+
+### app/views and app/helpers
+
+Works exactly the same as ``app/views`` and ``app/helpers`` in a normal Rails app. You just put the views and helpers related to this engine in here instead of in your actual main app directory.
+
+### config/routes.rb
+
+Works exactly the same as ``config/routes.rb`` in your app except this routes file only loads the routes for this engine.
+
+### rails/init.rb
+
+This file runs when your site is started up. All is does is registers this engine with Refinery so it knows that it exists, how to handle it in the Refinery admin menu and how to render recent activity on the Dashboard (see "Getting your Engine to Report Activity in the Dashboard")
+
+NOTE: The latest version of Refinery requires that you only specify a engine.name. plugin.title &amp; plugin.description will be looked up by the I18n system.
+
+# pages/lib/pages.rb
+    Refinery::Plugin.register do |plugin|
+      plugin.name = "pages"
+      plugin.version = 1.0
+      plugin.menu_match = /(refinery|admin)\/page(_dialog|part)?s$/
+      plugin.activity = {
+        :class => Page,
+        :url_prefix => "edit_",
+        :title => "title",
+        :created_image => "page_add.png",
+        :updated_image => "page_edit.png"
+      }
+    end
+
+# pages/config/locales/en.yml
+    en:
+      plugins:
+        refinery_pages:
+          title: Pages
+          description: Manage content pages
+
+## Getting your Engine to Report Activity in the Dashboard
+
+Recent activity reporting is built right in, so all you need to do is follow the convention below and your engine will start showing up in the recent activity list of the Dashboard.
+
+In our example above we showed the use of ``plugin.activity`` for the pages engine.
+
+    Refinery::Plugin.register do |plugin|
+      plugin.name = "pages"
+      plugin.version = 1.0
+      plugin.menu_match = /(refinery|admin)\/page(_dialog|part)?s$/
+      plugin.activity = {
+        :class => Page,
+        :url_prefix => "edit_",
+        :title => "title",
+        :created_image => "page_add.png",
+        :updated_image => "page_edit.png"
+      }
+    end
+
+Here's what the different activity options mean:
+
+### Required
+
+    :class
+    # the name of the class we're watching.
+
+    :url_prefix
+    # Just use "edit_" if you're not sure how this works.
+    #
+    # When it says "'About' page was updated about 4 hours ago", the page title "About"
+    # is linked to that page in a way we specify.  So by setting "_edit" as a :url_prefix what
+    # we're doing is making it link to the page that allows us to edit this page.
+    # So the next result is edit_admin_page_url(page)
+
+    :title
+    # which attribute on the :class should be in the activty message. In our case it's "title"
+    # because we want it to run something like this "#{page.title} was updated about ...."
+
+### Optional
+
+    :created_image and :updated_image
+    # the activity monitor knows if something is created or updated and shows a different icon
+    # depending on how you want that to look. You can specify the filename to any image you
+    # want in the public/images/refinery/icons/ directory.
+
+## Search Engine Optimisation: Improving the default URLs
+
+In our example above we extended Refinery to manage a products area. The problem is when I look at a product on the front end I get a URL like [http://localhost:3000/products/1](http://localhost:3000/products/1) but I would really like it to be something like [http://localhost:3000/products/my-product](http://localhost:3000/products/my-product)
+
+To achieve this all you need to do is open up the product model (found in ``/vendor/plugins/products/app/models/product.rb``) and add the following line inside your class:
+
+    has_friendly_id :title, :use_slug => true
+
+Note you want to change ``:title`` to the field which you want to show up in the URL.
+
+This will work just fine for new products added from this point, but you'll want to migrate any existing products you have to use this new URL format. All you have to do is save each product you have in the database to make it create a nice URL for you.
+
+    ruby script/console
+    >> Product.all.each {|p| p.save };nil
+
+Now all the products in your database will have nice URLs.
+
+## How to get a WYSIWYG editor to show on your form fields
+
+Refinery uses a standards compliant visual editor called [WYMeditor](http://www.wymeditor.org/)
+
+_Note: When using the Refinery generator, if you apply a field type of "text" to any of your fields, they automatically load as a WYMEditor._
+
+The WYSIWYG editor can only be applied to a ``textarea``. All you need to do is add a class of "wymeditor widest" to a ``textarea`` in your form and a WYSIWYG WYMEditor will load right in place.
+
+### Example
+
+Again going back to our product plugin example if you had this in your ``vendor/plugins/products/app/views/admin/products/_form.html.erb`` file:
+
+    <%= f.text_area :description %>
+
+Just change that to:
+
+    <%= f.text_area :description, :class => "wymeditor widest" %>
+
+Refresh and you're done.

data/core/features/search.feature

@@ -0,0 +1,55 @@
+@refinerycms @search
+Feature: Search
+  In order find content more quickly
+  As an administrator
+  I want to use search
+
+  Background:
+    Given I am a logged in refinery user
+
+  @search-existing
+  Scenario Outline: Search Existing Item
+    Given I have a <item> titled "<title>"
+    When I go to the list of <location>
+    And I fill in "search" with "<title>"
+    And I press "Search"
+    Then I should see "<title>"
+
+    Examples:
+      |  item  | title  |   location   |
+      |page    |testitem|pages         |
+      |setting |testitem|settings      |
+
+  # This will only run when resources engine is installed.
+  @search-file
+  Scenario: Search File
+    When I upload the file at "refinery_is_awesome.txt"
+    And I go to the list of files
+    And I fill in "search" with "Refinery Is Awesome"
+    And I press "Search"
+    Then I should see "Refinery Is Awesome"
+
+  # This will only run when images engine is installed.
+  @search-image
+  Scenario: Search Image
+    When I upload the image at "beach.jpeg"
+    And I go to the list of images
+    And I fill in "search" with "Beach"
+    And I press "Search"
+    Then I should see "Beach"
+
+  @search-nonexisting
+  Scenario Outline: Search Nonexisting Item
+    Given I have no <item>
+    When I go to the list of <location>
+    And I fill in "search" with "nonexisting"
+    And I press "Search"
+    Then I should see "Sorry, no results found"
+
+    Examples:
+      |  item   |   location   |
+      |pages    |pages         |
+      |images   |images        |
+      |files    |files         |
+      |settings |settings      |
+