Getting Started

Before you can start using Beyond Canvas, you first need to install it and get an overview of the possibilities you have when working with it.

Install the gem

1. Add this line to your application's Gemfile:

   gem 'beyond_canvas'

2. Execute the following command:

   $ bundle install

3. Run the generator. The required command depends on whether you'd like to use Webpacker or Sprockets.

   1. Webpacker:

      $ rails generate beyond_canvas:install

   2. Sprockets:

      $ rails generate beyond_canvas:install --skip-webpacker

   At this point, several instructions will appear in the console.

   The generator will install two initializer files, one for BeyondCanvas(config/initializers/beyond_canvas.rb) and the second one for BeyondApi (config/initializers/beyond_api.rb). It is really important that you adapt all configuration options to your needs.

4. Add the Beyond Canvas router to the routes.rb file:

   beyond_canvas_routes

5. Run the database migration:

   $ rails db:migrate

6. Restart your application. Otherwise you might run into errors due to configuration settings that are not updated.

Learn about helpers

Beyond Canvas will automatically create helpers that you can use inside your controllers and views:

• Use this helper to figure out the shop you are currently logged in to.

  current_shop

• To verify if you are logged in to a shop, use the following helper:

  logged_in?

Allow strong parameters

When customizing your own views, you may end up adding new attributes to forms.

If you would like to allow additional parameters for these forms, you can do so by using a before action in your ApplicationController:

class ApplicationController < ActionController::Base
  before_action :configure_permitted_parameters, if: :beyond_canvas_controller?

  protected

  def configure_permitted_parameters
    beyond_canvas_parameter_sanitizer.permit(:your_app_client_id, :your_app_client_secret)
  end
end

Customize views

Beyond Canvas aims to support you in quickly developing a Beyond application. That's why all its views are packaged inside the gem which allows you to easily get started. However, you still have the possibility to customize them according to your specific needs.

To do so, you need to invoke the following generator. It will copy all views to your application:

$ rails generate beyond_canvas:views

Customize controllers

Besides the possibility to customize the views, you can also customize each controller by following these steps:

1. Run the custom controller generator:

   $ rails generate beyond_canvas:controller

2. Use the custom controller within the router:

   beyond_canvas_routes controllers: { authentications: 'shops' }

   Note that you can use customer controllers and custom webhooks at the same time. In that case, the router configuration will look like this:

   beyond_canvas_routes controllers: { authentications: 'shops', webhooks: 'webhooks' }

3. Change or extend the controller actions according to your needs.

Customize webhooks

When using Beyond Canvas, your app is listening to the app.uninstalled event by default. If you would like your app to listen to further events or if you would like to overwrite the default, you can customize the related settings according to your needs. Here’s how:

1. Run the custom webhook generator:

   $ rails generate beyond_canvas:webhook

2. Use the custom webhook within the router:

   beyond_canvas_routes controllers: { webhooks: 'webhooks' }

   Note that you can use customer controllers and custom webhooks at the same time. In that case, the router configuration will look like this:

   beyond_canvas_routes controllers: { authentications: 'shops', webhooks: 'webhooks' }

3. Change or extend the webhook actions according to your needs.