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 +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: []
|