### Project Setup with Git and Bundler

Source: https://github.com/actmd/abraham/wiki/Gem-development-workflow

Clones the Abraham project repository, navigates into the project directory, and installs necessary Ruby gems using Bundler. This is the initial setup required before working on the project.

```bash
git clone ...
cd abraham
gem install bundler
bundle install
```

--------------------------------

### Install Abraham Gem and Dependencies

Source: https://context7.com/actmd/abraham/llms.txt

Installs the Abraham gem, runs the installation generator to set up migrations and initializers, and adds necessary JavaScript dependencies for tour functionality.

```bash
# Install Abraham gem and run generator
bundle add abraham
rails generate abraham:install
rails db:migrate

# Install JavaScript dependencies
yarn add js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
```

--------------------------------

### Clone and Install Dependencies (Bash)

Source: https://github.com/actmd/abraham/blob/master/README.md

Commands to clone the Abraham repository and install its Ruby and Yarn dependencies. Assumes rvm is installed and configured.

```bash
~ git clone git@github.com:actmd/abraham.git
Cloning into 'abraham'...
~ cd abraham
ruby-2.5.3 - #gemset created /Users/jon/.rvm/gems/ruby-2.5.3@abraham
ruby-2.5.3 - #generating abraham wrappers - please wait
~ bundle install
Bundle complete! 13 Gemfile dependencies, 73 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
~ yarn install
```

--------------------------------

### Generate Abraham Installer and Migrate Database

Source: https://github.com/actmd/abraham/blob/master/README.md

After adding the gem, run the Abraham installer to generate necessary configuration files and run database migrations to set up tracking for tours.

```bash
$ bundle install
$ rails generate abraham:install
$ rails db:migrate
```

--------------------------------

### Manual Tour Triggering (JavaScript)

Source: https://github.com/actmd/abraham/blob/master/README.md

Demonstrates how to manually start a tour named 'walkthrough' using JavaScript event listeners. This is useful when tours should not start automatically. It requires a button to initiate the tour and uses the `Abraham.startTour` method.

```javascript
<button id="startTour">Start tour</button>

<script>
  document.querySelector("#startTour").addEventListener("click", function() {
    Abraham.startTour("walkthrough"));
  });
</script>

```

```javascript
$"#startTour".on("click", function() { Abraham.startTour('walkthrough'); })

```

--------------------------------

### Gem Release Process

Source: https://github.com/actmd/abraham/wiki/Gem-development-workflow

Provides commands for releasing a new version of the gem. Includes pushing the gem to rubygems, running tests, building the gem locally, and finalizing the feature branch using git flow.

```bash
# If you're not signed into rubygems yet, run this and enter your credentials
gem push
# Run all the tests
rails t
# Make sure the gem builds
rake install
# Finish & squash the branch
git flow feature finish --squash
# Create the git flow release
git flow release start VERSION
git flow release finish
rake release
```

--------------------------------

### Install JavaScript Dependencies for Abraham

Source: https://github.com/actmd/abraham/blob/master/README.md

Install the required JavaScript libraries, js-cookie and shepherd.js, using Yarn. These are essential for Abraham's tour functionality and cookie management.

```bash
$ yarn add js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
```

--------------------------------

### Start Git Flow Release (Bash)

Source: https://github.com/actmd/abraham/blob/master/README.md

Command to initiate a release using the git-flow branching model.

```bash
$ git flow release start VERSION_NUMBER
```

--------------------------------

### Control Tours using Flipper in Ruby

Source: https://context7.com/actmd/abraham/llms.txt

Provides Ruby code examples for programmatically enabling or disabling feature flags that control tour visibility within the Abraham application.

```ruby
# Enable/disable tours via Flipper
Flipper.enable(:new_feature_tour)
Flipper.disable(:hide_old_tutorial)
```

--------------------------------

### Install Local Abraham Gem (Ruby)

Source: https://github.com/actmd/abraham/blob/master/README.md

How to add the Abraham gem to a local Rails application using a path to a local copy of the gem.

```ruby
gem 'abraham', path: '~/Workspace/abraham'
```

--------------------------------

### Install Abraham Gem in Rails

Source: https://github.com/actmd/abraham/blob/master/README.md

Add the Abraham gem to your application's Gemfile to include its functionality. After adding, run bundle install to install the gem and the associated generator.

```ruby
gem 'abraham'
```

--------------------------------

### Build and Push Abraham Gem (Bash)

Source: https://github.com/actmd/abraham/blob/master/README.md

Commands to build the Abraham gem locally and then push it to a package registry (like Rubygems).

```bash
$ rake build
$ gem push pkg/abraham-VERSION_NUMBER.gem
```

--------------------------------

### Manual Tour Triggering with JavaScript

Source: https://context7.com/actmd/abraham/llms.txt

Configures tours to be triggered manually rather than automatically, and provides a JavaScript API to start tours programmatically on demand, initiated by user interaction.

```yaml
# config/tours/dashboard/home.en.yml
walkthrough:
  trigger: "manual"
  steps:
    1:
      text: "This walkthrough will show you how to use advanced features."
    2:
      title: "Advanced Controls"
      text: "Click here to access advanced settings."
      attachTo:
        element: "#settings-panel"
        placement: "left"
```

--------------------------------

### Abraham JavaScript Core API for Tour Management

Source: https://context7.com/actmd/abraham/llms.txt

The client-side JavaScript API for Abraham, used for managing user tours. It handles tour initialization, starting tours programmatically, automatically starting the next incomplete tour on page load or Turbolinks load, and cleaning up tour elements before Turbolinks cache.

```javascript
// Abraham JavaScript API
var Abraham = new Object();
Abraham.tours = {};
Abraham.incompleteTours = [];

// Start a specific tour programmatically
Abraham.startTour = function(tourName) {
  if (!Shepherd.activeTour) {
    Abraham.tours[tourName].start();
  }
};

// Automatically start next incomplete tour
Abraham.startNextIncompleteTour = function() {
  if (Abraham.incompleteTours.length) {
    Abraham.tours[Abraham.incompleteTours[0]].checkAndStart();
  }
};

// Event listeners for automatic tour triggering
document.addEventListener("DOMContentLoaded", Abraham.startNextIncompleteTour);
document.addEventListener("turbolinks:load", Abraham.startNextIncompleteTour);

// Cleanup before Turbolinks cache
document.addEventListener('turbolinks:before-cache', function() {
  document.querySelectorAll(".shepherd-element").forEach(function(el) {
    el.remove()
  });
  Abraham.tours = {};
  Abraham.incompleteTours = [];
});
```

--------------------------------

### Abraham Initialization and Configuration Loading

Source: https://context7.com/actmd/abraham/llms.txt

This Ruby initializer script configures Abraham by loading tour definitions from YAML files and merging them with application-wide settings from `config/abraham.yml`. It dynamically discovers tour files, parses them, and sets up `config.abraham.tour_options` and `config.abraham.tours` for use throughout the application.

```ruby
# config/initializers/abraham.rb
Rails.application.configure do
  tours = {}
  tours_root = Pathname.new(Rails.root.join("config/tours"))

  if Rails.root.join("config/tours").exist?
    Dir.glob(Rails.root.join("config/tours/**/*.yml")).each do |yml|
      relative_filename = Pathname.new(yml).relative_path_from(tours_root)
      controller_path, filename = relative_filename.split
      file_parts = filename.to_s.split(".")
      action = file_parts[0]
      locale = file_parts[1]
      t = YAML.load_file(yml)
      tours["#{controller_path}.#{action}.#{locale}"] = t
    end
  end

  abraham_config = Rails.application.config_for :abraham
  config.abraham = ActiveSupport::OrderedOptions.new
  config.abraham.tour_options = abraham_config[:tour_options]
  config.abraham.tours = tours
end
```

--------------------------------

### Define Tours Using YAML Format

Source: https://context7.com/actmd/abraham/llms.txt

Defines multi-step guided tours using YAML files. Each step can include text, title, and attachment details for elements on the page, supporting internationalization.

```yaml
# config/tours/articles/index.en.yml
intro:
  steps:
    1:
      text: "Welcome to your dashboard! This is where we'll highlight key information to manage your day."
    2:
      title: "Events"
      text: "If you're participating in any events today, we'll show that here."
      attachTo:
        element: ".dashboard-events"
        placement: "right"
    3:
      title: "Search"
      text: "You can find anything else by using the search bar."
      attachTo:
        element: ".navbar-primary form"
        placement: "bottom"
```

--------------------------------

### Define Tour with Steps (YAML)

Source: https://github.com/actmd/abraham/blob/master/README.md

Defines a tour named 'intro' with three steps. Each step has text, and specific steps include a title, element to attach to, and placement of the callout relative to the element. This format is used for structuring tour content.

```yaml
intro:
  steps:
    1:
      text: "Welcome to your dashboard! This is where we'll highlight key information to manage your day."
    2:
      title: "Events"
      text: "If you're participating in any events today, we'll show that here."
      attachTo:
        element: ".dashboard-events"
        placement: "right"
    3:
      title: "Search"
      text: "You can find anything else by using the search bar."
      attachTo:
        element: ".navbar-primary form"
        placement: "bottom"

```

--------------------------------

### Manual Tour Triggering Configuration (YAML)

Source: https://github.com/actmd/abraham/blob/master/README.md

Configures a tour named 'walkthrough' to be triggered manually. The 'trigger: "manual"' option prevents the tour from starting automatically, requiring explicit invocation via `Abraham.startTour`.

```yaml
walkthrough:
  trigger: "manual"
  steps:
    1:
      text: "This walkthrough will show you how to..."

```

--------------------------------

### Trigger Tour Programmatically with JavaScript

Source: https://context7.com/actmd/abraham/llms.txt

Demonstrates how to initiate a tour using JavaScript by adding an event listener to a button that calls the `Abraham.startTour` method with the tour's name.

```html
<!-- Trigger tour from JavaScript -->
<button id="startTour">Start Walkthrough</button>

<script>
  document.querySelector("#startTour").addEventListener("click", function() {
    Abraham.startTour("walkthrough");
  });
</script>
```

--------------------------------

### Configure Rails Application for Abraham

Source: https://context7.com/actmd/abraham/llms.txt

Includes the necessary Abraham JavaScript and CSS assets in the Rails application's asset pipeline and adds a helper to render tour elements in the layout.

```ruby
# app/assets/javascripts/application.js
//= require abraham

# app/assets/stylesheets/application.scss
*= require abraham/theme-default

# app/views/layouts/application.html.erb
<%= abraham_tour %>
</body>
</html>
```

--------------------------------

### Finish Git Flow Release (Bash)

Source: https://github.com/actmd/abraham/blob/master/README.md

Commands to complete a release using git-flow, including merging changes and pushing to remote repositories.

```bash
$ git flow release finish
$ git push origin develop
$ git push origin master
$ git push --tags
```

--------------------------------

### Configure Abraham Tour Theme

Source: https://github.com/actmd/abraham/blob/master/README.md

Update the `config/abraham.yml` file to specify tour options, such as applying a specific CSS theme like 'theme-dark' to the default step options.

```yaml
defaults: &defaults
  :tour_options: '{ defaultStepOptions: { classes: "theme-dark" } }'
```

--------------------------------

### AbrahamHistory Model Schema and Query

Source: https://context7.com/actmd/abraham/llms.txt

Defines the ActiveRecord model schema for `abraham_histories` used to track tour completion per user, controller, and action. Includes an example of querying completed tours.

```ruby
# Database schema created by migration
create_table :abraham_histories do |t|
  t.string :controller_name
  t.string :action_name
  t.string :tour_name
  t.references :creator, null: false, index: true
  t.timestamps index: true
end

# Query tour completion status
completed_tours = AbrahamHistory.where(
  creator_id: current_user.id,
  controller_name: "articles",
  action_name: "index"
)

tour_names = completed_tours.map(&:tour_name)
# => ["intro", "advanced_features"]
```

--------------------------------

### Define Tour with Custom Buttons (YAML)

Source: https://github.com/actmd/abraham/blob/master/README.md

Shows how to define custom buttons for a tour step. Each button has specified text, an action (like 'cancel', 'complete', 'next'), and CSS classes for styling. This allows for more interactive user control within tours.

```yaml
my_tour:
  steps:
    1:
      text: "Welcome to my custom button tour"
      buttons:
        1:
          text: 'Show this to me later'
          action: 'cancel'
          classes: 'custom-button shepherd-button-secondary'
        2:
          text: 'Finish now'
          action: 'complete'
          classes: 'custom-button'

```

--------------------------------

### Define Tours in YAML for Rails Controllers

Source: https://github.com/actmd/abraham/blob/master/README.md

Organize tour definitions in the `config/tours` directory, mirroring your application's controller and action structure. Specify the locale in the filename (e.g., `.en.yml`, `.es.yml`).

```treeview
config/
└── tours/
    ├── admin/
    │   └── articles/
    │       └── edit.en.yml
    ├── blog/
    │   ├── show.en.yml
    │   └── show.es.yml
    └── articles/
        ├── index.en.yml
        ├── index.es.yml
        ├── show.en.yml
        └── show.es.yml
```

--------------------------------

### Insert Abraham Tour JavaScript in Layout

Source: https://github.com/actmd/abraham/blob/master/README.md

Place the `abraham_tour` helper method in your main layout file, just before the closing `body` tag, to ensure tours are rendered correctly.

```erb
<%= abraham_tour %>
</body>
</html>
```

--------------------------------

### Tour Callout Placement Options

Source: https://context7.com/actmd/abraham/llms.txt

This YAML configuration defines various placement options for tour callouts relative to specific page elements. It showcases how to attach tour steps to elements using CSS selectors and specifies the desired position (e.g., 'top', 'right', 'bottom left', 'center') for the callout. This allows for precise visual guidance within the tour.

```yaml
# config/tours/dashboard/placement.en.yml
positioning_tour:
  steps:
    1:
      text: "Top placement"
      attachTo:
        element: ".target-element"
        placement: "top"
    2:
      text: "Right placement"
      attachTo:
        element: ".target-element"
        placement: "right"
    3:
      text: "Bottom left placement"
      attachTo:
        element: ".target-element"
        placement: "bottom left"
    4:
      text: "Center placement"
      attachTo:
        element: ".target-element"
        placement: "center"
```

--------------------------------

### AbrahamHistoriesController API Endpoint

Source: https://context7.com/actmd/abraham/llms.txt

Describes the `AbrahamHistoriesController` which acts as a JSON API endpoint, designed to receive POST requests from the JavaScript tour interface to record tour completion events.

```ruby
# POST /abraham_histories
# Request body:
# {

```

--------------------------------

### Module-Namespaced Controller Tour Path Resolution

Source: https://context7.com/actmd/abraham/llms.txt

This Ruby code demonstrates how the tour system correctly resolves tour configurations for controllers nested within modules. The `ArticlesController` within the `Admin` module will load tours from `config/tours/admin/articles/edit.en.yml`, ensuring proper tour loading for complex controller structures.

```ruby
# app/controllers/admin/articles_controller.rb
module Admin
  class ArticlesController < ApplicationController
    def edit
      # Renders tours from config/tours/admin/articles/edit.en.yml
    end
  end
end
```

--------------------------------

### Locale Fallback Logic for Tours

Source: https://context7.com/actmd/abraham/llms.txt

This Ruby code illustrates the multi-locale tour support mechanism. It shows how the tour system dynamically loads tour content based on the current `I18n.locale`. If a tour definition is not found for the current locale, it automatically falls back to the default locale, ensuring tour availability across different language settings.

```ruby
# Spanish-speaking user sees Spanish tour
I18n.locale = :es
# => Tour loaded from config/tours/articles/index.es.yml

# Falls back to default locale if translation missing
I18n.locale = :fr
# => Tour loaded from config/tours/articles/index.en.yml (if en is default)
```

--------------------------------

### Integrate Tours with Flipper Feature Flags

Source: https://context7.com/actmd/abraham/llms.txt

Enables or disables tours based on Flipper feature flags. Tours can be configured to show only when a specific flag is enabled or disabled, facilitating phased rollouts.

```yaml
# config/tours/articles/new_feature.en.yml
walkthrough:
  flipper_key: "new_feature_tour"
  flipper_activation: "enabled"
  steps:
    1:
      text: "This tour only shows when new_feature_tour flipper is enabled."

disabled_tour:
  flipper_key: "hide_old_tutorial"
  flipper_activation: "disabled"
  steps:
    1:
      text: "This tour shows only when hide_old_tutorial flipper is disabled."
```

--------------------------------

### Require Abraham JavaScript and CSS in Rails Application

Source: https://github.com/actmd/abraham/blob/master/README.md

Include the Abraham JavaScript file in your application's JavaScript manifest and a CSS theme in your SCSS file to enable tours and styling.

```javascript
//= require abraham
```

```scss
 *= require abraham/theme-default
```

--------------------------------

### Define Custom Tour Buttons

Source: https://context7.com/actmd/abraham/llms.txt

Allows for the creation of custom buttons within tour steps, enabling specific actions like 'cancel' or 'complete' and custom CSS class styling for unique user flows.

```yaml
# config/tours/dashboard/custom.en.yml
my_tour:
  steps:
    1:
      text: "Welcome to my custom button tour"
      buttons:
        1:
          text: 'Show this to me later'
          action: 'cancel'
          classes: 'custom-button shepherd-button-secondary'
        2:
          text: 'Finish now'
          action: 'complete'
          classes: 'custom-button'
```

--------------------------------

### Abraham Global Tour Configuration

Source: https://context7.com/actmd/abraham/llms.txt

This YAML file defines default Shepherd.js tour options and theme customizations for the Abraham application. It uses YAML anchors and aliases for reusability across different environments (development, test, production), ensuring consistent tour behavior application-wide.

```yaml
# config/abraham.yml
defaults: &defaults
  :tour_options: '{ defaultStepOptions: { classes: "theme-dark", scrollTo: true, cancelIcon: { enabled: true } }, useModalOverlay: true }'

development:
  <<: *defaults

test:
  <<: *defaults

production:
  <<: *defaults
```

--------------------------------

### Multi-Locale Tour Content Configuration

Source: https://context7.com/actmd/abraham/llms.txt

This demonstrates how to configure tour content for different locales using YAML files. The system supports internationalization by allowing separate tour definitions per locale, falling back to a default locale if a specific translation is missing. This ensures tours are displayed correctly for users in different language regions.

```yaml
# config/tours/articles/index.en.yml
intro:
  steps:
    1:
      text: "Welcome to the articles section!"
    2:
      title: "Create Article"
      text: "Click here to create a new article."
      attachTo:
        element: ".new-article-button"
        placement: "bottom"

# config/tours/articles/index.es.yml
intro:
  steps:
    1:
      text: "¡Bienvenido a la sección de artículos!"
    2:
      title: "Crear Artículo"
      text: "Haga clic aquí para crear un nuevo artículo."
      attachTo:
        element: ".new-article-button"
        placement: "bottom"
```

--------------------------------

### Flipper Integration for Tour Control (YAML)

Source: https://github.com/actmd/abraham/blob/master/README.md

Illustrates how to use Flipper keys to control tour visibility. The 'flipper_key' option enables or disables a tour based on the Flipper state. The 'flipper_activation' option can specify whether the tour is enabled or disabled when the Flipper is active.

```yaml
walkthrough:
  flipper_key: "name_of_flipper"
  steps:
    1:
      text: "This walkthrough will show you how to..."

```

```yaml
walkthrough:
  flipper_key: "name_of_flipper"
  flipper_activation: "disabled"
  steps:
    1:
      text: "This walkthrough will show you how to..."

```

--------------------------------

### Render Tour JavaScript in Layout

Source: https://context7.com/actmd/abraham/llms.txt

This snippet shows how to include the abraham_tour helper method within the application's layout file. It ensures that the tour JavaScript is rendered on every page, provided the helper is called. Dependencies include the Rails view layer.

```erb
<!DOCTYPE html>
<html>
<head>
  <title>My Application</title>
  <%= stylesheet_link_tag 'application' %>
  <%= javascript_include_tag 'application' %>
</head>
<body>
  <%= yield %>

  <%= abraham_tour %>
</body>
</html>
```

--------------------------------

### Module-Namespaced Controller Tour Configuration

Source: https://context7.com/actmd/abraham/llms.txt

This YAML defines tour content specifically for a module-namespaced controller action (`admin/articles_controller`'s `edit` action). It follows the naming convention `config/tours/<module>/<controller>/<action>.<locale>.yml` to ensure the tour is loaded correctly for that specific context.

```yaml
# config/tours/admin/articles/edit.en.yml
editor_tour:
  steps:
    1:
      text: "Welcome to the admin article editor."
    2:
      title: "Advanced Options"
      text: "Access advanced editing features here."
      attachTo:
        element: "#advanced-options"
        placement: "right"
```

--------------------------------

### Ruby on Rails System Test for Checkout Flow

Source: https://context7.com/actmd/abraham/llms.txt

A system test written in Ruby on Rails to verify the user checkout process. It visits the checkout page, fills in user details, submits the purchase, and asserts the order confirmation message. This test is designed to run without interruption from Abraham tours.

```ruby
class ToursTest < ApplicationSystemTestCase
  test "user completes checkout flow" do
    visit checkout_path
    # No tour interruptions during test
    fill_in "Email", with: "user@example.com"
    click_button "Complete Purchase"
    assert_text "Order confirmed"
  end
end
```

--------------------------------

### Disable Abraham Tours in Test Environment

Source: https://context7.com/actmd/abraham/llms.txt

This code snippet configures the Abraham tours to be an empty hash in the test environment. This is crucial for preventing tours from interfering with JavaScript integration tests, ensuring a clean testing environment and accurate test results.

```ruby
# test/test_helper.rb
Rails.application.configure do
  config.abraham.tours = {}
end
```

--------------------------------

### Reset Abraham Configuration in Test Helper (Ruby)

Source: https://github.com/actmd/abraham/blob/master/README.md

Provides a Ruby code snippet for clearing Abraham tour definitions within a test environment. This is useful for integration tests to prevent tours from interfering with the testing process. It involves configuring the Rails application to an empty tour object.

```ruby
Rails.application.configure do
  config.abraham.tours = {}
end

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.