Helmsman
Installation
Add this line to your application's Gemfile:
gem 'helmsman'
And then execute:
$ bundle
Usage
Helmsman adds the helm
helper to your rails application views. Here is how you use it:
helm :pictures, url: 'http://defiant.ncc/pictures'
The above call will produce the following html output
<li>
<a href='http://defiant.ncc/pictures'>Pictures</a>
</li>
Building the link
There are multiple ways to build the link:
- Provide the url parameter. The link will then be build by using the translation and that url.
helm :pictures, url: 'http://randompictures.com'
- Set helm values in a block. (This works for name and url only.)
helm :pictures do |entry|
entry.name = 'Some pictures'
entry.url = 'http://randompictures.com'
end
- Build everything manually
helm :pictures do |_|
link_to 'Some pictures', 'http://randompictures.com'
end
Translation lookup
The first parameter will be used to lookup the translations.
e.g. helm :edit
called from app/views/pictures/_menu.html.*
uses the following translations
- en.pictures.menu.edit
- en.pictures.menu.edit_disabled_tooltip
- en.pictures.menu.disabled_tooltip
Translation scope
To wrap a group of navigation elements into the same translation namespace use the helm_i18n_scope
method:
helm_i18n_scope 'bridge' do
helm :sensors # will use 'bridge.sensors' for translation lookup
end
Highlight current
Helmsman will highlight the current entry by using the controller and action name.
Per default the first parameter will be treated as the controller name: helm :pictures, url: pictures_url
highlights on every controller action of the pictures_controller.
You may customize the highlight options by providing a set of controller and/or action names in the highlight
options. Here are some examples:
helm :bridge, highlight: :screens # on any screens controller action
helm :bridge, highlight: [:screens, :sensors] # on any screens and sensors controller action
helm :bridge, highlight: { screens: :show } # on bridges controller show action
helm :bridge, highlight: [:screens, { sensors: [:show, :index] }] # all screens controller actions and sensors controller #show and #index
Anyway you are not forced to use that mechanism, you can also set current
by hand:
helm :bridge, current: true
Disabling and visibility
To set a helm disabled you may use the disabled
option. It will then add a tooltip to that entry to explain why it was disabled (´.pictures_disabled_tooltip´).
helm :pictures, url: pictures_url, disabled: user_signed_in?
If you want it to not be visible at all set the visible
option to false.
helm :pictures, url: pictures_url, visible: user_signed_in?
Additional content and nesting
As mentioned above you may additional content and nest helms into each other by using its yield feature. Here is a SLIM example:
- helm :pictures, url: 'http://allpictures.com' do
ul
= helm :architecture
= helm :nature
You can always use the current helm during that yield, so finding out whether it is disabled, current or anything is trivial:
helm :pictures, disabled: true, current: false do |entry|
puts entry.enabled? # false
puts entry.disabled? # true
puts entry.visible? # true
puts entry.current? # false
end
Configuration
In an initializer you can customize the css classes to use.
Helmsman.current_css_class = 'current-menu-item'
Helmsman.disabled_css_class = 'disabled-menu-item'
Compatibility
Helmsman is working for rails 3 & 4 and needs ruby 2
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
TODO
- configure helper name