pistaa 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 0b7239fd73ce7ca80d1474305f70792790664cb3
4
+ data.tar.gz: d05b4023c36ce5a1e7fbda6f6bb8ebba4bb2a698
5
+ SHA512:
6
+ metadata.gz: 2eb36ef4ea922e0d65e4ca7f4421e3a12be64e8d9f8ef5fffc887a3745bade86ae927d91a0acb336c69fc0129e5effa93d4185fdd138b9b9dbd7c5b4cbcaea53
7
+ data.tar.gz: b6a0abdef259f6d165e74f7c0d9e3c64c12df900e053687de20fd027ec70003ca788a95d7c848fb5fafde93a98f707fc0f3b276acc94223cea5b4d34f9569f2b
data/MIT-LICENSE ADDED
@@ -0,0 +1,20 @@
1
+ Copyright 2015 Rolf van de Krol
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,87 @@
1
+ # Pistaa
2
+
3
+ Simple structure for Ruby on Rails that allows templates for engines to accept
4
+ injected content from other engines.
5
+
6
+ Suppose you are creating a modular product that consists of a main engine and
7
+ some engines that can be used to extend the main engine. When some of the
8
+ optional engines are enabled, you probably want to alter a template in the main
9
+ engine, to show functionality that is included in one of the optional engines.
10
+ But if you change the main engine to cater the needs of all optional engine, the
11
+ main engine becomes a spaghetti of code for the optional engines.
12
+
13
+ Pistaa provides another solution to this problem. It allows you to define
14
+ *slots* where other engines can inject *partials* so your main engine only has
15
+ to call Pistaa to render a slot and automatically all injected partials will be
16
+ rendered.
17
+
18
+ ## Usage
19
+
20
+ Add Pistaa to the `gemspec` of your main engine.
21
+
22
+ ```ruby
23
+ s.add_dependency "pistaa"
24
+ ```
25
+
26
+ Change a template in the main engine to render a *slot* where other engines can
27
+ inject *partials*. So let's change `news/show.html.erb`.
28
+
29
+ ```erb
30
+ <%= render_pistaa_slot :news_body %>
31
+ ```
32
+
33
+ Then, in one of the optional engines, register a *partial* in the *slot*.
34
+
35
+ ```ruby
36
+ module MyEngine
37
+ class Engine < ::Rails::Engine
38
+ def self.activate
39
+ Pistaa[:news_body][:my_engine_content] = 'my_engine/news/my_engine_content'
40
+ end
41
+
42
+ config.to_prepare &method(:activate).to_proc
43
+ end
44
+ end
45
+ ```
46
+
47
+ And make sure the template `my_engine/news/_my_engine_content.html.erb` exists.
48
+ This will be rendered just like any other partial, so you can use all the
49
+ instance variables that are available to the template in the main engine.
50
+
51
+ Because Pistaa does not hijack the rendering logic in any way (it only provides
52
+ simple helpers that loop over the *partials* in a *slot* and calls
53
+ `render partial: 'path/to/partial'` for each partial), all functionality that
54
+ Rails uses for rendering views is still available. So you can render other
55
+ partials for the injected partial, you can use any template language you like
56
+ and you can even call Pistaa again from the injected partial.
57
+
58
+ Because it essentially is simple partial rendering, overriding templates also
59
+ works as expected. So if the application that uses both the main engine and
60
+ MyEngine defines `my_engine/news/_my_engine_content.html.erb`, it will override
61
+ the template from MyEngine.
62
+
63
+ If the main application overrides the template `news/show.html.erb`, Pistaa
64
+ exposes some helpers that allow the overriding template to control the order of
65
+ the partials in the slot. Check `app/helpers/pistaa_helper.rb` for more
66
+ information. Smart combination of `render_pistaa_slot`,
67
+ `render_pistaa_slot_item` and `hide_pistaa_slot_item` will probably serve your
68
+ needs.
69
+
70
+ ## Inspiration
71
+
72
+ I'm aware of one other project that tries to solve this problem, but in a
73
+ completely different way. [Deface](https://github.com/spree/deface is tool that
74
+ was used in older versions of [Spree](https://spreecommerce.com/) and also
75
+ provides a way to alter templates from engines. It parses ERB templates to an
76
+ XML structure using Nokogiri, exposes a DSL to manipulate the Nokogiri document
77
+ and renders the document back to ERB. Although it works, it is quite error
78
+ prone. Currently, it's stable versions only support Rails 3.
79
+
80
+ The way `hide_pistaa_slot_item`, `render_pistaa_slot_item` and
81
+ `render_pistaa_slot` work, is inspired by [Drupal](https://drupal.org/)'s render
82
+ arrays.
83
+
84
+ ## Roadmap
85
+
86
+ The first thing that will be added to this gem, is a way to control the order
87
+ of the partials from the engines.
data/Rakefile ADDED
@@ -0,0 +1,37 @@
1
+ begin
2
+ require 'bundler/setup'
3
+ rescue LoadError
4
+ puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
5
+ end
6
+
7
+ require 'rdoc/task'
8
+
9
+ RDoc::Task.new(:rdoc) do |rdoc|
10
+ rdoc.rdoc_dir = 'rdoc'
11
+ rdoc.title = 'Pistaa'
12
+ rdoc.options << '--line-numbers'
13
+ rdoc.rdoc_files.include('README.rdoc')
14
+ rdoc.rdoc_files.include('lib/**/*.rb')
15
+ end
16
+
17
+ APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
18
+ load 'rails/tasks/engine.rake'
19
+
20
+
21
+ load 'rails/tasks/statistics.rake'
22
+
23
+
24
+
25
+ Bundler::GemHelper.install_tasks
26
+
27
+ require 'rake/testtask'
28
+
29
+ Rake::TestTask.new(:test) do |t|
30
+ t.libs << 'lib'
31
+ t.libs << 'test'
32
+ t.pattern = 'test/**/*_test.rb'
33
+ t.verbose = false
34
+ end
35
+
36
+
37
+ task default: :test
@@ -0,0 +1,44 @@
1
+ module PistaaHelper
2
+
3
+ # Render all templates in the slot, but skip the items that are registered as
4
+ # hidden. It repeatedly calls `render_pistaa_slot_item`, so the rendered
5
+ # templates will be registered as hidden.
6
+ def render_pistaa_slot(slot)
7
+ pistaa_slot_items(slot).map do |item|
8
+ next if pistaa_slot_item_hidden?(slot, item)
9
+
10
+ render_pistaa_slot_item(slot, item)
11
+ end.join("\n").html_safe
12
+ end
13
+
14
+ # Render a specific template from a slot (regardless of it was hidden), and
15
+ # register it as hidden, so it won't be rendered if `render_pistaa_slot` is
16
+ # called.
17
+ def render_pistaa_slot_item(slot, item)
18
+ hide_pistaa_slot_item(slot, item)
19
+ render partial: Pistaa[slot][item]
20
+ end
21
+
22
+ # List all the keys of the items in the slot.
23
+ def pistaa_slot_items(slot)
24
+ Pistaa[slot].item_keys
25
+ end
26
+
27
+ # Helper to access the hidden items. You shouldn't need to access this helper
28
+ # from the template. Use `pistaa_slot_item_hidden?` and
29
+ #{ }`hide_pistaa_slot_item` instead.
30
+ def pistaa_hidden_items
31
+ @pistaa_hidden_items ||= []
32
+ end
33
+
34
+ # Register a template as hidden, so it won't be rendered with
35
+ # `render_pistaa_slot`.
36
+ def hide_pistaa_slot_item(slot, item)
37
+ pistaa_hidden_items << [slot, item]
38
+ end
39
+
40
+ # Check if a template is hidden.
41
+ def pistaa_slot_item_hidden?(slot, item)
42
+ pistaa_hidden_items.include? [slot, item]
43
+ end
44
+ end
data/config/routes.rb ADDED
@@ -0,0 +1,2 @@
1
+ Rails.application.routes.draw do
2
+ end
data/lib/pistaa.rb ADDED
@@ -0,0 +1,42 @@
1
+ require "pistaa/engine"
2
+
3
+ module Pistaa
4
+ class << self
5
+ def [](slot_key)
6
+ slots[slot_key]
7
+ end
8
+
9
+ def slot_keys
10
+ slots.keys
11
+ end
12
+
13
+ protected
14
+
15
+ def slots
16
+ @slots ||= Hash.new do |hash, key|
17
+ hash[key] = Pistaa::Slot.new
18
+ end
19
+ end
20
+ end
21
+
22
+ class Slot
23
+ def [](item_key)
24
+ raise IndexError if items[item_key.to_sym].nil?
25
+ items[item_key.to_sym]
26
+ end
27
+
28
+ def []=(item_key, template)
29
+ items[item_key.to_sym] = template
30
+ end
31
+
32
+ def item_keys
33
+ items.keys
34
+ end
35
+
36
+ protected
37
+
38
+ def items
39
+ @items ||= Hash.new
40
+ end
41
+ end
42
+ end
@@ -0,0 +1,4 @@
1
+ module Pistaa
2
+ class Engine < ::Rails::Engine
3
+ end
4
+ end
@@ -0,0 +1,3 @@
1
+ module Pistaa
2
+ VERSION = "0.0.1"
3
+ end
@@ -0,0 +1,4 @@
1
+ # desc "Explaining what the task does"
2
+ # task :pistaa do
3
+ # # Task goes here
4
+ # end
metadata ADDED
@@ -0,0 +1,67 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: pistaa
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.1
5
+ platform: ruby
6
+ authors:
7
+ - Rolf van de Krol
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2015-12-23 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: rails
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - "~>"
18
+ - !ruby/object:Gem::Version
19
+ version: 4.2.5
20
+ type: :runtime
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - "~>"
25
+ - !ruby/object:Gem::Version
26
+ version: 4.2.5
27
+ description: Simple structure that allows extending templates from engines.
28
+ email:
29
+ - info@rolfvandekrol.nl
30
+ executables: []
31
+ extensions: []
32
+ extra_rdoc_files: []
33
+ files:
34
+ - MIT-LICENSE
35
+ - README.md
36
+ - Rakefile
37
+ - app/helpers/pistaa_helper.rb
38
+ - config/routes.rb
39
+ - lib/pistaa.rb
40
+ - lib/pistaa/engine.rb
41
+ - lib/pistaa/version.rb
42
+ - lib/tasks/pistaa_tasks.rake
43
+ homepage: https://github.com/rolfvandekrol/pistaa
44
+ licenses:
45
+ - MIT
46
+ metadata: {}
47
+ post_install_message:
48
+ rdoc_options: []
49
+ require_paths:
50
+ - lib
51
+ required_ruby_version: !ruby/object:Gem::Requirement
52
+ requirements:
53
+ - - ">="
54
+ - !ruby/object:Gem::Version
55
+ version: '0'
56
+ required_rubygems_version: !ruby/object:Gem::Requirement
57
+ requirements:
58
+ - - ">="
59
+ - !ruby/object:Gem::Version
60
+ version: '0'
61
+ requirements: []
62
+ rubyforge_project:
63
+ rubygems_version: 2.4.5.1
64
+ signing_key:
65
+ specification_version: 4
66
+ summary: Template extension helper
67
+ test_files: []