User interface customization

These are instructions for the latest Private eazyBI version 4.0.

Here is described how you can customize private eazyBI user interface for your organization-specific needs. More advanced customization techniques require some knowledge of Ruby programming language and Ruby on Rails framework.

On this page:

Layout and view templates

If you would like to customize the general layout of all pages then you need to customize layout templates. If you would like to customize one particular page then you need to customize particular view template for this page. Customized layout and view templates should be placed in app/views directory subdirectories in the Private eazyBI main directory. Layout and view templates are using the HAML templating language.

To see the list of typical layout and view templates that you would like to customize, execute the following command from private eazyBI directory:

jar tvf eazybi_private.jar -C rails_root app/views

If you would like to customize e.g. general layout file app/views/layouts/application.html.haml then extract it with command

jar xvf eazybi_private.jar -C rails_root app/views/layouts/application.html.haml
mkdir -p app/views/layouts
mv rails_root/app/views/layouts/application.html.haml app/views/layouts/
rm -r rails_root

and then you can modify extracted file in the app/views/layouts directory.

By default if you modify template file then you need to restart private eazyBI server to see changes. If you would like to see changes immediately after page refresh you need to start your private eazyBI in development more. In your bin/start.sh file locate RAILS_ENV variable and change it to development.

If you want to see list of additional view templates that can be customized (that are shared with eazybi.com version of eazyBI) then use command:

jar tvf eazybi_private.knob -C rails_root vendor/gems/eazybi/app/views

If you extract some of these templates then after extraction you need to move them from the vendor/gems/eazybi/app/views directory to the app/views directory.

Stylesheets, images, and JavaScript files

If you need additional static asset files (stylesheets, images or JavaScript files) in your private eazyBI installation (e.g. if you reference them in your customized layout or view templates) then you need to create the directory public in private eazyBI directory. It is recommended to place any eazyBI specific static asset files in the public/eazybi directory as then also all your asset files will have /eazybi URL path prefix as all other eazyBI requests.

E.g. if you have created your custom custom_logo.png image file then place it in the public/eazybi/images/custom_logo.png location and then in your layout template or in a stylesheet reference it as /eazybi/custom_logo.png.

If you need to add a custom stylesheet file then place this file in the public/eazybi/stylesheets directory (e.g. a custom.css file) and then create the app/views/layouts/_custom_head.html.haml file and include the following line in it:

= custom_stylesheet_link "custom"

Please see an example how to add new custom chart type JavaScript files to Private eazyBI.

Custom controllers, helpers, models, and routes

This customization requires Ruby on Rails framework knowledge.

If you would like to add custom controllers, helpers, mailers and models to your private eazyBI application then you can place them in app/controllers, app/helpers, app/mailers and app/models directories as well as create views for these controllers in the app/views directory. In addition, you can add custom initializers in the config/initializers directory.

See customization examples of model classes or an example of a custom contact support helper.

To add custom routes for these new controllers create the config/routes.rb file with the following content:

Rails.application.routes.append do
  # add your custom routes here
end

Please use append method (and not draw) in the first line which will add new (and not replace all existing) routes.

If you would like to modify some default routes then you can also use the prepend method to define different handling of specific URLs. For example, use the following config/routes.rb to redirect all unauthenticated users from default home page to login page:

Rails.application.routes.prepend do
  unauthenticated :user do
    get "#{EazybiPrivate.prefix}/" => redirect("#{EazybiPrivate.prefix}/login")
  end
end

Change eazyBI URL prefix

By default all Private eazyBI URLs start with a /eazybi prefix - it can be used when Private eazyBI is put behind frontend web server which can proxy all requests which start with this prefix to Private eazyBI backend server but requests with other URLs it will proxy to other backend servers.

If necessary, the default /eazybi prefix can be changed to a different one. In the startup script (bin/start.sh or other which is used) uncomment and set the EAZYBI_PREFIX environment variable, e.g.

export EAZYBI_PREFIX=/bi

To remove the /eazybi prefix at all set this environment variable to an empty string:

export EAZYBI_PREFIX=""

Customize Map chart vector maps

If you are using the Map chart then you can configure in eazybi.toml which maps will be available in the Select map selection list. See the vector_maps section in config/eazybi.toml.sample for list of example maps included in Private eazyBI.

You can add your own additional vector maps to this selection as well. See the list of included maps in eazybi_private.jar with

jar tvf eazybi_private.jar -C rails_root public/eazybi/vector-maps

You can create additional maps from jVectorMap library maps by changing them to the eazyBI JSON format. Add new custom maps in the public/eazybi/vector-maps directory and add them to the vector_maps list in the eazybi.toml file.