structured_menus 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0bf8638465b18ff55d7769def7e225ec37d0a3e4
-  data.tar.gz: 2e7c8564de3bbf3aa00d68a18452197c01700446
+  metadata.gz: 35fdf0f4c1a6a53ce6cd0cd7a9321b140b7a3b12
+  data.tar.gz: c06806a04da79cd69a6fe72b482429f6a3d64e15
 SHA512:
-  metadata.gz: 6c715ac46996d845698dc886904c00c16a8b27dabfc9978a62fa888eb4106885cea33d22be5f77dfdd4df458781448a91c10d805c3b1970564295eae3cd7e08c
-  data.tar.gz: fc3b254949da858edc0deb1a3e438796f7c144bcf27a2f71688f3799af1dc98f99e9f89493e0a7e1ed1140e7ee4c21f31add909fd459e95ae3f288c630c4b805
+  metadata.gz: 3169ec2a454240abfe33b2c2d8f9de7292ee7f583fab6fd7a27dc63f30e3a3d98f96ab3f3258b4dc546d62951d2d3f532775137ae3096e308a06450864946167
+  data.tar.gz: bce213b07a67fc149d274e8e3b7f252728fa0ef657c2e012ec2b5498439397047e9a15087cc8aebdad93d7157d4541934a02bb7902f0c6736a2a370f545af1d5

data/Gemfile.lock

@@ -0,0 +1,142 @@
+PATH
+  remote: .
+  specs:
+    structured_menus (0.0.1)
+      rails (~> 5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.2.0)
+      actionpack (= 5.2.0)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailer (5.2.0)
+      actionpack (= 5.2.0)
+      actionview (= 5.2.0)
+      activejob (= 5.2.0)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.2.0)
+      actionview (= 5.2.0)
+      activesupport (= 5.2.0)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.0)
+      activesupport (= 5.2.0)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.2.0)
+      activesupport (= 5.2.0)
+      globalid (>= 0.3.6)
+    activemodel (5.2.0)
+      activesupport (= 5.2.0)
+    activerecord (5.2.0)
+      activemodel (= 5.2.0)
+      activesupport (= 5.2.0)
+      arel (>= 9.0)
+    activestorage (5.2.0)
+      actionpack (= 5.2.0)
+      activerecord (= 5.2.0)
+      marcel (~> 0.3.1)
+    activesupport (5.2.0)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    arel (9.0.0)
+    builder (3.2.3)
+    concurrent-ruby (1.0.5)
+    crass (1.0.4)
+    diff-lcs (1.3)
+    erubi (1.7.1)
+    globalid (0.4.1)
+      activesupport (>= 4.2.0)
+    i18n (1.0.1)
+      concurrent-ruby (~> 1.0)
+    loofah (2.2.2)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.0)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.2)
+      mimemagic (~> 0.3.2)
+    method_source (0.9.0)
+    mimemagic (0.3.2)
+    mini_mime (1.0.0)
+    mini_portile2 (2.3.0)
+    minitest (5.11.3)
+    nio4r (2.3.1)
+    nokogiri (1.8.3)
+      mini_portile2 (~> 2.3.0)
+    rack (2.0.5)
+    rack-test (1.0.0)
+      rack (>= 1.0, < 3)
+    rails (5.2.0)
+      actioncable (= 5.2.0)
+      actionmailer (= 5.2.0)
+      actionpack (= 5.2.0)
+      actionview (= 5.2.0)
+      activejob (= 5.2.0)
+      activemodel (= 5.2.0)
+      activerecord (= 5.2.0)
+      activestorage (= 5.2.0)
+      activesupport (= 5.2.0)
+      bundler (>= 1.3.0)
+      railties (= 5.2.0)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
+    railties (5.2.0)
+      actionpack (= 5.2.0)
+      activesupport (= 5.2.0)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.5.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    sprockets (3.7.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (0.20.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    websocket-driver (0.7.0)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  structured_menus!
+
+BUNDLED WITH
+   1.16.0

data/README.md

@@ -2,10 +2,123 @@
 An easy way to create flexible menus for Rails apps.
 
 ## Installation
-TBC
+Add this line to your Gemfile and run `bundle install`:
+
+    gem 'structured_menus'
+    
+Next, create a configuration file in `config/initializers`, probably called `structured_menus.rb` because convention, and add the following to it:
+
+```ruby
+StructuredMenus::Configurator.configure do |config|
+  # You don't have to add anything here, if you like the defaults, but you still need to call `configure`.
+end
+```
+
+## Quick Start
+Once you've done the above, create `app/menus/menu.yml`, and add the following to it:
+
+```yaml
+- name: FAQ
+  icon: question
+  link: /faq
+```
+
+In the view in which you want to display the menu, add this code:
+
+```erb
+<%= Rails.menus.show :menu, :dashboard, current_user %>
+``` 
+
+You can substitute `:dashboard` for `:dropdown` if you want a Bootstrap dropdown menu instead; if you don't have a `current_user` method, use `nil`.
+
+Continue reading for more detailed usage options.
     
 ## Usage
-TBC
+StructuredMenus enables you to create menus for your app by writing YAML files in (by default) `app/menus`. Each file is a menu; each item in the file
+becomes an item on your menu, displayed according to the adapter (more on that later) and options you specify. Such a file might look like this:
+
+```yaml
+- name: Admin
+  icon: cogs
+  link: /admin
+  if: 'lambda { |u| u&.has_role?(:admin) }'
+
+- name: CRM
+  icon: users
+  link: /crm
+
+- name: Orders
+  icon: money-bill-alt
+  link: /orders
+```
+
+Save that as `mymenu.yml`, and you'll be able to call `Rails.menus.show :mymenu, :dashboard, current_user` to pop it up anywhere in your app.
+
+### Adapters
+Adapters are the bits that control how the menu is actually displayed. There are two included by default: `:dashboard` and `:dropdown`. Both are 
+designed to work with Bootstrap and FontAwesome (yes, I'm opinionated). Each adapter supports different options - see the definitions in 
+`lib/structured_menus/adapters` for details on what they are.
+
+ - **Dashboard** is designed to be a full-screen main menu type thing, probably for apps with lots of navigation. The example menu YAML shown above
+   looks like this when shown (some custom CSS - the topbar is not part of the menu):
+   
+   [![](https://i.stack.imgur.com/n0sbQ.png)](https://i.stack.imgur.com/n0sbQ.png)
+   
+   Use `:dashboard` in your call to `Rails.menus.show` to get this adapter.
+   
+ - **Dropdown** is, well, a Bootstrap dropdown menu. It doesn't include icons by default, but you can make it do so if you want them. The same YAML
+   looks like this with the dropdown adapter:
+   
+   [![](https://i.stack.imgur.com/rc1Ww.png)](https://i.stack.imgur.com/rc1Ww.png)
+   
+   Use `:dropdown` in your call to `Rails.menus.show` to get this adapter.
+   
+#### Custom adapters
+If those two don't suit your needs, you can write your own custom adapter. Essentially, this needs to emulate one of the two stock adapters, in that:
+
+ - It must respond to `#show`
+ - Calls to `#show` must respond with the string of raw HTML that you want to render.
+ 
+For reference, here's what the dashboard adapter looks like:
+
+```ruby
+module StructuredMenus::Adapters
+  class DashboardAdapter
+    include ActionView::Helpers::UrlHelper
+    include ActionView::Helpers::OutputSafetyHelper
+    
+    def self.show(menu, user, **options)
+      inst = new
+      width = options[:width] || 4
+      cards = menu.map do |i|
+        next unless !i['if'] || instance_eval(i['if']).call(user)
+
+        cls = options[:class] || 'dashboard-menu-card'
+        inst.raw("<div class=\"#{cls}\">#{inst.link_to inst.raw("<i class=\"fas fa-#{i['icon']}\"></i> #{i['name']}"), i['link']}</div>")
+      end.compact
+
+      inst.raw(cards.in_groups_of(12 / width).map(&:compact).map do |g|
+        '<div class="row">' + g.map { |c| "<div class=\"col-md-#{12 / width}\">#{c}</div>" }.join("\n") + '</div>'
+      end.join("\n"))
+    end
+  end
+end
+```
+
+The parameters that will be passed to `#show` are as follows:
+
+ - `menu` - a parsed YAML file, in the form of an array. Each element is a hash representing a single menu item as specified in the file.
+ - `user` is the value passed to `Rails.menus.show`, which should be a reference to the current user. This can be `nil`.
+ - `**options` is a hash of additional options - it's up to you what you want to support. Look at the adapter files in `lib/structured_menus/adapters`
+   to see the options that the stock adapters support.
+   
+Once you've written your adapter, tell structured_menus about it by adding it to the configuration file:
+
+```ruby
+StructuredMenus::Configurator.configure do |config|
+  config.adapters << YourCustomAdapterClass
+end
+```
 
 ## Contributions
 Welcome. Ping me a PR. For large changes you should probably open an issue first to discuss.

data/lib/structured_menus/adapters/dashboard_adapter.rb

@@ -20,7 +20,7 @@ module StructuredMenus::Adapters
         inst.raw("<div class=\"#{cls}\">#{inst.link_to inst.raw("<i class=\"fas fa-#{i['icon']}\"></i> #{i['name']}"), i['link']}</div>")
       end.compact
 
-      inst.raw(cards.in_groups_of(12 / width).map(&:compact).map do |g|
+      inst.raw(cards.in_groups_of(width).map(&:compact).map do |g|
         '<div class="row">' + g.map { |c| "<div class=\"col-md-#{12 / width}\">#{c}</div>" }.join("\n") + '</div>'
       end.join("\n"))
     end

data/lib/structured_menus/version.rb

@@ -1,3 +1,3 @@
 module StructuredMenus
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.0.2'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: structured_menus
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - ArtOfCode-
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-29 00:00:00.000000000 Z
+date: 2018-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -76,6 +76,7 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - lib/structured_menus.rb