pistaa 0.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/MIT-LICENSE +20 -0
- data/README.md +87 -0
- data/Rakefile +37 -0
- data/app/helpers/pistaa_helper.rb +44 -0
- data/config/routes.rb +2 -0
- data/lib/pistaa.rb +42 -0
- data/lib/pistaa/engine.rb +4 -0
- data/lib/pistaa/version.rb +3 -0
- data/lib/tasks/pistaa_tasks.rake +4 -0
- metadata +67 -0
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
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
|
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: []
|