Cockpit App

If you would like your app to be opened in the merchant's cockpit instead of in an external tab, you will need to set up your app as a so-called cockpit app. Your app will then show up in the sidebar of the merchant's cockpit and be embedded as an iFrame when the merchant selects the respective menu entry in the sidebar. Follow the steps described on this page to set up your app as a cockpit app.

Configure the initializer file

First of all, you must set the option cockpit_app in the initializer file /config/initializers/beyond_canvas.rb to true.

Provide breadcrumbs

In order to facilitate the navigation for the merchant and to match the general look and feel of the cockpit, your app must provide breadcrumbs. Here's how to do so:

1. Adjust your controller

Add the following code to your controller:

breadcrumb path_name, :path

2. Create a breadcrumbs file

Create the file app/views/beyond_canvas/shared/_breadcrumbs.html.erb and add the following code to it:

<% if is_cockpit_app? && breadcrumb_trail.count.positive? %>

  <div class='breadcrumbs'>

    <%= inline_svg_tag 'icons/home.svg' %>

    <% i = 1 %>

    <% breadcrumb_trail do |crumb| %>
      <%= link_to crumb.name, crumb.url, class: "breadcrumb__item#{ '--current' if crumb.current? }" %>
      <% unless i ==  breadcrumb_trail.count || crumb.current? %><%= inline_svg_tag 'icons/arrow_right.svg' %><% end %>
      <% i += 1 %>
    <% end %>

  </div>

<% end %>

With this code, you can already see a basic version of the breadcrumb in the shop. Now, it's time to adjust it to your needs and to the actual path. Here's an example of what you could add:

    <%= inline_svg_tag 'icons/home.svg' %>

    <%= link_to I18n.t('breadcrumbs.dashboard'), current_shop.url('/cockpit'), class: 'breadcrumb__item', target: '_parent' %>
    <%= inline_svg_tag 'icons/arrow_right.svg' %>

    <%= link_to I18n.t('breadcrumbs.apps'), current_shop.url('/cockpit/apps'), class: 'breadcrumb__item', target: '_parent' %>
    <%= inline_svg_tag 'icons/arrow_right.svg' %>

    <% i = 1 %>

With this code, the breadcrumb starts at the cockpit's dashboard (which is the usual starting point), followed by the Apps section.

You're done with the breadcrumb settings. If you would like to get further support in terms of breadcrumb management, you can make use of dedicated gems, such as the loaf gem.

Support iFrames

As mentioned in the introduction, cockpit apps are embedded as an iFrame. Thus, your app must include a header that allows such iFrames. To do so, add the following code to the config/application.rb file:

class Application < Rails::Application
  config.action_dispatch.default_headers = {
    'X-Frame-Options' => 'ALLOWALL'
  }
end

Your app is now well prepared to be embedded as a cockpit app! When submitting your app, be sure to select the App type Menu entry in the sidebar.