diff --git a/doc/guides/4 - Refinery Extensions/9 - Adding an image collection to an extension using PageImages.md b/doc/guides/4 - Refinery Extensions/9 - Adding an image collection to an extension using PageImages.md new file mode 100644 index 0000000000..e2a7f95226 --- /dev/null +++ b/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 %> + +