actmd/abraham

Trackable application tours for Rails with i18n support

abraham's Issues

Rails 5.1 support

Hi @jabbett
Tried out this gem today and blown away (really impressed).
I forked it and changed the rails dependency for it to work with rails 5.1:

See abraham.gemspec line 20.

s.add_dependency 'rails', '~> 5.0', '>= 5.0.0.1'

Include documentation on `placement` options

As suggested by #45, the README lacks detail on all the placement options.

The options look to be enumerated within https://github.com/shipshapecode/shepherd/blob/v6.0.0/src/js/utils/general.js

Let's test in abraham that all of these work and then add to the README.

Uncaught ReferenceError: Shepherd is not defined

After following all the steps in the Readme I got this error in my webapp:
(index):924 Uncaught ReferenceError: Shepherd is not defined
This is my abraham.yml file:

defaults: &defaults
  # Add any valid Shepherd.js configuration JSON here
  # and it will be passed into the `new Shepherd.Tour()`
  # initializer.
  :tour_options: '{ defaultStepOptions: { classes: "theme-default" } }'

development:
  <<: *defaults

test:
  <<: *defaults

production:
  <<: *defaults

All the rest, tours structure is the same as the views and I have required css and js Abraham files.

This is the gem I have in my gemfile.lock:
abraham (2.1.1)

I am using ruby 2.7 and rails 6.0

CI is failing against Rails 6

https://travis-ci.com/github/actmd/abraham/jobs/497555469

Where to specify current_user ?

I use a different table for Devise.

Where do I configure this?

couldn't find file 'shepherd.js/dist/css/shepherd-theme-default' with type 'text/css'

Hi,
Good day. Thank you very much for making this Gem.
I'm using gem 'rails', '~> 5.2.3'
I did all the steps provided, however, I got this error when I load the page. Hope you can help.

couldn't find file 'shepherd.js/dist/css/shepherd-theme-default' with type 'text/css'

Attach tour on lazy loading elements like modals

The tour seems to check if the if the element for a tour step exist on the page.

What if the application happens to load some partials by javascript, for example a modal that does not exist on page right away. So how to implement a tour for modal content?

rails generate abraham:install not working

Is this potentially a rails 5 issue?

Output below:

rails generate abraham:install
Running via Spring preloader in process 47672
Expected boolean default value for '--markerb'; got :erb (string)
Expected string default value for '--controller'; got false (boolean)
Expected string default value for '--helper'; got true (boolean)
Expected string default value for '--assets'; got true (boolean)
Could not find generator 'abraham:install'. Maybe you meant 'rspec:install', 'koudoku:install' or 'devise:install'
Run `rails generate --help` for more options.

ERROR in ./node_modules/abraham/cli.js 1:0 Module parse failed: Unexpected character '#' (1:0)

Not sure if this is more a webpack issue than with abraham, but I'm getting the error:

ERROR in ./node_modules/abraham/cli.js 1:0
Module parse failed: Unexpected character '#' (1:0)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders

#!/usr/bin/env node
| 'use strict';

The tour works fine in my application, but this error is constantly in the console and I'm having issues with builds because of it. I've tried a webpack loader as suggested in webpack/webpack#4603, however that's not working so I wondered if anyone had come across this and there was a fix?

How to achieve multi pages tours alike redirecting from one page to another?

I want to show multiple Pop-up modal on different pages when user completed its registration. For instance, when user visits home page, shown up first pop-up modal, then user clicks 'Next' button on popup, it should be display other page pop-up modal and so on. how to achieve that functionality ?

Thanks in advance.

How to restart tour for user? (issue with deleting cookie)

Hi,

I'm trying to add a "reset" button to my site that would effectively restart the tour after the user has either clicked "later" or fully completed the tour. I tried deleting the abraham_histories entries with the creator_id and also tried to do Cookie.remove(COOKIE_KEY) but that's not working; I can still see the cookie with Cookie.get(). It only works if I delete the cookies through the browser, but not via JS, which makes me think I'm on the right track but missing something.

I tried Cookie.remove(COOKIE_KEY) as well as Cookie.remove(COOKIE_KEY, {path: PATH}) with different path combinations. Nothing worked. Any ideas?

Provide full configuration of underlying Shepherd.Tour JS component

Right now, the shepherd component is initialized like this:

  var tour = new Shepherd.Tour({
    defaults: {
      classes: '<%= Rails.configuration.abraham.default_theme %>'
    }
  });

It would be great to be able to use all of Shepherd.js options.

Maybe it would be easier to do with PORO Abrahamah tours rather than yml files, just suggesting :)

Automatically skip a step if its attachTo.element isn't on the page

Shepherd.js will insert raw, unstyled content into your page if a step's attachTo.element isn't present. Beyond the disappointing user experience, this also makes tours brittle because they have to be so tightly coupled with whatever particular dynamic elements are visible to a user.

There is an undocumented showOn option in Shepherd (usage example) that will let us check first whether the element is present. If not, we can skip to the next step.

I propose we make this behavior Abraham's default.

No route matches [GET] "/assets/shepherd.js.map" excluded from capture: DSN not set

I followed all of the steps in the Readme but I am getting the following error:

No route matches [GET] "/assets/shepherd.js.map" excluded from capture: DSN not set

How to handle controllers with the same name?

Hi there,

Thanks for making Abraham :)

My issue is that I have some namespaced controllers / actions with the same name, eg. :

• User::Dashboard#index
• Admin::Dashboard#index

Namespaces aren't taken into account in Abraham so I had put my yml file inside tours/dashboard/index.en.yml which results in the tour displaying in both dashboards.

I've tried changing the initializer to take subfolders like tours/admin/dashboard/index.en.yml into account but with no luck, Abraham doesn't recognize the controller.

Any clue?

Thanks

Reports of tours not being displayed in production - how to debug ?

I have reports of a tour not being displayed in production on different environments, for new users who never saw it.

I find it hard to track the reason - did you guys ever experiment that ?

I see it correctly with my own account.

Configure my application so tours don't appear in test environment by default

When we run in-browser tests, a Shepherd step will sometimes get in the way of an element positioned beneath it. If we're running tests that aren't explicitly testing product tours, it would be nice if the tours didn't appear.

Launch tour on demand

Is it possible to start tour on demand by calling a function or something?

Would it for example be possible to implement a "Launch Tour" button on a page?

Web UI?

Thanks for this gem - it looks great. Wondering if you've thought about building out any kind of web ui for managing the tours (rather than yaml). It'd be great to let non-technical members of my team create/manage tours. There are a million SaaS offerings for this out there, but they're 1) expensive and 2) not great.

Just wondering what thought has been given to this before I go ahead and start building in this direction myself.

Configure continuous integration to run cross-browser system tests

Using something like SauceLabs' free open source accounts, we should get Travis CI to run abraham's system tests in multiple browsers.

We could keep abraham's testing consistent with Shepherd's supported browsers, i.e. the last 2 versions of Firefox, Chrome, and Safari, plus IE Edge.

Would be really nice if the tour definitions reloaded without having to restart the server

Title says it all. I'll research how to do it myself if/when I have time.

Implement in-browser system tests

Now that Abraham is configured for Rails 5.1 support, it'll be easier to beef up our test coverage, specifically testing that Abraham's generated JavaScript functions within a browser using now-built-in Capybara.

Sourcemap errors

Is anyone else getting sourcemap errors in development? I think I have following the install instructions correctly but am seeing this error in my Rails logs

ActionController::RoutingError (No route matches [GET] "/assets/shepherd.js.map"):

actionpack (5.2.5) lib/action_dispatch/middleware/debug_exceptions.rb:65:in `call'
rollbar (3.0.1) lib/rollbar/middleware/rails/show_exceptions.rb:22:in `call_with_rollbar'
rack-contrib (2.1.0) lib/rack/contrib/response_headers.rb:17:in `call'
meta_request (0.7.0) lib/meta_request/middlewares/headers.rb:16:in `call'
actionpack (5.2.5) lib/action_dispatch/middleware/show_exceptions.rb:33:in `call'
railties (5.2.5) lib/rails/rack/logger.rb:38:in `call_app'
railties (5.2.5) lib/rails/rack/logger.rb:26:in `block in call'
etc

Travis is not running system tests in Rails 6+

rails test seems to run all tests in Rails 5, but only runs non-system tests in Rails 6.

Travis has been reporting successful builds in Rails 6, but it turns out it has never run the full test suite.

Support for Rails 4?

Hello guys,

Is there a reason why there's no support for Rails 4?

Thank you!

Issue with query selectors

Hi there,

When using specific query selectors in the "element" property in tours YML, some errors are raised for advanced selectors, eg. [id^="whatever"] or .class > #id

As specials characters like < > or quotes are escaped, it raises javascript errors.

Is there any way to either add .raw or .html_safe to this line?

abraham/app/views/application/_abraham.html.erb

Line 32 in 86a4533

attachTo: { element: "<%= step['attachTo']['element'] %>", on: "<%= step['attachTo']['placement'] %>" },

Remove visible step from the DOM before Turbolinks caches the page

Using this currently in app/assets/javascripts/application.js:

$(document).on('turbolinks:before-cache', function() {
    // Remove visible product tours
    $(".shepherd-step").remove();
});

Question: access to the full Shepherd API?

The Abraham documentation talks about steps, and the example has element and placement

   title: "Events"
      text: "If you're participating in any events today, we'll show that here."
      attachTo:
        element: ".dashboard-events"
        placement: "right"

The Shepherd API offers many other options on the Step object, including popperOptions, highlightClass, arrow etc.

Does Abraham support all of these options?

https://shepherdjs.dev/docs/

When I select "later," wait until my next session before showing the tour again

Currently, the tour reappears the next time I navigate to the view. The more likely expectation is that I would not be nagged again until my next login.

Remove jQuery dependency

Hello,

As I understand you only need jQuery for the following lines:

abraham/app/assets/javascripts/abraham/index.js

Line 5 in 160ec8e

$(document).on('turbolinks:before-cache', function() {

Wouldn't it be more judicious to remove the dependency altogether and rewrite that part in vanilla JS?

Cheers

using js-cookie@^3.1 instead of js-cookie@^2.2.0

In our app we use js-cookie@^3.1, and when i tried to down grade to version 2.2, my app doesn't function correctly.
so i want to keep using js-cookie@^3.1
i fixed this by:
In gems/abraham-2.5.1/app/assets/javascripts/abraham/index.js i changed
//= require js-cookie/src/js.cookie
to:
//= require js-cookie/dist/js.cookie

js-cookie/dist/js.cookie is the default path for version 3.1
i would like to ask , is there a way to do that without modifying the gem?

Update documentation for Rails 7

Would be helpful to update installation/config documentation to Rails 7 standards. I tried installing this morning on a rails 7 app and couldn't get it working. I ultimately uninstalled everything, but I would still love to use the gem once the documentation adapts to a rails 7 environment.

Transition from Travis CI to GitHub Actions

Seems open source projects no longer get unlimited testing with Travis, so Travis has suddenly stopped running tests on our pulls requests, etc.

Custom buttons and actions

Hi. Thank you for porting shepherd to Rails!

I have a question

I see that shepherd shows that buttons with custom actions can be included in tour steps, e.g.:

buttons: [
{
action() {
return this.back();
},
text: 'Back'
},

(from their demo page at https://shepherdjs.dev/)

I can't figure out how to do this with Abraham. I suspect I'm not using the correct syntax, but it's not clear to me what the correct one would be (shepherd's vanilla syntax doesn't seem to work for me).

Don't start a tour if the first step's attachTo isn't present

Related to #6... while we want to keep a tour going if an intermediate step is missing, most tours don't make sense if the first step gets skipped.

I'd like to add a check to our start method wrapper that confirms the first step's attachTo element is present on the page, should the first step have an attachTo value.

Upgrade abraham to use latest version of Shepherd.js

Abraham was developed when Shepherd.js was at version 1.8... it's now at 5.0 (and no longer maintained by HubSpot, to boot).

According to shepherd-pro/shepherd#624, we should upgrade to the v6 beta since that's being released soon.

Use another id than current_user's one

Hi there,

Thanks for the great job with Abraham. I was wondering if there was any possibility to pass in some other model id to a tour? Not just the user's one via current_user?

Thanks,

Thomas

If user has more than one unviewed tour, show them both?

As we've used Abraham in our software for a while now, we're at the point of adding new features to pages that already have introductory tours. We want new users to learn about all the features, and we want old users to learn about the new features.

Currently, there two ways for that play out:

1. Include the new feature tour content in a second, feature-specific tour. Existing users who have seen the introductory tour only see the new feature-specific one. New users see the intro tour first (without the new feature mentioned) and then have to revisit the same page later to see the second tour.
2. Include the new feature tour content in both the introductory tour AND a second, feature-specific tour. Existing users who have seen the introductory tour only see the new feature-specific one. New users see the same content duplicated in both the introductory tour and when they revisit the same page later, in the second, feature-specific tour.

Neither is a great user experience.

There are a few ways we could improve this:

1. Abraham shows a user all unseen tour content for a page. This approach would benefit from developers writing several smaller tours on a per-callout basis that would naturally string together, rather than large cohesive tours.
2. We add some notion of a "release date" for each tour. Tours with a release date would only get shown if the user had visited the page some time before the release. Of course, this requires Abraham knowing more about the user than just their current_user.id, which may not be desirable or possible in all cases.

Anyhow, open to suggestions!

Manually activate a tour (e.g. on click)

For example when hovering over the "starred items" icon on Slack, you get a nice popup as follows

Then when you click on the icon, the (single step) tour begins

The nice thing is that the "hover" step doesn't need to be there (e.g. on mobile there is no "hover") and so it works nicely on both desktop and mobile.

Uncaught SyntaxError: Identifier 'tour' has already been declared

In v2, I switched from "var" to "const" to define the tour object.

When you navigate between tour-enabled pages with Turbolinks, you'll get the JS error:

Uncaught SyntaxError: Identifier 'tour' has already been declared

We need to fix this for Turbolinks users.