abraham 2.0.0 → 2.2.0
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 +4 -4
- data/README.md +43 -9
- data/Rakefile +1 -1
- data/app/assets/javascripts/abraham/index.js +3 -4
- data/app/controllers/abraham_histories_controller.rb +0 -1
- data/app/helpers/abraham_helper.rb +10 -1
- data/app/views/application/_abraham.html.erb +22 -12
- data/lib/abraham/version.rb +1 -1
- metadata +20 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: d6094c0e5929d5da7e61f12bd1e60a11e450a05e2c3b99afc349b0b7d847edca
|
4
|
+
data.tar.gz: 2b6df2f7d73f7b0c312b13ca3bc5adf16452437f1fd97faea90468093193f5fa
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 978175580bd5132ea570ea0c14421f6ac0def8ca523ce5dfea730c3934c49180c6f9909fd35f161190afddf02aade22c9d447cb74546c419d8cd143e77129d3e
|
7
|
+
data.tar.gz: 9c46128409adfc46ed76abe7f07601d4e5035c63641c13e50b747e51a2e532910326ed77f63f7b2406feb4f5930feb8dbdbe10e5b660f858409f1ce7cf8f186c
|
data/README.md
CHANGED
@@ -15,7 +15,8 @@ Abraham injects dynamically-generated [Shepherd](https://shepherdjs.dev/) JavaSc
|
|
15
15
|
|
16
16
|
## Requirements
|
17
17
|
|
18
|
-
Abraham needs to know the current user to track tour views, e.g. `current_user` from Devise.
|
18
|
+
* Abraham needs to know the current user to track tour views, e.g. `current_user` from Devise.
|
19
|
+
* Abraham is tested on Rails 5.2, 6.0, and 6.1
|
19
20
|
|
20
21
|
## Installation
|
21
22
|
|
@@ -95,7 +96,7 @@ NB: You must specify a locale in the filename, even if you're only supporting on
|
|
95
96
|
|
96
97
|
### Tour content
|
97
98
|
|
98
|
-
A tour is composed of a series of steps. A step may have a title and must have a description. You may attach a step to a particular element on the page, and place the callout
|
99
|
+
A tour is composed of a series of steps. A step may have a title and must have a description. You may attach a step to a particular element on the page, and place the callout in a particular position (see below).
|
99
100
|
|
100
101
|
```yaml
|
101
102
|
intro:
|
@@ -122,6 +123,23 @@ Abraham takes care of which buttons should appear with each step:
|
|
122
123
|
* "Exit" and "Next" buttons on intermediate steps
|
123
124
|
* "Done" button on the last step
|
124
125
|
|
126
|
+
When you specify an `attachTo` element, use the `placement` option to choose where the callout should appear relative to that element:
|
127
|
+
|
128
|
+
* `bottom` / `bottom center`
|
129
|
+
* `bottom left`
|
130
|
+
* `bottom right`
|
131
|
+
* `center` / `middle` / `middle center`
|
132
|
+
* `left` / `middle left'
|
133
|
+
* `right` / `middle right`
|
134
|
+
* `top` / `top center`
|
135
|
+
* `top left`
|
136
|
+
* `top right`
|
137
|
+
|
138
|
+
Abraham tries to be helpful when your tour steps attach to page elements that are missing:
|
139
|
+
|
140
|
+
* If your first step is attached to a particular element, and that element is not present on the page, the tour won't start. ([#28](https://github.com/actmd/abraham/issues/28))
|
141
|
+
* If your tour has an intermediate step attached to a missing element, Abraham will skip that step and automatically show the next. ([#6](https://github.com/actmd/abraham/issues/6))
|
142
|
+
|
125
143
|
### Testing your tours
|
126
144
|
|
127
145
|
Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.
|
@@ -134,6 +152,10 @@ Rails.application.configure do
|
|
134
152
|
end
|
135
153
|
```
|
136
154
|
|
155
|
+
## Full example
|
156
|
+
|
157
|
+
We provide a [small example app](https://github.com/actmd/abraham-example) that implements abraham, so you can see it in action.
|
158
|
+
|
137
159
|
## Upgrading from version 1
|
138
160
|
|
139
161
|
Abraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 -- quite a jump, yes.
|
@@ -144,11 +166,7 @@ If you were using Abraham v1, you'll want to take the following steps to upgrade
|
|
144
166
|
1. Fix your yarn dependencies to use the right versions
|
145
167
|
1. Shepherd no longer provides a set of themes. Abraham maintains two of the legacy themes: default and dark. You'll want to choose one of those or migrate your theme to the new Shepherd structure.
|
146
168
|
1. Abraham now exposes the entire Shepherd configuration object, so your `abraham.yml` file should now fully define the `tour_options` value instead of `default_theme`
|
147
|
-
1. There's been a slight change to `initializers/abraham.rb`.
|
148
|
-
|
149
|
-
```rb
|
150
|
-
config.abraham.tour_options = abraham_config[:tour_options]
|
151
|
-
```
|
169
|
+
1. There's been a slight change to `initializers/abraham.rb`. Replace yours with [the latest](https://github.com/actmd/abraham/blob/master/lib/generators/abraham/templates/initializer.rb).
|
152
170
|
|
153
171
|
If you have any trouble at all, please [submit an issue](https://github.com/actmd/abraham/issues) for assistance!
|
154
172
|
|
@@ -156,10 +174,26 @@ If you have any trouble at all, please [submit an issue](https://github.com/actm
|
|
156
174
|
|
157
175
|
Contributions are welcome!
|
158
176
|
|
159
|
-
Create a feature branch (using git-flow) and submit as a pull request.
|
177
|
+
Create a feature branch (using git-flow) and submit as a pull request (with a base branch of `develop`).
|
160
178
|
|
161
179
|
Everyone interacting in Abraham's codebase, issue tracker, etc. is expected to follow the [Contributor Covenent Code of Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct).
|
162
180
|
|
181
|
+
### Getting started with the source code
|
182
|
+
|
183
|
+
Abraham uses `rvm` with a gemset to ensure the appropriate version of Ruby and its dependencies. Make sure that's installed before you get started.
|
184
|
+
|
185
|
+
```
|
186
|
+
~ git clone git@github.com:actmd/abraham.git
|
187
|
+
Cloning into 'abraham'...
|
188
|
+
~ cd abraham
|
189
|
+
ruby-2.5.3 - #gemset created /Users/jon/.rvm/gems/ruby-2.5.3@abraham
|
190
|
+
ruby-2.5.3 - #generating abraham wrappers - please wait
|
191
|
+
~ bundle install
|
192
|
+
Bundle complete! 13 Gemfile dependencies, 73 gems now installed.
|
193
|
+
Use `bundle info [gemname]` to see where a bundled gem is installed.
|
194
|
+
~ yarn install
|
195
|
+
```
|
196
|
+
|
163
197
|
### Testing
|
164
198
|
|
165
199
|
#### Testing locally
|
@@ -178,7 +212,7 @@ gem 'abraham', path: '~/Workspace/abraham'
|
|
178
212
|
|
179
213
|
#### Automated testing
|
180
214
|
|
181
|
-
We use TravisCI to automatically test this engine with Rails 5.
|
215
|
+
We use TravisCI to automatically test this engine with Rails 5.2, 6.0, and 6.1. For test history, venture over to [TravisCI](https://travis-ci.com/actmd/abraham).
|
182
216
|
|
183
217
|
### Releasing
|
184
218
|
|
data/Rakefile
CHANGED
@@ -1,8 +1,7 @@
|
|
1
|
-
//= require jquery
|
2
1
|
//= require js-cookie/src/js.cookie
|
3
2
|
//= require shepherd.js/dist/js/shepherd
|
4
3
|
|
5
|
-
|
6
|
-
|
7
|
-
|
4
|
+
document.addEventListener('turbolinks:before-cache', function() {
|
5
|
+
// Remove visible product tours
|
6
|
+
document.querySelectorAll(".shepherd-element").forEach(function(el) { el.remove() });
|
8
7
|
});
|
@@ -15,7 +15,6 @@ class AbrahamHistoriesController < ApplicationController
|
|
15
15
|
|
16
16
|
private
|
17
17
|
|
18
|
-
# Never trust parameters from the scary internet, only allow the white list through.
|
19
18
|
def abraham_history_params
|
20
19
|
params.require(:abraham_history).permit(:controller_name, :action_name, :tour_name)
|
21
20
|
end
|
@@ -25,9 +25,18 @@ module AbrahamHelper
|
|
25
25
|
end
|
26
26
|
|
27
27
|
def abraham_cookie_prefix
|
28
|
-
"abraham-#{
|
28
|
+
"abraham-#{fetch_application_name.to_s.underscore}-#{current_user.id}-#{controller_name}-#{action_name}"
|
29
29
|
end
|
30
30
|
|
31
|
+
def fetch_application_name
|
32
|
+
if Module.method_defined?(:module_parent)
|
33
|
+
Rails.application.class.module_parent
|
34
|
+
else
|
35
|
+
Rails.application.class.parent
|
36
|
+
end
|
37
|
+
end
|
38
|
+
|
39
|
+
|
31
40
|
def abraham_domain
|
32
41
|
request.host
|
33
42
|
end
|
@@ -1,14 +1,12 @@
|
|
1
1
|
<script>
|
2
|
-
|
2
|
+
var tour = new Shepherd.Tour(<%= Rails.configuration.abraham.tour_options.html_safe unless Rails.configuration.abraham.tour_options.nil? %>);
|
3
3
|
|
4
4
|
tour.on("complete", function() {
|
5
|
-
//
|
6
|
-
return
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
contentType: "application/json",
|
11
|
-
data: JSON.stringify({
|
5
|
+
// Make AJAX call to save history of tour completion
|
6
|
+
return fetch("/abraham_histories/", {
|
7
|
+
method: "POST",
|
8
|
+
headers: { 'Content-Type': 'application/json' },
|
9
|
+
body: JSON.stringify({
|
12
10
|
authenticity_token: '<%= form_authenticity_token %>',
|
13
11
|
controller_name: '<%= controller_name %>',
|
14
12
|
action_name: '<%= action_name %>',
|
@@ -51,8 +49,20 @@
|
|
51
49
|
});
|
52
50
|
<% end %>
|
53
51
|
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
52
|
+
tour.start = function (start) {
|
53
|
+
return function () {
|
54
|
+
// Don't start the tour if the user dismissed it once this session
|
55
|
+
var tourMayStart = !Cookies.get('<%= abraham_cookie_prefix %>-<%= tour_name %>', {domain: '<%= abraham_domain %>'});
|
56
|
+
<% if steps.first[1]['attachTo'] %>
|
57
|
+
// Don't start the tour if the first step's element is missing
|
58
|
+
tourMayStart = tourMayStart && document.querySelector("<%= steps.first[1]['attachTo']['element'] %>");
|
59
|
+
<% end %>
|
60
|
+
|
61
|
+
if (tourMayStart) {
|
62
|
+
start();
|
63
|
+
}
|
64
|
+
}
|
65
|
+
}(tour.start)
|
66
|
+
|
67
|
+
tour.start()
|
58
68
|
</script>
|
data/lib/abraham/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: abraham
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 2.
|
4
|
+
version: 2.2.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Jonathan Abbett
|
8
|
-
autorequire:
|
8
|
+
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2021-04-15 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: sassc-rails
|
@@ -66,6 +66,20 @@ dependencies:
|
|
66
66
|
- - ">="
|
67
67
|
- !ruby/object:Gem::Version
|
68
68
|
version: '0'
|
69
|
+
- !ruby/object:Gem::Dependency
|
70
|
+
name: web-console
|
71
|
+
requirement: !ruby/object:Gem::Requirement
|
72
|
+
requirements:
|
73
|
+
- - ">="
|
74
|
+
- !ruby/object:Gem::Version
|
75
|
+
version: '0'
|
76
|
+
type: :development
|
77
|
+
prerelease: false
|
78
|
+
version_requirements: !ruby/object:Gem::Requirement
|
79
|
+
requirements:
|
80
|
+
- - ">="
|
81
|
+
- !ruby/object:Gem::Version
|
82
|
+
version: '0'
|
69
83
|
description: Trackable application tours for Rails with i18n support, based on Shepherd.js.
|
70
84
|
email:
|
71
85
|
- jonathan@act.md
|
@@ -101,7 +115,7 @@ homepage: https://github.com/actmd/abraham
|
|
101
115
|
licenses:
|
102
116
|
- MIT
|
103
117
|
metadata: {}
|
104
|
-
post_install_message:
|
118
|
+
post_install_message:
|
105
119
|
rdoc_options: []
|
106
120
|
require_paths:
|
107
121
|
- lib
|
@@ -116,8 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
116
130
|
- !ruby/object:Gem::Version
|
117
131
|
version: '0'
|
118
132
|
requirements: []
|
119
|
-
rubygems_version: 3.0.
|
120
|
-
signing_key:
|
133
|
+
rubygems_version: 3.0.8
|
134
|
+
signing_key:
|
121
135
|
specification_version: 4
|
122
136
|
summary: Trackable application tours for Rails with i18n support, based on Shepherd.js.
|
123
137
|
test_files: []
|