More at Faalis.io: More Faalis

Dashboard Sidebar

This guide will get you started with sidebar menu of Faalis dashboard.

This guide covers the overview of dashboard sidebar and how it works.

After reading this guide, you will know:

Warning: Sidebar API is in beta state and may change in the future.

1 How sidebar works?

Sidebar is not very complicated. It's just a nested hash which Faalis uses it to render a nested menu in dashboard. You can build this hash easily by yourself and via any source you want. For example you can fetch the entries from database of a remote API. But Faalis provides a simple DSL for you to build this hash more easily. It's a bit limited but far from enough.

The best place to build your sidebar hash is in Dashboard::ApplicationController. Faalis will generate a very besic skel for you to easily create your hash.

In Dashboard::ApplicationController of your application. You should define a method called setup_sidebar. In fact by overriding this method you will allow Faalis to know about the sidebar.

In setup_sidebar method you should build your suitable sidebar menu hash and assign it to @sidebar instance variable.

Faalis provides a nice little DSL for you to helps you build your hash easily. Here is an example of the sidebar DSL:

  # Dashboard::ApplicationController
  # ...
  def setup_sidebar

    @sidebar = sidebar('') do |s|
      s.faalis_entries
      s.menu(t('Base Data'), icon: 'fa fa-book') do
        s.item(t('Provinces'),
               url: main_app.dashboard_provinces_path,
               model: 'Province')
        s.item(t('Cities'),
               url: main_app.dashboard_cities_path,
               model: 'City')
        s.item(t('Areas'),
               url: main_app.dashboard_areas_path,
               model: 'Area')
      end
    end
  end
  #...

As you can see in the above example you can start defining your sidebar hash using sidebar method (Checkout the API documents for this method for more information). This method yields an Sidebar instance which provides following methods.

2.1 faalis_entries

This method will render all the menu entries provided by Faalis itself. Currently Faalis only provides the authentication and authorization menu.

If you wish your users to not see this menu don't worry you can handle it via permissions.

Using menu item you can define a head menu which can contains several items. Checkout the API docs for menu

2.3 item

This method will define a single clickable entry inside a menu. The most important thing about this method is the model argument which is optional and indicates that user have to has read access to what model to see this entry. If user does not have read access on the given model name, he/she won't see this item and menus with no visible item won't be visible to user too. For more information on item take a look at its API docs.

Feedback

You're encouraged to help improve the quality of this guide.

Please contribute if you see any typos or factual errors. To get started, you can read our documentation contributions section.

You may also find incomplete content, or stuff that is not up to date. Please do add any missing documentation for master. Make sure to check Edge Guides first to verify if the issues are already fixed or not on the master branch. Check the Faalis Guides Guidelines for style and conventions.

If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.

And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome in the rubyonrails-docs mailing list.