Merge pull request #3132 from anitagraham/ExtensionImageCollection

Add Guide for adding Image collection to extension

doc/guides/4 - Refinery Extensions/9 - Adding an image collection to an extension using PageImages.md

@@ -0,0 +1,156 @@
+# Adding Multiple Images to your Model
+
+Refinery offers a generator which allows an engine/model to have fields which are single images. It doesn't supply anything out-of-the-box to allow a model to have a collection of images. 
+
+However the extension *Refinerycms-page-images* implements an image collection for the *Refinery::Page* model which can be extended to other models.
+
+*Thanks to [Prokop Simek](:https://github.com/prokopsimek) who detailed this method [here](:https://github.com/refinery/refinerycms-page-images/issues/111).*
+
+## What you get
+
+When you have completed these steps your model/engine you will be able to add and remove images from an instance of your model using the same tabbed interface used by Refinery::Pages.
+
+In a view you will have access to a collection of images (*@model.images*) or a collection of images with associated captions (*@model.images_with_captions*). 
+
+### Pre-requisites
+
+* Refinerycms
+* Refinerycms-page-images
+* an engine or extension to work with (the examples will use `Shows`)
+
+
+##### Configure Refinerycms-page-images
+
+````Ruby
+#app/config/initializers/refinery/page_images.rb
+Refinery::PageImages.configure do |config|
+  config.captions = true
+  config.enable_for = [
+    {model: "Refinery::Page", tab: "Refinery::Pages::Tab"},
+    {model: "Refinery::Show", tab: "Refinery::Shows::Tab"}
+  ]
+  config.wysiwyg = true
+end
+````
+
+#####  Add page-images to your model 
+
+````Ruby
+#vendor/extensions/shows/app/models/refinery/shows/show.rb
+module Refinery
+  module Shows
+    class Show < Refinery::Core::BaseModel
+
+      self.table_name = 'refinery_shows'
+      validates :title, :presence => true, :uniqueness => true
+      has_many_page_images
+    end
+  end
+end
+````
+
+##### Define Tabs
+
+````Ruby
+#vendor/extensions/shows/lib/refinery/shows/tabs.rb
+ module Refinery
+  module Shows
+    class Tab
+      attr_accessor :name, :partial
+
+      def self.register(&block)
+        tab = self.new
+
+        yield tab
+
+        raise "A tab MUST have a name!: #{tab.inspect}" if tab.name.blank?
+        raise "A tab MUST have a partial!: #{tab.inspect}" if tab.partial.blank?
+      end
+
+      protected
+
+        def initialize
+          ::Refinery::Shows.tabs << self # add me to the collection of registered tabs
+        end
+    end
+  end
+ end
+ ````
+
+##### Load and Initialize Tabs
+````Ruby
+# vendor/extensions/shows/lib/refinery/shows.rb
+require 'refinerycms-core'
+module Refinery
+  autoload :ShowsGenerator, 'generators/refinery/shows_generator'
+
+  module Shows
+    require 'refinery/shows/engine'
+
+    autoload :Tab, 'refinery/shows/tabs'
+
+    class << self
+      attr_writer :root
+      attr_writer :tabs
+
+      def root
+        @root ||= Pathname.new(File.expand_path('../../../', __FILE__))
+      end
+
+      def tabs
+        @tabs ||= []
+      end
+
+      def factory_paths
+        @factory_paths ||= [ root.join('spec', 'factories').to_s ]
+      end
+    end
+  end
+end
+````
+
+
+##### Finally modify the admin view
+````Ruby
+# vendor/extensions/shows/app/views/refinery/admin/_form.html.erb
+<%= form_for [refinery, :shows_admin, @show] do |f| -%>
+  <%= render '/refinery/admin/error_messages',
+              :object => @show,
+              :include_object_name => true %>
+
+  <div class='field'>
+    <%= f.label :title -%>
+    <%= f.text_field :title, :class => 'larger widest' -%>
+  </div>
+
+  <div class='field'>
+    <div id='page-tabs' class='clearfix ui-tabs ui-widget ui-widget-content ui-corner-all'>
+      <ul id='page_parts'>
+        <li class='ui-state-default ui-state-active'>
+          <%= link_to 'Blurb', "#page_part_blurb" %>
+        </li>
+        <% Refinery::Shows.tabs.each_with_index do |tab, tab_index| %>
+          <li class='ui-state-default' id="custom_<%= tab.name %>_tab">
+            <%= link_to tab.name.titleize, "#custom_tab_#{tab_index}" %>
+          </li>
+        <% end %>
+      </ul>
+
+      <div id='page_part_editors'>
+        <% part_index = -1 %>
+          <%= render 'form_part', :f => f, :part_index => (part_index += 1) -%>
+        <% Refinery::Shows.tabs.each_with_index do |tab, tab_index| %>
+          <div class='page_part' id='<%= "custom_tab_#{tab_index}" %>'>
+            <%= render tab.partial, :f => f %>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+
+  <%= render '/refinery/admin/form_actions', :f => f,
+             :continue_editing => false,
+             :delete_title => t('delete', :scope => 'refinery.shows.admin.shows.show'),
+             :delete_confirmation => t('message', :scope => 'refinery.admin.delete', :title => @show.title) -%>
+<% end -%>
+````

doc/guides/4 - Refinery Extensions/9 - Adding an image collection to an extension using PageImages.textile

@@ -0,0 +1,155 @@
+h1. Adding Multiple Images to your Model
+
+Refinery offers a generator which allows an engine/model to have fields which are single images. It doesn't supply anything out-of-the-box to allow a model to have a collection of images. 
+
+However Refinery has a plugin "Refinerycms-page-images" which implements an image collection for the Refinery::Page model.
+
+It is relatively straight-forward to use this plugin to add an image collection to your model.
+
+*Thanks to "Prokop Simek":https://github.com/prokopsimek who detailed this method "here":https://github.com/refinery/refinerycms-page-images/issues/111.*
+
+h2. What you get
+
+When you have completed these steps your model/engine you will be able to add and remove images from an instance of your model using the same tabbed interface used by Refinery::Pages.
+
+In a view you will have access to a collection of images ("@model.images") or a collection of images with associated captions ("@model.images_with_captions"). 
+
+h3. Pre-requisites
+
+* Refinerycms
+* Refinerycms-page-images
+* an engine or extension to work with (the examples will use Shows)
+
+
+h5. Configure Refinerycms-page-images
+
+bc..
+# app/config/initializers/refinery/page_images.rb
+Refinery::PageImages.configure do |config|
+  config.captions = true
+  config.enable_for = [
+    {model: "Refinery::Page", tab: "Refinery::Pages::Tab"},
+    {model: "Refinery::Show", tab: "Refinery::Shows::Tab"}
+  ]
+  config.wysiwyg = true
+end
+
+h5.  Add page-images to your model
+
+bc..
+#vendor/extensions/shows/app/models/refinery/shows/show.rb
+module Refinery
+  module Shows
+    class Show < Refinery::Core::BaseModel
+
+      self.table_name = 'refinery_shows'
+      validates :title, :presence => true, :uniqueness => true
+      has_many_page_images
+    end
+  end
+end
+
+h5. Define Tabs
+
+bc..
+# in vendor/extensions/shows/lib/refinery/shows/tabs.rb
+ module Refinery
+  module Shows
+    class Tab
+      attr_accessor :name, :partial
+
+      def self.register(&block)
+        tab = self.new
+
+        yield tab
+
+        raise "A tab MUST have a name!: #{tab.inspect}" if tab.name.blank?
+        raise "A tab MUST have a partial!: #{tab.inspect}" if tab.partial.blank?
+      end
+
+      protected
+
+        def initialize
+          ::Refinery::Shows.tabs << self # add me to the collection of registered tabs
+        end
+    end
+  end
+ end
+
+h5. Load and Initialize Tabs
+# vendor/extensions/shows/lib/refinery/shows.rb
+require 'refinerycms-core'
+
+bc..
+module Refinery
+  autoload :ShowsGenerator, 'generators/refinery/shows_generator'
+
+  module Shows
+    require 'refinery/shows/engine'
+
+    autoload :Tab, 'refinery/shows/tabs'
+
+    class << self
+      attr_writer :root
+      attr_writer :tabs
+
+      def root
+        @root ||= Pathname.new(File.expand_path('../../../', __FILE__))
+      end
+
+      def tabs
+        @tabs ||= []
+      end
+
+      def factory_paths
+        @factory_paths ||= [ root.join('spec', 'factories').to_s ]
+      end
+    end
+  end
+end
+
+
+h5.  Finally modify the admin view
+
+bc..
+#vendor/extensions/shows/app/views/refinery/admin/_form.html.erb
+<%= form_for [refinery, :shows_admin, @show] do |f| -%>
+  <%= render '/refinery/admin/error_messages',
+              :object => @show,
+              :include_object_name => true %>
+
+  <div class='field'>
+    <%= f.label :title -%>
+    <%= f.text_field :title, :class => 'larger widest' -%>
+  </div>
+
+  <div class='field'>
+    <div id='page-tabs' class='clearfix ui-tabs ui-widget ui-widget-content ui-corner-all'>
+      <ul id='page_parts'>
+        <li class='ui-state-default ui-state-active'>
+          <%= link_to 'Blurb', "#page_part_blurb" %>
+        </li>
+        <% Refinery::Shows.tabs.each_with_index do |tab, tab_index| %>
+          <li class='ui-state-default' id="custom_<%= tab.name %>_tab">
+            <%= link_to tab.name.titleize, "#custom_tab_#{tab_index}" %>
+          </li>
+        <% end %>
+      </ul>
+
+      <div id='page_part_editors'>
+        <% part_index = -1 %>
+          <%= render 'form_part', :f => f, :part_index => (part_index += 1) -%>
+        <% Refinery::Shows.tabs.each_with_index do |tab, tab_index| %>
+          <div class='page_part' id='<%= "custom_tab_#{tab_index}" %>'>
+            <%= render tab.partial, :f => f %>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+
+  <%= render '/refinery/admin/form_actions', :f => f,
+             :continue_editing => false,
+             :delete_title => t('delete', :scope => 'refinery.shows.admin.shows.show'),
+             :delete_confirmation => t('message', :scope => 'refinery.admin.delete', :title => @show.title) -%>
+<% end -%>