navtastic 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f71489809ad37489fff943b48ecc3c00224a7d5d
-  data.tar.gz: 8d52c7216084c2e84d620ae1f94b7464fc4c68ad
+  metadata.gz: f1310ede0cecc3da85ea235b10c6bd7b6413d823
+  data.tar.gz: 7507adc0d81b1e381463fabc7f0a912b24e8b586
 SHA512:
-  metadata.gz: c9a022d6a93b60adbc98dfed4d8fe26b9a9b4d35c6ac1e37a83e9a6c511cd4c021ed15e5fd4cc6871d40c585b032b13e6062c503550d11892fdccf7802d69015
-  data.tar.gz: 6b3678f6e320f10eab9f158845ec34cdb634f0b3babe35fa9c7649dfd907148a348438b6a7febb60bfef866fe185e76fe8225ff3b0b1cf0dc1b251750a9c7b85
+  metadata.gz: fab8bbf0725908f60ecdd76c50709ea4cff88ccbf43ba30f4cd1d6085b03b4e3baeae5bd18ebec37ba19f8dec5e77a5e4a77c78395ec0a44621c0c049ce1749b
+  data.tar.gz: d315fb9dc68df9e0d827b231421684d9b211611b249a69163fa65b95055c797062286a6935144af2246c33e011ff1d9aef3d75e67c6961c48063c312149eb297

data/.rubocop.yml

@@ -6,16 +6,26 @@ AllCops:
     - '**/Rakefile'
   Exclude:
     - 'spec/demo/**/*'
+    - 'spec/support/**/*'
     - 'vendor/**/*'
   TargetRubyVersion: 2.4
 
+Metrics/AbcSize:
+  Max: 20
+
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*_spec.rb'
-    - 'spec/support/matchers/**/*'
+
+Metrics/MethodLength:
+  Max: 15
 
 Style/FrozenStringLiteralComment:
   Enabled: false
 
 Style/StringLiterals:
   Enabled: false
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+  

data/.yardopts

@@ -2,3 +2,4 @@
 --no-private
 -
 LICENSE
+CHANGELOG.md

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.1.0] - 2017-09-05
+
+### Added
+
+- Configuration options
+- Base urls
+- New Renderers: Bootstrap4, Bulma, Foundation 6
+  - Only vertical menus are supported for now
+
 ## 0.0.1 - 2017-08-21
 
 ### Added
@@ -11,4 +20,5 @@
 - Highlighting current menu item
 - Runtime parameters
 
-[Unreleased]: https://github.com/aramvisser/navtastic/compare/v0.0.1...HEAD
+[Unreleased]: https://github.com/aramvisser/navtastic/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.1.0

data/README.md

@@ -3,13 +3,19 @@
 [![Build Status](https://img.shields.io/circleci/project/github/aramvisser/navtastic.svg)](https://circleci.com/gh/aramvisser/navtastic)
 [![Code Coverage](https://img.shields.io/codeclimate/coverage/github/aramvisser/navtastic.svg)](https://codeclimate.com/github/aramvisser/navtastic)
 [![Inline docs](https://inch-ci.org/github/aramvisser/navtastic.svg?branch=master)](https://inch-ci.org/github/aramvisser/navtastic)
+[![Gem](https://img.shields.io/gem/v/navtastic.svg)](https://rubygems.org/gems/navtastic)
 [![MIT License](https://img.shields.io/github/license/aramvisser/navtastic.svg)](https://github.com/aramvisser/navtastic/blob/master/LICENSE)
 
-Navtastic is way to create and render complex navigation menus. It allows for runtime configurations
-of menus.
+Navtastic is way to create and display complex navigation menus for websites. It allows for runtime
+configurations of menus, depending on context.
 
 - Keep menu content and rendering logic separate
 - Automatically highlight the current page
+- Different output structures supported (Simple, Bootstrap4, Bulma, Foundation6)
+  - HTML structure only, bring your own CSS.
+- Easily create your own renderer to fit your style.
+
+_The current renderers only support vertical menus. Horizontal (navbar) menus are planned._
 
 ## Table of Contents
 
@@ -18,7 +24,13 @@ of menus.
 - [Documentation](#documentation)
   - [Submenus](#submenus)
   - [Current item](#current-item)
+  - [Custom classes](#custom-classes)
   - [Runtime parameters](#runtime-parameters)
+  - [Global Configuration](#global-configuration)
+  - [Menu Configuration](#menu-configuration)
+  - [Item Configuration](#item-configuration)
+  - [Renderers](#renderers)
+- [Development](#development)
 
 ## Installation
 
@@ -36,7 +48,7 @@ bundle install
 
 ## Example
 
-Define a menu somwhere:
+Define a menu somewhere:
 
 ```ruby
 Navtastic.define :main_menu do |menu|
@@ -70,9 +82,9 @@ Using the default renderer, assuming that the current url starts with `/posts`,
 
 ## Documentation
 
-## Submenus
+### Submenus
 
-Every item can have a submenu. They can be nested as deeply as you want (or at least until Ruby starts complaining).
+Every item can have a submenu. They can be nested as deeply as you want.
 
 ```ruby
 Navtastic.define :main_menu do |menu|
@@ -117,7 +129,7 @@ For example, if there is a menu containing these urls:
 If the current_url is `/posts/featured/2017`, the `/posts/featured` item will be highlighted. If the
 current_url is `/posts/123`, then `/posts` is highlighted.
 
-The root url `/` will always match, if no other items match the current _url. If there is no item
+The root url `/` will always match, if no other items match the current url. If there is no item
 with `/` as url in the menu and no other urls match, nothing will be highlighted.
 
 ### Runtime parameters
@@ -141,3 +153,131 @@ end
 # Render it with the current user as a parameter
 Navtastic.render :main_menu, current_url, current_user: User.current
 ```
+
+### Global Configuration
+
+Some global settings that Navtastic uses can be configured. Make sure the configuration happens
+before defining any menu (e.g. when using rails, add it to `config/initializers/navtastic.rb`).
+
+These are the defaults values:
+
+```ruby
+Navtastic.configure do |config|
+  # This url to prepend before every item url
+  config.base_url = nil
+
+  # Set the renderer to use, can be one of :simple, :bootstrap4, :bulma, :foundation6
+  # Can also be a class if you want to use a custom renderer
+  config.renderer = :simple
+
+  # Options that are passed to the renderer
+  config.renderer_options = {}
+end
+```
+
+### Menu Configuration
+
+Each individual menu can also be configured in some way:
+
+```ruby
+Navtastic.define :user_menu do |menu, params|
+  # The url to put before every item
+  menu.config.base_url = '/users/' + params[:user_id]
+
+  menu.item "Profile", '/profile' # will link to: /users/123/profile
+end
+```
+
+### Item Configuration
+
+Every item can have options passed to it:
+
+```ruby
+Navtastic.define :menu do |menu|
+  # Add a css class to the container (e.g. <li> tag)
+  menu.item "Home", "/", class: 'highlight'
+
+  # Add a css class the content inside the container (e.g. <a> tag)
+  menu.item "Posts", "/posts", content_class: 'important'
+
+  # If `root` is true, this item will ignore any base urls
+  menu.item "Somewhere", '/', root: true
+
+  # Use the item url as the base_url for the submenu
+  menu.item "Settings", '/settings', base_url: true do |submenu|
+    # submenu.config.base_url is now set to '/settings'
+  end
+end
+```
+
+### Renderers
+
+The following renders are currently available:
+
+- **Simple** adds a `current` class to the basic list structure
+- **Bootstrap4** is used with the [Bootstrap 4](https://getbootstrap.com) framework.
+- **Bulma** is used with the [Bulma.io](http://bulma.io) framework.
+- **Foundation6** is used with the [Foundation 6](http://foundation.zurb.com/sites.html) framework.
+
+Some renderers also support extra options. You can set them globally in the configuration or pass
+them at runtime when rendering a menu:
+
+```ruby
+# Global options
+Navtastic.configure do |config|
+  config.renderer_options = { option: value }
+end
+```
+
+```erb
+# Runtime options
+<%= Navtastic.render :menu, current_url, renderer: { option: value } %>
+```
+
+Globally defined options and options given at runtime are merged together, with those at runtime
+taking precedence.
+
+#### Bulma Configuration
+
+- **headers** (default: `false`)
+
+  Top level items are styled differently. Works best if they are only text, not
+  links.
+
+  <div align="center">
+    <figure>
+      <img src="docs/bulma_headers_preview.png"><br>
+      <figcaption>left: <code>headers: false</code>, right: <code>headers: true</code></legend>
+    </figure>
+  </div>
+
+#### Foundation Configuration
+
+- **active_class** (default: `nil`)
+
+  CSS class to use for active items. Active items are items that have a child that is the current
+  item. Useful to highlight the current item in a drilldown menu.
+
+- **style** (default: `nil`)
+
+  Set to `:drilldown` to generate [a drilldown
+  menu](http://foundation.zurb.com/sites/docs/drilldown-menu.html). Make sure you include the
+  required javascript files.
+
+  <div align="center">
+    <figure>
+      <img src="docs/foundation_styles_preview.png"><br>
+      <figcaption>left: default style, right: drilldown style</figcaption>
+    </figure>
+  </div>
+
+## Development
+
+1. Checkout Repository: `git clone https://github.com/aramvisser/navtastic.git`
+2. Install Bundler: `gem install bundler`
+3. Run `bundle install` inside the project root to install the gem dependencies
+4. Run test cases: `bundle exec rake`
+
+For testing visual changes, a test server is provided by running `bundle exec rake demo`. It's
+accessibly on http://localhost:9090.
+

data/lib/navtastic.rb

@@ -1,6 +1,11 @@
+require 'navtastic/configuration'
 require 'navtastic/item'
 require 'navtastic/menu'
 require 'navtastic/renderer'
+require 'navtastic/renderer/bootstrap4'
+require 'navtastic/renderer/bulma'
+require 'navtastic/renderer/foundation6'
+require 'navtastic/renderer/simple'
 require 'navtastic/version'
 
 # Main module containing some convenience methods
@@ -33,9 +38,16 @@ module Navtastic
 
   # Render a stored menu
   #
+  # The `params` parameter is passed along to the block in {Navtastic.define}.
+  #
+  # If `params` contains a `:renderer` key, it's removed from the hash and
+  # passed to the renderer instead. Look at the renderer documentation to see
+  # which options are supported.
+  #
   # @param name the name of the defined menu
   # @param current_url [String] the url of the current page
   # @param params [Hash] runtime parameters
+  # @option params [Hash] :renderer Options passed to the renderer
   #
   # @raise [KeyError] if the menu was not defined
   #
@@ -46,10 +58,14 @@ module Navtastic
 
     raise KeyError, "menu not defined: #{name.inspect}" if block.nil?
 
+    # Merge renderer options globally with those passed at runtime
+    renderer_options = configuration.renderer_options
+    renderer_options.merge!(params.delete(:renderer) || {})
+
     menu = Menu.new
     block.call(menu, params)
     menu.current_url = current_url
-    Renderer.render(menu)
+    Navtastic.configuration.renderer.render(menu, renderer_options)
   end
 
   # A list of all defined menus

data/lib/navtastic/configuration.rb

@@ -0,0 +1,84 @@
+module Navtastic # :nodoc:
+  # Configuration settings
+  class Configuration
+    # The base url will be prepended to every item url
+    #
+    # Defaults to nil.
+    #
+    # @return [String,nil]
+
+    attr_accessor :base_url
+    # The default renderer to use when displaying a menu
+    #
+    # Defaults to {Navtastic::Renderer::Simple}.
+    #
+    # @return any class that responds to the `.render` method
+    attr_reader :renderer
+
+    # Default options passed to the current renderer
+    #
+    # Defaults to empty Hash.
+    #
+    # @return [Hash]
+    attr_accessor :renderer_options
+
+    def initialize
+      @renderer = Navtastic::Renderer::Simple
+      @renderer_options = {}
+      @base_url = nil
+    end
+
+    # Set the renderer to use for displaying a menu
+    #
+    # @param value [Symbol,Class]
+    def renderer=(value)
+      if value.is_a? Symbol
+        renderers = available_renderers
+
+        unless renderers.key? value
+          raise ArgumentError, "Unknown renderer: #{value}"
+        end
+
+        @renderer = renderers[value]
+      else
+        @renderer = value
+      end
+    end
+
+    private
+
+    # Built in renderers
+    #
+    # @return Hash
+    def available_renderers
+      {
+        bootstrap4: Renderer::Bootstrap4,
+        bulma: Renderer::Bulma,
+        foundation6: Renderer::Foundation6,
+        simple: Renderer::Simple,
+      }
+    end
+  end
+
+  # @return [Navtastic::Configuration] current configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # This will reset the configuration back to defaults
+  def self.reset_configuration
+    @configuration = nil
+  end
+
+  # Modify Navtastic's current configuration
+  #
+  # @example Modify the current configuration
+  #   Navtastic.configure do |config|
+  #     config.setting = :updated
+  #   end
+  #
+  # @yieldparam [Navtastic::Configuration] current Navtastic configuration
+  def self.configure
+    yield configuration
+  end
+end

data/lib/navtastic/item.rb

@@ -1,11 +1,14 @@
 module Navtastic
   # A single menu item
   class Item
+    # @return [Menu] the containing menu
+    attr_reader :menu
+
     # @return [String] the name to be displayed in the menu
     attr_reader :name
 
-    # @return [String,nil] the url to link to if item is a link, nil otherwise
-    attr_reader :url
+    # @return [Hash] extra options to configure individual items
+    attr_reader :options
 
     # @return [Menu,nil] the submenu of this item, if defined
     attr_accessor :submenu
@@ -19,10 +22,12 @@ module Navtastic
     # @param menu [Menu] the menu this items belongs to
     # @param name [String] the name to display when rendering
     # @param url [String] the url to link to, if the item is a link
-    def initialize(menu, name, url = nil)
+    # @param options [Hash] extra configuration options
+    def initialize(menu, name, url = nil, options = {})
       @menu = menu
       @name = name
       @url = url
+      @options = options
 
       @submenu = nil
     end
@@ -37,6 +42,21 @@ module Navtastic
       @menu.current_item == self
     end
 
+    # Check if the item has a current child in its submenu (or deeper)
+    #
+    # Also returns true if this is the current item.
+    #
+    # @see file:README.md#Current_item documentation on how the current item is
+    #   selected
+    #
+    # @return [Bool] if the item is the current item
+    def active?
+      return true if current?
+      return false unless submenu
+
+      submenu.items.any?(&:active?)
+    end
+
     # @return [Bool] true if the item has a submenu, false other
     def submenu?
       !@submenu.nil?
@@ -45,5 +65,26 @@ module Navtastic
     def inspect
       "#<Item \"#{name}\" [#{url}] current?:#{current?}>"
     end
+
+    # Check if item has a link or not
+    #
+    # @return [Bool]
+    def url?
+      !@url.nil?
+    end
+
+    # The url for this item, if the item has a url
+    #
+    # Will prepend the `base_url` for the menu if it is present
+    #
+    # @return [String,nil]
+    def url
+      return nil unless url?
+      return @url if options[:root]
+
+      url = "#{@menu.base_url}#{@url}"
+      url.chomp!('/') unless url == '/'
+      url
+    end
   end
 end