abraham 2.0.2 → 2.3.0.beta
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +83 -12
- data/Rakefile +1 -1
- data/app/assets/javascripts/abraham/index.js +24 -4
- data/app/controllers/abraham_histories_controller.rb +0 -1
- data/app/helpers/abraham_helper.rb +25 -8
- data/app/views/application/_abraham.html.erb +41 -24
- data/lib/abraham/version.rb +1 -1
- metadata +22 -8
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 5872e5ab9e3d24a4133de7b4127934eba2b36688eac51eb4f29bfdd9c7a0f1ff
|
4
|
+
data.tar.gz: ead10365b2cdf82e9f9e49f7ee55d9525731093b0b1b6faafe720b789766c977
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 810d59a5b7d8f35d787d65fec4e42c46cb27edc7228272aa337adb31ddf9a4f35167610046f99861af51ccd0a65dea2bd77d32ac41f8fd07ed5f349516faa8b4
|
7
|
+
data.tar.gz: bfe6c59e405805b0e98938480037fc5a2c40ef4ae965558060ac4767cbc522890b131f634a190847b92d759b9facd7ba472d4f67b8a0b32eb183f660164f7487
|
data/README.md
CHANGED
@@ -6,16 +6,18 @@ _Guide your users in the one true path._
|
|
6
6
|
|
7
7
|
![Watercolor Sheep](https://upload.wikimedia.org/wikipedia/commons/e/e4/Watercolor_Sheep_Drawing.jpg)
|
8
8
|
|
9
|
-
Abraham
|
9
|
+
Abraham makes it easy to show guided tours to users of your Rails application. When Abraham shows a tour, it keeps track of whether the user has completed it (so it doesn't get shown again) or dismissed it for later (so it reappears in a future user session).
|
10
10
|
|
11
11
|
* Define tour content with simple YAML files, in any/many languages.
|
12
12
|
* Organize tours by controller and action.
|
13
|
-
*
|
14
|
-
*
|
13
|
+
* Trigger tours automatically on page load or manually via JavaScript method.
|
14
|
+
* Built with the [Shepherd JS](https://shepherdjs.dev/) library. Plays nicely with Turbolinks.
|
15
|
+
* Ships with two basic CSS themes (default & dark) — or write your own
|
15
16
|
|
16
17
|
## Requirements
|
17
18
|
|
18
|
-
Abraham needs to know the current user to track tour views, e.g. `current_user` from Devise.
|
19
|
+
* Abraham needs to know the current user to track tour views, e.g. `current_user` from Devise.
|
20
|
+
* Abraham is tested on Rails 5.2, 6.0, and 6.1
|
19
21
|
|
20
22
|
## Installation
|
21
23
|
|
@@ -37,7 +39,7 @@ $ rails db:migrate
|
|
37
39
|
Install the JavaScript dependencies:
|
38
40
|
|
39
41
|
```
|
40
|
-
$ yarn add
|
42
|
+
$ yarn add js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
|
41
43
|
```
|
42
44
|
|
43
45
|
Require `abraham` in `app/assets/javascripts/application.js`
|
@@ -76,7 +78,7 @@ Tell Abraham where to insert its generated JavaScript in `app/views/layouts/appl
|
|
76
78
|
|
77
79
|
## Defining your tours
|
78
80
|
|
79
|
-
Define your tours in the `config/tours` directory. Its directory structure
|
81
|
+
Define your tours in the `config/tours` directory corresponding to the views defined in your application. Its directory structure mirrors your application's controllers, and the tour files mirror your actions/views.
|
80
82
|
|
81
83
|
```
|
82
84
|
config/
|
@@ -91,11 +93,15 @@ config/
|
|
91
93
|
└── show.es.yml
|
92
94
|
```
|
93
95
|
|
94
|
-
|
96
|
+
For example, per above, when a Spanish-speaking user visits `/articles/`, they'll see the tours defined by `config/tours/articles/index.es.yml`.
|
97
|
+
|
98
|
+
(Note: You must specify a locale in the filename, even if you're only supporting one language.)
|
95
99
|
|
96
100
|
### Tour content
|
97
101
|
|
98
|
-
|
102
|
+
Within a tour file, each tour is composed of a series of **steps**. A step may have a `title` and must have `text`. You may attach a step to a particular element on the page, and place the callout in a particular position.
|
103
|
+
|
104
|
+
In this example, we define a tour called "intro" with 3 steps:
|
99
105
|
|
100
106
|
```yaml
|
101
107
|
intro:
|
@@ -122,6 +128,55 @@ Abraham takes care of which buttons should appear with each step:
|
|
122
128
|
* "Exit" and "Next" buttons on intermediate steps
|
123
129
|
* "Done" button on the last step
|
124
130
|
|
131
|
+
When you specify an `attachTo` element, use the `placement` option to choose where the callout should appear relative to that element:
|
132
|
+
|
133
|
+
* `bottom` / `bottom center`
|
134
|
+
* `bottom left`
|
135
|
+
* `bottom right`
|
136
|
+
* `center` / `middle` / `middle center`
|
137
|
+
* `left` / `middle left`
|
138
|
+
* `right` / `middle right`
|
139
|
+
* `top` / `top center`
|
140
|
+
* `top left`
|
141
|
+
* `top right`
|
142
|
+
|
143
|
+
Abraham tries to be helpful when your tour steps attach to page elements that are missing:
|
144
|
+
|
145
|
+
* 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))
|
146
|
+
* 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))
|
147
|
+
|
148
|
+
### Automatic vs. manual tours
|
149
|
+
|
150
|
+
By default, Abraham will automatically start a tour that the current user hasn't seen yet. You can instead define a tour to be triggered manually using the `trigger` option:
|
151
|
+
|
152
|
+
```yml
|
153
|
+
walkthrough:
|
154
|
+
trigger: "manual"
|
155
|
+
steps:
|
156
|
+
1:
|
157
|
+
text: "This walkthrough will show you how to..."
|
158
|
+
```
|
159
|
+
|
160
|
+
This tour will not start automatically; instead, use the `Abraham.startTour` method with the tour name:
|
161
|
+
|
162
|
+
```
|
163
|
+
<button id="startTour">Start tour</button>
|
164
|
+
|
165
|
+
<script>
|
166
|
+
document.querySelector("#startTour").addEventListener("click", function() {
|
167
|
+
Abraham.startTour("walkthrough"));
|
168
|
+
});
|
169
|
+
</script>
|
170
|
+
```
|
171
|
+
|
172
|
+
...or if you happen to use jQuery:
|
173
|
+
|
174
|
+
```
|
175
|
+
<script>
|
176
|
+
$("#startTour").on("click", function() { Abraham.startTour('walkthrough'); })
|
177
|
+
</script>
|
178
|
+
```
|
179
|
+
|
125
180
|
### Testing your tours
|
126
181
|
|
127
182
|
Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.
|
@@ -136,11 +191,11 @@ end
|
|
136
191
|
|
137
192
|
## Full example
|
138
193
|
|
139
|
-
We provide a [small example app](https://github.com/actmd/abraham-example) that implements
|
194
|
+
We provide a [small example app](https://github.com/actmd/abraham-example) that implements Abraham, so you can see it in action.
|
140
195
|
|
141
196
|
## Upgrading from version 1
|
142
197
|
|
143
|
-
Abraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6
|
198
|
+
Abraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 – quite a jump, yes.
|
144
199
|
|
145
200
|
If you were using Abraham v1, you'll want to take the following steps to upgrade:
|
146
201
|
|
@@ -156,10 +211,26 @@ If you have any trouble at all, please [submit an issue](https://github.com/actm
|
|
156
211
|
|
157
212
|
Contributions are welcome!
|
158
213
|
|
159
|
-
Create a feature branch (using git-flow) and submit as a pull request.
|
214
|
+
Create a feature branch (using git-flow) and submit as a pull request (with a base branch of `develop`).
|
160
215
|
|
161
216
|
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
217
|
|
218
|
+
### Getting started with the source code
|
219
|
+
|
220
|
+
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.
|
221
|
+
|
222
|
+
```
|
223
|
+
~ git clone git@github.com:actmd/abraham.git
|
224
|
+
Cloning into 'abraham'...
|
225
|
+
~ cd abraham
|
226
|
+
ruby-2.5.3 - #gemset created /Users/jon/.rvm/gems/ruby-2.5.3@abraham
|
227
|
+
ruby-2.5.3 - #generating abraham wrappers - please wait
|
228
|
+
~ bundle install
|
229
|
+
Bundle complete! 13 Gemfile dependencies, 73 gems now installed.
|
230
|
+
Use `bundle info [gemname]` to see where a bundled gem is installed.
|
231
|
+
~ yarn install
|
232
|
+
```
|
233
|
+
|
163
234
|
### Testing
|
164
235
|
|
165
236
|
#### Testing locally
|
@@ -178,7 +249,7 @@ gem 'abraham', path: '~/Workspace/abraham'
|
|
178
249
|
|
179
250
|
#### Automated testing
|
180
251
|
|
181
|
-
We use TravisCI to automatically test this engine with Rails 5.
|
252
|
+
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
253
|
|
183
254
|
### Releasing
|
184
255
|
|
data/Rakefile
CHANGED
@@ -1,8 +1,28 @@
|
|
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
|
+
var Abraham = new Object();
|
5
|
+
|
6
|
+
Abraham.tours = {};
|
7
|
+
Abraham.incompleteTours = [];
|
8
|
+
Abraham.startTour = function(tourName) {
|
9
|
+
if (!Shepherd.activeTour) {
|
10
|
+
Abraham.tours[tourName].start();
|
11
|
+
}
|
12
|
+
};
|
13
|
+
Abraham.startNextIncompleteTour = function() {
|
14
|
+
if (Abraham.incompleteTours.length) {
|
15
|
+
Abraham.tours[Abraham.incompleteTours[0]].checkAndStart();
|
16
|
+
}
|
17
|
+
};
|
18
|
+
|
19
|
+
document.addEventListener("DOMContentLoaded", Abraham.startNextIncompleteTour);
|
20
|
+
document.addEventListener("turbolinks:load", Abraham.startNextIncompleteTour);
|
21
|
+
|
22
|
+
document.addEventListener('turbolinks:before-cache', function() {
|
23
|
+
// Remove visible product tours
|
24
|
+
document.querySelectorAll(".shepherd-element").forEach(function(el) { el.remove() });
|
25
|
+
// Clear Abraham data
|
26
|
+
Abraham.tours = {};
|
27
|
+
Abraham.incompleteTours = [];
|
8
28
|
});
|
@@ -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
|
@@ -4,30 +4,47 @@ module AbrahamHelper
|
|
4
4
|
def abraham_tour
|
5
5
|
# Do we have tours for this controller/action in the user's locale?
|
6
6
|
tours = Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.locale}"]
|
7
|
-
|
7
|
+
# Otherwise, default to the default locale
|
8
8
|
tours ||= Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.default_locale}"]
|
9
9
|
|
10
10
|
if tours
|
11
|
+
# Have any automatic tours been completed already?
|
11
12
|
completed = AbrahamHistory.where(
|
12
13
|
creator_id: current_user.id,
|
13
14
|
controller_name: controller_name,
|
14
15
|
action_name: action_name
|
15
16
|
)
|
16
|
-
remaining = tours.keys - completed.map(&:tour_name)
|
17
17
|
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
18
|
+
tour_keys_completed = completed.map(&:tour_name)
|
19
|
+
tour_keys = tours.keys
|
20
|
+
|
21
|
+
tour_html = ''
|
22
|
+
|
23
|
+
tour_keys.each do |key|
|
24
|
+
tour_html += render(partial: "application/abraham",
|
25
|
+
locals: { tour_name: key,
|
26
|
+
tour_completed: tour_keys_completed.include?(key),
|
27
|
+
trigger: tours[key]["trigger"],
|
28
|
+
steps: tours[key]["steps"] })
|
23
29
|
end
|
30
|
+
|
31
|
+
tour_html.html_safe
|
24
32
|
end
|
25
33
|
end
|
26
34
|
|
27
35
|
def abraham_cookie_prefix
|
28
|
-
"abraham-#{
|
36
|
+
"abraham-#{fetch_application_name.to_s.underscore}-#{current_user.id}-#{controller_name}-#{action_name}"
|
29
37
|
end
|
30
38
|
|
39
|
+
def fetch_application_name
|
40
|
+
if Module.method_defined?(:module_parent)
|
41
|
+
Rails.application.class.module_parent
|
42
|
+
else
|
43
|
+
Rails.application.class.parent
|
44
|
+
end
|
45
|
+
end
|
46
|
+
|
47
|
+
|
31
48
|
def abraham_domain
|
32
49
|
request.host
|
33
50
|
end
|
@@ -1,14 +1,13 @@
|
|
1
1
|
<script>
|
2
|
-
|
2
|
+
Abraham.tours["<%= tour_name %>"] = new Shepherd.Tour(<%= Rails.configuration.abraham.tour_options.html_safe unless Rails.configuration.abraham.tour_options.nil? %>);
|
3
3
|
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
data: JSON.stringify({
|
4
|
+
<% if trigger != 'manual' %>
|
5
|
+
Abraham.tours["<%= tour_name %>"].on("complete", function() {
|
6
|
+
// Make AJAX call to save history of tour completion
|
7
|
+
return fetch("/abraham_histories/", {
|
8
|
+
method: "POST",
|
9
|
+
headers: { 'Content-Type': 'application/json' },
|
10
|
+
body: JSON.stringify({
|
12
11
|
authenticity_token: '<%= form_authenticity_token %>',
|
13
12
|
controller_name: '<%= controller_name %>',
|
14
13
|
action_name: '<%= action_name %>',
|
@@ -17,12 +16,13 @@
|
|
17
16
|
});
|
18
17
|
});
|
19
18
|
|
20
|
-
|
19
|
+
Abraham.tours["<%= tour_name %>"].on("cancel", function() {
|
21
20
|
Cookies.set('<%= abraham_cookie_prefix %>-<%= tour_name %>', 'later', { domain: '<%= abraham_domain %>' });
|
22
21
|
});
|
22
|
+
<% end %>
|
23
23
|
|
24
24
|
<% steps.each_with_index do |(key, step), index| %>
|
25
|
-
|
25
|
+
Abraham.tours["<%= tour_name %>"].addStep({
|
26
26
|
id: 'step-<%= key %>',
|
27
27
|
<% if step.key?('title') %>
|
28
28
|
title: "<%= step['title'] %>",
|
@@ -36,23 +36,40 @@
|
|
36
36
|
},
|
37
37
|
<% end %>
|
38
38
|
buttons: [
|
39
|
-
<% if index ==
|
40
|
-
{ text: '<%= t('abraham.
|
41
|
-
{ text: '<%= t('abraham.continue') %>', action: tour.next }
|
39
|
+
<% if index == steps.size - 1 %>
|
40
|
+
{ text: '<%= t('abraham.done') %>', action: Abraham.tours["<%= tour_name %>"].complete }
|
42
41
|
<% else %>
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
{ text: '<%= t('abraham.
|
48
|
-
|
42
|
+
<% if index == 0 %>
|
43
|
+
{ text: '<%= t('abraham.later') %>', action: Abraham.tours["<%= tour_name %>"].cancel, classes: 'shepherd-button-secondary' },
|
44
|
+
{ text: '<%= t('abraham.continue') %>', action: Abraham.tours["<%= tour_name %>"].next }
|
45
|
+
<% else %>
|
46
|
+
{ text: '<%= t('abraham.exit') %>', action: Abraham.tours["<%= tour_name %>"].cancel, classes: 'shepherd-button-secondary' },
|
47
|
+
{ text: '<%= t('abraham.next') %>', action: Abraham.tours["<%= tour_name %>"].next }
|
48
|
+
<% end %>
|
49
49
|
<% end %>
|
50
50
|
]
|
51
51
|
});
|
52
52
|
<% end %>
|
53
53
|
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
54
|
+
<% if trigger != "manual" %>
|
55
|
+
Abraham.tours["<%= tour_name %>"].checkAndStart = function (start) {
|
56
|
+
return function () {
|
57
|
+
// Don't start the tour if the user dismissed it once this session
|
58
|
+
var tourMayStart = !Cookies.get('<%= abraham_cookie_prefix %>-<%= tour_name %>', {domain: '<%= abraham_domain %>'});
|
59
|
+
<% if steps.first[1]['attachTo'] %>
|
60
|
+
// Don't start the tour if the first step's element is missing
|
61
|
+
tourMayStart = tourMayStart && document.querySelector("<%= steps.first[1]['attachTo']['element'] %>");
|
62
|
+
<% end %>
|
63
|
+
|
64
|
+
if (tourMayStart) {
|
65
|
+
start();
|
66
|
+
}
|
67
|
+
}
|
68
|
+
}(Abraham.tours["<%= tour_name %>"].start)
|
69
|
+
|
70
|
+
<% if !tour_completed %>
|
71
|
+
Abraham.incompleteTours.push("<%= tour_name %>");
|
72
|
+
<% end %>
|
73
|
+
<% end %>
|
74
|
+
|
58
75
|
</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.0.
|
4
|
+
version: 2.3.0.beta
|
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-21 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
|
@@ -112,12 +126,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
112
126
|
version: '0'
|
113
127
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
114
128
|
requirements:
|
115
|
-
- - "
|
129
|
+
- - ">"
|
116
130
|
- !ruby/object:Gem::Version
|
117
|
-
version:
|
131
|
+
version: 1.3.1
|
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: []
|