refinerycms 0.9.5.30 → 0.9.5.31

data/vendor/plugins/refinery/plugins.md

@@ -0,0 +1,194 @@
+# Extending Refinery with Plugins
+
+## 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 plugins 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?
+
+## The Refinery Generator
+
+The Refinery generator is a standard Rails generator that functions just like the scaffold generator. It allows you to quickly add new "tabs" to the Refinery backend and the front end views.
+
+To see how to use the generator run
+
+    ruby script/generate refinery
+
+## Example of Using the Generator
+
+Let's say you have a client who has a range of products they want to show on their website.
+
+First decide what fields they need to manage. In our case the client is going to want to edit the title and description of each product. They would also like a little "facts panel" to show on the right of the page. 
+
+So go to the root of your project and run
+
+    ruby script/generate refinery
+  
+This will output the help on how to use the generator. To generate the new section we want to manage products we run:
+
+    ruby script/generate refinery product title:string description:text facts:text
+  
+The generator will output a list of files it generated. You'll notice there is a new plugin that has been added in ``vendor/plugins/products``. This is where both the backend and front end files are held for this new products area.
+
+A new database migration has been added to add the products table in so run:
+
+    rake db:migrate
+
+Start up your app by running ``ruby script/server`` go to [http://localhost:3000](http://localhost:3000) and you'll see instantly a new menu item called "products". Click on that and you'll see there are no products yet.
+
+Now go to the backend of your site by visiting [http://localhost:3000/admin](http://localhost:3000/admin) and logging in. You'll see a new tab called "Products", click on that and then click "Add a new product", fill the form and to add an example product. Now go back to the front end and you'll see your product is showing up in the products part of your site.
+
+Now you have a fully managed products section in Refinery, nice.
+
+If you want to modify your generated plugin you need to understand the basic structure of how they work.
+
+## The Structure of a Plugin
+
+Think of a plugin in Refinery as a small Rails app or an "engine". Plugins have a structure that is extremely similar to a Rails app. Here's an example of Refinery's pages plugin (located in Refinery's ``vendor/plugins/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:
+
+    class Admin::PagesController < Admin::BaseController
+
+      crudify :page, :conditions => "parent_id IS NULL",
+                     :order => "position ASC", :paging => false
+
+    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 which gives us all of these regular features out of the box.
+
+To read more about how crudify works, checkout the crudify.md file.
+
+### 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 plugin 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 plugin.
+
+### rails/init.rb
+
+This file runs when your site is started up. All is does is registers this plugin 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 plugin to report activity in the dashboard")
+
+    Refinery::Plugin.register do |plugin|
+      plugin.title = "Pages"
+      plugin.description = "Manage content pages"
+      plugin.version = 1.0
+      plugin.menu_match = /admin\/((pages)|(page_dialogs)|(page_parts))$/
+      plugin.activity = {:class => Page,
+                         :url_prefix => "edit_",
+                         :title => "title",
+                         :created_image => "page_add.png",
+                         :updated_image => "page_edit.png"}
+    end
+  
+## Getting your plugin 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 plugin 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 plugin.
+
+    Refinery::Plugin.register do |plugin|
+      plugin.title = "Pages"
+      plugin.description = "Manage content pages"
+      plugin.version = 1.0
+      plugin.menu_match = /admin\/((pages)|(page_dialogs)|(page_parts))$/
+      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
+    # when it says "'About Us' page was updated about 4 hours ago", the page title "About Us" 
+    # is linked to that page in a way we specify.  So by setting "_edit" as a :url_preview what
+    # we're doing is making it link to the page that allows us to edit this 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.
+
+## Improving the 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, :strip_diacritics => 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/)
+
+The WYSIWYG editor can only be applied to a ``textarea``. All you need to do is add a class of "wymeditor" 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" %>
+  
+Refresh and you're done.

data/vendor/plugins/refinery/rails/init.rb

@@ -7,3 +7,8 @@ Refinery::Plugin.register do |plugin|
   plugin.menu_match = /admin\/(refinery_core|base)$/
 end
 require_dependency 'refinery/form_helpers'
+require_dependency 'refinery/base_presenter'
+
+presenters_path = "#{RAILS_ROOT}/app/presenters/"
+$LOAD_PATH << presenters_path
+::ActiveSupport::Dependencies.load_paths << presenters_path

data/vendor/plugins/refinery_settings/settings.md

@@ -0,0 +1,5 @@
+# Settings
+
+![Refinery Settings](http://refinerycms.com/system/images/0000/0666/settings.png)
+
+need to add info in here about how to use a setting in your plugin.

data/vendor/plugins/resources/resources.md

@@ -0,0 +1,9 @@
+# Resources
+
+## About
+
+The Resources plugin allows you to upload files such as PDFs and other files you want your users to download.
+
+## How it works
+
+The resources plugins is made up of attachment_fu and the Crudfiy mixin (see the crud.md file for details)

data/vendor/plugins/themes/app/controllers/themes_controller.rb

@@ -1,26 +1,23 @@
 class ThemesController < ApplicationController
  
   def stylesheets
-    render_theme_item(:stylesheets, params[:filename], 'text/css; charset=utf-8')
-  end
- 
-  def javascripts
-    render_theme_item(:javascript, params[:filename], 'text/javascript; charset=utf-8')
+    render_theme_item(:stylesheets, params[:filepath])
+  end                                                
+                                                     
+  def javascripts                                    
+    render_theme_item(:javascripts, params[:filepath])
   end
  
   def images
-    render_theme_item(:images, params[:filename])
+    render_theme_item(:images, params[:filepath])
   end
  
 protected
  
-  def render_theme_item(type, file, mime = nil)
-    mime ||= mime_for(file)
-
-    file_path = File.join(RAILS_ROOT, "themes", RefinerySetting[:theme], "#{type}/#{file}#{params[:extension]}")
-
+  def render_theme_item(type, relative_path)
+    file_path = File.join(RAILS_ROOT, "themes", RefinerySetting[:theme], type.to_s, relative_path)
  		if File.exists? file_path
-    	send_file(file_path, :type => mime, :disposition => 'inline', :stream => true)
+    	send_file(file_path, :type => mime_for(relative_path), :disposition => 'inline', :stream => true)
 		else
 			return error_404
 		end
@@ -28,11 +25,11 @@ protected
  
   def mime_for(filename)
 		# could we use the built in Rails mime types to work this out?
-    case filename.downcase
+    case filename.last.downcase
     when /\.js$/
-      'text/javascript'
+      'text/javascript; charset=utf-8'
     when /\.css$/
-      'text/css'
+      'text/css; charset=utf-8'
     when /\.gif$/
       'image/gif'
     when /(\.jpg|\.jpeg)$/

data/vendor/plugins/themes/app/models/theme.rb

@@ -8,10 +8,10 @@ end
 
 class Theme < ActiveRecord::Base
 
-	before_save :read_theme
+  before_save :read_theme
 
   has_attachment :storage => (USE_S3_BACKEND ? :s3 : :file_system),
-          			 :size => 0.kilobytes..15.megabytes,
+          			 :size => 0.kilobytes..25.megabytes,
 								 :path_prefix => (USE_S3_BACKEND ? nil : 'public/system/themes'),
 								 :content_type => 'application/zip'
 
@@ -19,10 +19,10 @@ class Theme < ActiveRecord::Base
 	def after_attachment_saved
 		if Theme::directory_is_writable?
 			# make the folder for the them
-			FileUtils.mkdir(self.theme_path) unless File.exists? self.theme_path
+			FileUtils.mkdir(self.theme_path) unless File.directory? self.theme_path
 
 			# extracts the contents of the zip file into the theme directory
-		 	Zip::ZipFile.foreach(self.filename) do |entry|
+		 	Zip::ZipFile.foreach(self.full_filename) do |entry|
 				FileUtils.mkdir_p(File.dirname("#{theme_path}/#{entry}"))
 				entry.extract("#{theme_path}/#{entry}") { true }
 		  end
@@ -32,7 +32,7 @@ class Theme < ActiveRecord::Base
 	end
 
 	def theme_folder_title
-		File.basename(self.filename).split(".").first
+		File.basename(self.full_filename).split(".").first
 	end
 
 	def theme_path
@@ -44,15 +44,9 @@ class Theme < ActiveRecord::Base
 	end
 
 	def read_theme
-		self.title = File.basename(self.filename).split(".").first.titleize
-
-		if File.exists? File.join(theme_path, "LICENSE")
-			self.license =  File.open(File.join(theme_path, "LICENSE")).read
-		end
-
-		if File.exists? File.join(theme_path, "README")
-			self.description =  File.open(File.join(theme_path, "README")).read
-		end
+		self.title = File.basename(self.full_filename).split(".").first.titleize
+		self.license = File.open(File.join(theme_path, "LICENSE")).read if File.exists? File.join(theme_path, "LICENSE")
+    self.description = File.open(File.join(theme_path, "README")).read if File.exists? File.join(theme_path, "README")
 	end
 
 	def self.directory_is_writable?

data/vendor/plugins/themes/config/routes.rb

@@ -5,8 +5,8 @@ ActionController::Routing::Routes.draw do |map|
   end
 
 	# allows theme files that are not in the Rails public directory to be served back to the client
- 	map.connect 'stylesheets/theme/:filename*extension', :controller => 'themes', :action => 'stylesheets'
-  map.connect 'javascripts/theme/:filename*extension', :controller => 'themes', :action => 'javascripts'
-  map.connect 'images/theme/:filename*extension', :controller => 'themes', :action => 'images'
+  map.connect 'stylesheets/theme/*filepath', :controller => 'themes', :action => 'stylesheets'
+  map.connect 'javascripts/theme/*filepath', :controller => 'themes', :action => 'javascripts'
+  map.connect 'images/theme/*filepath', :controller => 'themes', :action => 'images'
 
 end

data/vendor/plugins/themes/themes.md

@@ -0,0 +1,133 @@
+# Themes
+
+![Refinery Dashboard](http://refinerycms.com/system/images/0000/0576/dashboard.png)
+
+## Introduction
+
+__Themes allow you to wrap up the design of your Refinery site into a single folder that is portable.__
+
+Refinery doesn't force you to learn a special templating language, but rather just uses the regular
+ERB views you're used to in Rails. This means creating a theme from your existing site is extremely easy.
+
+Think of a theme as your ``app/views`` directory with a few extra things like images, css and javascript.
+
+It's worth noting you don't need to use a theme if you don't want to. Placing files in the ``app/views`` directory like any other Rails app will work just fine. It's only if you want to wrap your design up into a single location that you would use a theme or allow your client to easily change designs.
+
+## The structure of a theme
+
+Themes sit in your Rails app like this
+
+    app/
+    config/
+    db/
+    lib/
+    public/
+    themes/
+      |- mytheme/
+      |- othertheme/
+    plugins/
+    tests/
+
+So let's take the ``mytheme`` example theme shown above. This is how the theme is structured:
+
+    mytheme/
+       |- images
+       |    |- whatever.png
+       |    |- foo.jpg
+       |- javascripts
+       |    |- whatever.js
+       |- LICENSE
+       |- preview.png
+       |- README
+       |- stylesheets/
+       |    |- application.css
+       |    |- whatever.css
+       |- views
+            |- pages
+            |    |- show.html.erb
+            |    |- index.html.erb
+            |- layouts
+                 |- application.html.erb
+             
+### Images
+
+Usually this would be just what you have in ``public/images`` except we move that to the theme instead.
+
+### Javascripts
+
+Same with javascripts, just what you normally have in ``public/javascripts`` just in this theme directory instead.
+
+### Readme
+
+The ``README`` file is just a description of your theme.
+
+### Views
+
+This is exactly the same as how you lay your views out in app/views/ just instead of putting them in ``app/views/`` you put them into ``themes/mytheme/views/``
+
+### Preview Image
+
+The ``preview.png`` image is used when selecting the theme in the backend. It must be a png and ideally is 135x135 pixels.
+
+## How do I make my own theme?
+
+Create a folder with the name if your theme inside ``/themes`` e.g. ``/themes/mytheme`` and follow the directory structure outlined in 'The structure of a theme'.
+
+## How do I select which theme Refinery should use?
+
+In the admin area of Refinery go to the "Settings" area, locate the setting called "theme" and edit it.
+
+Set the value of that setting to the name of your themes folder. For example if your theme is sitting in:
+
+    themes/my_theme
+
+set it to ``my_theme`` and hit save.
+
+## How do I zip my theme to use it on other sites
+
+If you want to share a theme and install it on another site you have to zip it first.
+
+It's important to note you don't zip the theme's directory itself just the contents.
+
+If I had a theme sitting in:
+
+    themes/mytheme/[theme files here]
+
+The zip file would look like this
+
+    mytheme.zip
+      |- [theme files here]
+
+Read 'How do I install someone else's theme?' to take that zip file and install the theme.
+
+## How do I install someone else's theme?
+
+If you have the themes plugin added to your admin user, you should see in the admin area of Refinery a "Themes" tab in the main navigation. Click on that, then click "Upload new theme". Upload the theme zip file and then click on the "star" below the preview image for the theme to activate that theme as the one to use right now.
+
+## How can I convert my current views into a theme?
+
+This should be fairly straightforward just following the directory structure outlined in 'The structure of a theme'. 
+
+But there is one important difference that need to be addressed to convert your current site into a theme.
+
+If you have some CSS which refers to an image or URL:
+
+    #footer {
+      background: url('/images/footer_background.png') repeat-x;
+    }
+
+You need to update the URL so it requests /images/themes instead of /images. This tells Refinery we need to actually load this image from the theme and not just the public directory.
+
+So the result is simply:
+
+    #footer {
+      background: url('/images/theme/footer_background.png') repeat-x;
+    }
+
+This is the same with linking to Javascript and Stylesheets in your view. Say our ``application.html.erb`` layout had something like this:
+
+    <%= stylesheet_link_tag 'application' %>
+
+You just need to change that to:
+
+    <%= stylesheet_link_tag 'theme/application' %>