jekyll_icon_list 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f1da75e2e118c485c03c07af94262febe7aefe650715dbc72db46802a739594
-  data.tar.gz: 2f6185d3706196a24b561dd317e39ff45230690e2a3fb850730cc3448e632334
+  metadata.gz: 0f7ccfa6a8c94144f4a58982b651c553eb65976cf28b503f15b1f8efc9bb3bda
+  data.tar.gz: d4c30318fe1977bc2b5828871fe40d8faa902aa1323a9eea298111e3ac2a7932
 SHA512:
-  metadata.gz: 9b62e7b479c2a44e29e605d96e4121d5cd06cc8f354613123e6c83a56b50c39887d483cf443b0b8b66d50a1a7dd09084267d37af33d4553050b673397d38805c
-  data.tar.gz: 91991f9474658ba39c33012cfe0325f1c516e6d367e4824dcb0eb4c2852b0c9d5742cc07118df8822904b01d0ee8eaf08356a9188dd2cb969a5ad5ee6d5971ce
+  metadata.gz: 5b78191361e1968ddac22c8d25309de2015414f7dc271b7c738ff235520400b13103096087853496378bdf61c1a83cd36092cdab77a50a9fe201f5be9b6a02fd
+  data.tar.gz: 34092df630e9c3dfffb019ff0439ecf6f403dce6930e46a3d8eb55634d836f628540d1f6948cfbf166eb1789832325d116836150b5652034b8dfb0dba9a7fe34

data/.gitignore

@@ -7,3 +7,4 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
+*.gem

data/README.md

@@ -8,12 +8,12 @@ report bugs if you find them.**
 It's a jekyll tag that lets you build unordered lists of items that follow the "Icon + label"
 format.
 
-Write a tag like this: 
+Write this: 
 ```
 {% icon_list rails bootstrap heroku aws %}
 ```
 
-Add some icons, configuration, and a little CSS, and you get something like this: 
+Add some icons, configuration, and a little CSS, get something like this: 
 
 ![imgur screenshot]( https://i.imgur.com/9m6qCRB.png )
 
@@ -27,20 +27,20 @@ markup; the styling is up to you.
 
 It integrates with (and requires) [jekyll-svg-inliner](https://github.com/sdumetz/jekyll-inline-svg)
 to inline your SVGs for you. If you don't use inline SVGs (even though you should), it sets your file
-as an img src attribute (with alt text!).
+as the `src=` of an `img` tag.
 
 ## Installation
 
-(I don't have it hosted on rubygems yet. It will be once I've cleaned it up a bit further. .)
-
 ```ruby
 # Gemfile
 
 group :jekyll_plugins do
-  gem 'jekyll_icon_list', git: 'https://github.com/rbuchberger/jekyll_icon_list.git'
+  gem 'jekyll_icon_list'
 end
 ```
 
+`bundle install`
+
 ```yml
 # _config.yml
 
@@ -48,65 +48,73 @@ plugins:
   -jekyll_icon_list
 ```
 
-You'll also want some css. Here's an example that should get you close to the screenshot:
-```css
-
-ul.icon-list {
-  margin: 0;
-  font-size: 1.1em;
-  display: flex;
-  flex-wrap: wrap;
-  justify-content: center;
-  list-style: none;
-}
-
-ul.icon-list li {
-    display: flex;
-    align-items: center;
-    margin: 0 .5em;
-}
-
-.icon {
-  height: 1em;
-  margin-right: .2em;
-}
+## Basic Usage
 
 ```
-
-## Usage
-
-Basic usage: 
-
-```
-{% icon_list example_shortname example2 %}
+{% icon_list example example2 example3 %}
 ```
 
 By default, with no configuration:
 
 * It will look for icons in images/icons/ with the same name as your shortname, grabbing the first result which matches (shortname).*
 
-* It will take your shortname, swap dashes for spaces, and titleize it for the label.
+* It will take your shortname, swap dashes and underscores for spaces, and titleize it for the label.
 
-So for example, if you write `{% icon_list ruby-on-rails %}`, with `ruby-on-rails.png` located in
+Example: if you write `{% icon_list ruby-on-rails %}`, with `ruby-on-rails.png` located in
 `images/icons/`, it will generate markup like this:
-```
+```html
 <ul>
   <li><img src="/images/icons/ruby-on-rails.png">Ruby On Rails</li>
 <ul>
 ```
 
-You can specify attributes to add with --(element) arguments: 
+You can add HTML attributes with --(element) arguments: 
 ```
-{% icon_list example example2 example3 --ul class="stumpy" --li class="mopey" %}
-
+{% icon_list example --ul class="stumpy" --li class="mopey" data-max-volume="11" %}
+```
+Which will generate markup like this:
+```html
+<ul class="stumpy">
+  <li class="mopey" data-max-volume="11"><svg>(...)</svg>Example</li>
+</ul>
 ```
 
 Available arguments:
 `--ul, --li, --img, --svg, --a`
 These will overwrite any global defaults you have set.
 
-in your \_config.yml there are a few optional settings you can add. Here's an example:
+## Less Basic Usage
+If the default filenames and labels don't work for you, create:
+`/_data/icon_list.yml`
+
+And fill it with your icons in the following format: 
+```yml
+# /_data/icon_list.yml
+
+example1:
+  icon: example_logo.svg 
+  label: My Nicely Formatted, Long Name
+  url: https://example1.com
+example2:
+  icon: sloppy.svg
+  label: Here's Another Label I Don't Have To Type Again
 ```
+
+Each key is an item shortname, and everything is optional. `icon:` is the filename of the icon you
+would like to use, which will be prepended by your default_path if you set one (more on that later).
+
+If you set a `url:`, it'll wrap the `<li>` contents in an anchor tag.
+
+## Configuration
+
+* All of icon_list's configuration is under the `icon_list:` key in \_config.yml
+* `default_path:` - Where to find your icons
+* `defaults:` - Optional HTML attributes to include with your markup. They will be ignored if
+    a corresponding --(element) argument is passed in the tag.
+
+Here's an example configuration:
+
+```yml
 # _config.yml
 
 icon_list:
@@ -123,36 +131,86 @@ svg:
 
 ```
 
-* `default_path:`- Prepended to the filenames specified in your data file.
-* `defaults:` - Optional HTML attributes to include with your markup, if none are specified in the
-    tag.
+## Notes
 
-If the default filenames and labels don't work for you, create:
-`/_data/icon_list.yml`
+### Icon finding logic 
 
-And fill it with your icons in the following format: 
+It tries to be smart about finding your icons. Here's the decision  matrix:
+
+...               | default_path set    | default_path not set
+------------------|---------------------|---------------------
+item icon set     | default_path + icon | icon
+item icon not set | search default_path | search /images/icons
+
+When it searches a path, it just spits out the first result and raises an exception if there aren't
+any.
+
+### Accessibility
+Right now the only way to set individualized alt text for your icons is to use SVGs, and include a
+title tag in the file. Since the label itself will likely describe your image quite nicely, I
+recommend you set `alt=""` as a default attribute for image tags.
+
+If you would like automatic alt-text generation, or the ability to specify alt text in the data
+file, let me know or write it yourself and submit a pull request.
+
+### Styling
+Here's an example that should get you close to the screenshot:
+
+```css
+ul.icon-list {
+  margin: 0;
+  font-size: 1.1em;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  list-style: none;
+}
+
+ul.icon-list li {
+    display: flex;
+    align-items: center;
+    margin: 0 .5em;
+}
+
+.icon {
+  height: 1em;
+  margin-right: .2em;
+}
 ```
-# /_data/icon_list.yml
 
-example1:
-  icon: example_logo.svg 
-  label: My Nicely Formatted, Long Name
-  url: https://example1.com
-example2:
-  icon: sloppy.svg
-  label: Here's Another Label I Don't Have To Type Again
+### Using <use> To build an icon system
+[CSS tricks on SVG Icon Systems (old article warning)](https://css-tricks.com/svg-sprites-use-better-icon-fonts/)
+
+[Slightly newer article on <use>](https://css-tricks.com/svg-use-with-external-reference-take-2/)
+
+[MDN docs](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use)
+
+You can do it while using this plugin, but it's not remarkably efficient; build
+& inject the reference file on your own, and then write your SVG files like
+this:
+
+```html
+<!-- example-name.svg -->
+<svg>
+	<use href="#example-icon">
+</svg>
 ```
 
-The default directory setting in config.yml will be prepended to your
-filenames. You'll obviously need some icons, I hear you can find them on the
-internet.
+At this point the dependency on jekyll-svg-inliner gets pretty tenuous; do we
+really need a plugin and an extra file to render 3 lines of simple code? In the
+future I'd like to streamline this.
 
-If you set a url: for an item in the data file, it'll wrap the li's contents in
-an anchor tag for you.
+### Liquid variables
+
+You can't pass in liquid variables yet. It's on the to-do list.
 
 ## Contributing
 
 Bug reports and pull requests are welcome. https://github.com/rbuchberger/jekyll_icon_list
+Contact: robert@robert-buchberger.com
+
+I've been using rubocop with the default settings, and would appreciate if pull requests did the
+same.
 
 ## License
 

data/jekyll_icon_list.gemspec

@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rake', '~> 10.0'
 
   spec.add_dependency 'jekyll-inline-svg'

data/lib/jekyll_icon_list/version.rb

@@ -1,3 +1,3 @@
 module JekyllIconList
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/jekyll_icon_list.rb

@@ -14,11 +14,6 @@ module JekyllIconList
   # --ul, --li, --svg, and --img. Their arguments are inserted into their
   # respective HTML elements upon render.
   class IconList < Liquid::Tag
-    # \.     -  dot
-    # [\w]+  -  One or more letters, numbers, or underscores
-    # $      -  End of string
-    FILE_EXT_REGEX = /\.([\w]+)\z/
-
     def initialize(tag_name, raw_input, tokens)
       @raw_input = raw_input
       @tokens = tokens
@@ -26,6 +21,9 @@ module JekyllIconList
     end
 
     def initialize_attributes
+      # We will be interpolating strings with these values several times, so
+      # initializing them with empty strings is convenient.
+
       {
         'ul' => '',
         'li' => '',
@@ -35,82 +33,64 @@ module JekyllIconList
       }
     end
 
-    def attribute_defaults
-      attributes = initialize_attributes
+    def set_attribute_defaults
+      @attributes = initialize_attributes
 
-      attributes.each_key do |k|
-        if @li_settings['defaults'] && @li_settings['defaults'][k]
-          attributes[k] = @li_settings['defaults'][k].dup
+      @attributes.each_key do |k|
+        if @icon_list_settings['defaults'] && @icon_list_settings['defaults'][k]
+          @attributes[k] = @icon_list_settings['defaults'][k].dup
         end
       end
-
-      attributes
     end
 
-    def parse_input(raw_input)
+    def parse_input
       # raw_input will look something like this:
-      # 'item1 item2 item3 --ul attribute="value" --(...) "'
+      # 'item1 item2 item3 --ul attribute="value" --(...)'
 
-      raw_input_array = raw_input.split('--').map { |i| i.strip.split(' ') }
+      raw_input_array = @raw_input.split('--').map { |i| i.strip.split(' ') }
       # [['item1', 'item2', 'item3'], ['ul', 'attribute="value"'], (...) ]
 
       @item_shortnames = raw_input_array.shift
 
-      raw_input_array.each do |a|
-        key = a.shift
-        @attributes[key] = a.join ' '
-      end
+      raw_input_array.each { |a| @attributes[a.shift] = a.join ' ' }
     end
 
     def build_image_tag(icon_filename)
-      file_ext = FILE_EXT_REGEX.match(icon_filename)[1]
-
-      element = if file_ext == 'svg'
-                  Jekyll::Tags::JekyllInlineSvg.send(
-                    :new,
-                    'svg',
-                    "#{icon_filename} #{@attributes['svg']}",
-                    @tokens
-                  ).render(@context)
-                else
-                  "<img src=\"#{icon_filename}\" "\
-                    "alt=\"icon for #{icon_data['label']}\" "\
-                    "#{@attributes['img']}>"
-                end
-
-      element << "\n"
+      if icon_filename.split('.').pop.casecmp('svg')
+        Jekyll::Tags::JekyllInlineSvg.send(
+          :new,
+          'svg',
+          "#{icon_filename} #{@attributes['svg']}",
+          @tokens
+        ).render(@context)
+      else
+        "<img src=\"#{icon_filename}\" #{@attributes['img']}>"
+      end
+    end
+
+    def search_path(path, item)
+      search_results = Dir.glob(Dir.pwd + path + item + '.*')
+      raise "No icon found at #{path + item} .*" unless search_results.any?
+
+      # Returns the first matching result. May improve in the future:
+      search_results.first
     end
 
     def find_icon(item_shortname, this_item_data)
-      # This line gave me an interesting bug: jekyll data files are apparently
-      # mutable and persistent between tag calls. If I had the same item
-      # multiple times on a page (which is the entire point of this plugin), the
-      # default path would be prepended each time. .dup is very important!
-      icon_data_filename = this_item_data['icon'].dup
-      default_path = @li_settings['default_path'] || '/images/icons/'
-
-      if icon_data_filename && default_path
-        default_path + icon_data_filename
-      elsif icon_data_filename
-        icon_data_filename
-      elsif default_path
-        f = Dir.glob(Dir.pwd + default_path + item_shortname + '.*')
-        unless f.any?
-          raise "No icon for #{item_shortname} set in _data/icon_list.yml"\
-          ", and default filename #{default_path + item_shortname}.* not found"
-        end
+      icon_filename = this_item_data['icon']
+      path = @icon_list_settings['default_path'] || ''
 
-        f.first # Returns the first matching result. May improve in the future
+      if icon_filename
+        path + icon_filename
       else
-        raise "No icon for #{item_shortname} specified in _data/icon_list.yml"\
-          'And no default directory specified in _config.yml.'\
-          'Must have one, the other, or both.'
+        path = '/images/icons/' if path.empty?
+        search_path(path, item_shortname)
       end
     end
 
     def build_label(shortname, this_item_data)
       this_item_data['label'] ||
-        shortname.split('-').map(&:capitalize).join(' ')
+        shortname.split(/[-_]/).map(&:capitalize).join(' ')
     end
 
     def build_li(this_item_data, icon_location, label)
@@ -121,7 +101,7 @@ module JekyllIconList
       li << build_image_tag(icon_location)
       li << label
       li << '</a>' if this_item_data['url']
-      li << '</li>'
+      li << '</li>\n'
     end
 
     def build_html(all_items_data)
@@ -146,13 +126,13 @@ module JekyllIconList
       site_settings = @context.registers[:site]
       raise 'could not load website configuration data' unless site_settings
 
-      @li_settings = site_settings.config['icon_list'] || {}
+      @icon_list_settings = site_settings.config['icon_list'] || {}
 
       all_items_data = site_settings.data['icon_list'] || {}
 
-      @attributes = attribute_defaults
+      set_attribute_defaults
 
-      parse_input(@raw_input)
+      parse_input
 
       build_html(all_items_data)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_icon_list
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Robert Buchberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-22 00:00:00.000000000 Z
+date: 2018-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement