Dashboards

Ez-on-rails has the ability to provide dashboards having stylable and clickable tiles with target links.

Dashboards are meant to be used in namespaces holding links to its controller actions. In combination with the navigation bar, this provides a comprehensible ability to navigate through the application. But you must not use dashboards for namespaces. You can also use them to provide links anywhere to your application or outside your application.

Dashboards tiles can be categorized. Each category will be rendered as expandable html details view.

The dashboards use the same principles like the forms using render info. They are rendered using partials and can be configured using a dash_info that is located in a helper file.

You can create dashboards of namespaces using the ezdev generator or create it yourself manually. If you want to use the generator the generator, you just have to call it and pass the target namespace.

rails generate ez_on_rails:ezdash Content

Note that the generator adds a restriction to access the page to the db/seeds.rb file. You can remove the generated entry to make your dashboard public or change the assigned groups to restrict the access to the target group. See the permission system page for more details about the permission system.

If you want to create it manually have a look at [this section](## Create a dashboard manually). If you want to change the tiles, its categories or appearance, have a look at the [dash info section](## Dash info).

If you want to change the partial that renders the dashboard, you have to eject the views using the ezviews generator and change the file _views/ez_on_rails/shared/dashboard.html.slim

Dash info

The dash info tells the dashboard what categories and tiles should be rendered. It is located in a helper file for your dashboard, eg. app/helpers/content/dashboard.rb.

The file contains a method that returns the dash info, eg.:

def dash_info_admin
  [ 
    {
      tiles: [
        {
          label: Article.model_name.human(count: 2),
          background_color: '#FFA07A',
          text_color: '#000000',
          text: t(:articles_description),
          icon: 'newspaper',
          controller: 'content/articles',
          action: 'index'
        },
        {
          label: Magazine.model_name.human(count: 2),
          background_color: '#4682B4',
          text_color: '#FFFFFF',
          text: t(:magazines_description),
          image: 'magazines.png',
          link: 'https://some-external.url'
          controller: 'content/magazines',
          action: 'index'
        },
        ...
      ]
    },
    {
      label: 'Metainformation',
      tiles: [
        {
          label: Tag.model_name.human(count: 2),
          background_color: '#CD5C5C',
          text_color: '#FFFFFF',
          text: t(:tags_description),
          image: 'tags.png',
          controller: 'content/tags',
          action: 'index',
          footer: t(:tags_footer_description),
        },
        ...
      ]
    }
    ...
  ]
end

The array returned by the method defines the categories. Each category can have a label and tiles. If the category has a label, it is rendered as foldable html details view. If the label is not passed, the tiles will be directly rendered without a surrounding category.

The tiles option is expected to be an array of tile information. Every tile can have the following options:

• label: The title of the tile that that is shown as large text on the tile.
• background_color: The background color of the tile. It is directly passed as css property, hence it can either be a css color name (like red, blue, ...) or a hexadezimal code.
• text_color: The text color. This should be something having contrast to the background color. Like the background color, it is directly passed as css property. Use a hex code or css color name to define it.
• text: A small summary text that is shown on the tile beyond the label.
• image: The path to an image that is shown on the tile. Needs to be a path the rails asset pipeline can handle.
• icon: The name of an icon that is displayed on the tile. This uses font-awesome icons. You only need to pass the name of the icon.
• link: A static link to the target that is called if the user clicks the tile.
• controller: A controller containing the action that is called if the user clicks the tile.
• action: The action of the controller that is called if the user clicks the tile.
• footer: A text shown beyond the tile. Can be used for detailed descriptions.

Every option is optional and only rendered if it is passed.

Create a dashboard manually

If you want to create a dashboard without the generator, you have to create a route, controller, helper and view, as usual.

The route located in config/routes.rb is a default rails route, nothing special:

...
namespace :content do 
 get 'dashboard', to: 'dashboard#index'
end

The controller should inherit from EzOnRails::ApplicationController. This is necessary to provide the necessary helpers, permission system and layout. You can pass a title by overriding the default set_title method. You can also create a sub_title in the action itself. Both are rendered on the top of the page. The following example is namespaced, hence it should be located in app/controllers/content/dashboard_controller.rb.

class Content::DashboardController < EzOnRails::ApplicationController
  # GET content/dashboard
  def index
    @subtitle = t(:content_dashboard_subtitle)
  end

  protected

  # See description of set_title in ApplicationController.
  def set_title
    @title = t(:content_title)
  end
end

The hexample elper file having the dash info that provides the information what tiles should be rendered should be located in app/helpers/content/dashboard_helper.rb. Have a look at the [dash info section](## Dash info) to see what the dash info should return.

module Content::DashboardHelper
  module_function

  def dash_info_content
    ...
  end
end

The view file should be in this case located in app/views/content/dashboard/index.html.slim and should have the following content:

= render partial: 'ez_on_rails/shared/dashboard', locals: {\
    dash_info: dash_info_content,
    borderless: true\
  }

The borderless property here indicates that the tiles should have no borders.

Thats it, now you should see the dashboard by calling your created routed.