RubyGems - jekyll-gallery-plugin - Versions diffs - 1.0.0 - Mend

jekyll-gallery-plugin 1.0.0

Files changed (22) hide show

checksums.yaml +7 -0
data/.rspec +3 -0
data/.rubocop.yml +36 -0
data/CODE_OF_CONDUCT.md +84 -0
data/Gemfile +12 -0
data/Gemfile.lock +117 -0
data/LICENSE +674 -0
data/README.md +151 -0
data/Rakefile +12 -0
data/jekyll-gallery-plugin.gemspec +41 -0
data/lib/jekyll/gallery/config.rb +42 -0
data/lib/jekyll/gallery/helper.rb +45 -0
data/lib/jekyll/gallery/seo.rb +31 -0
data/lib/jekyll/gallery/tags.rb +71 -0
data/lib/jekyll/gallery/utils.rb +73 -0
data/lib/jekyll/gallery/version.rb +7 -0
data/lib/jekyll/gallery.rb +12 -0
data/lib/jekyll-gallery-gallery.html +3 -0
data/lib/jekyll-gallery-image.html +12 -0
data/lib/jekyll-gallery-plugin.rb +3 -0
data/sig/jekyll/gallery/plugin.rbs +8 -0
metadata +88 -0

data/README.md ADDED Viewed

@@ -0,0 +1,151 @@
+# Jekyll-Gallery
+This is a Jekyll plugin that provides a Liquid tag to render one of the named named galleries declared
+in the Front Matter inside the content, using a customizable template which, out of the bo, supports the
+Javascript [Glightbox library][glightbox].
+It also takes care of the gallery integrity at the compile time:
+- checking for the *file* field presence;
+- checking for the files presence within the related path.
+Everytime one of these constraints is broken, an error message is raised, blocking any further action.
+As an extra feature, the filesystem organization-and-check supports the *image* field declared for the
+[Jekyll-Seo-Tag plugin][seotag] implementing the subkey *cover*.
+[![Ruby](https://github.com/fabiomux/jekyll-gallery-plugin/actions/workflows/main.yml/badge.svg)][wf_main]
+[![Gem Version](https://badge.fury.io/rb/jekyll-gallery-plugin.svg)][gem_version]
+## Installation
+Can install the gem either manually or using *Bundler*.
+### Using Bundler
+Install the gem and add to the application's Gemfile by executing:
+    $ bundle add jekyll-gallery-plugin --group jekyll_plugins
+### Manually
+If bundler is not being used to manage dependencies, install the gem by executing:
+    $ gem install jekyll-gallery-plugin
+Then, add the following code within the Gemfile of your Jekyll project:
+```ruby
+group :jekyll_plugins do
+  ...
+  gem 'jekyll-gallery-plugin'
+end
+```
+## Configuration
+Inside the `_config.yml` file can set up the following fields:
+```yaml
+jekyll-gallery:
+  assets_path: assets/images
+  collections_dir:
+    posts: posts
+    downloads: downloads
+    ...
+```
+The assigned values are the default values.
+*assets_path*
+: This is the general path where assets lie, these files will be directly served by Jekyll so you will
+  have this same prefix path in your images as well.
+*collections_dir*
+: This is where can specify a folder name for each collection, by default it takes the slug of the
+  collection itself.
+Within the default template must add the code to recall the Glightbox CSS and Javascript scripts, the
+instructions are pretty standard:
+1. The CSS file goes in the *head* section
+2. The Javascript library file in before the *body* closing tag
+3. The Javascript code before the *body* tag and after the previous mentioned Javascript library
+Here an example using the CDN resources:
+```html
+<html>
+    <head>
+        <meta charset="utf-8" >
+        ...
+        <!-- (1) -->
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css" />
+        ...
+    </head>
+    ...
+    <!-- (2) -->
+    <script src="https://cdn.jsdelivr.net/gh/mcstudios/glightbox/dist/js/glightbox.min.js"></script>
+    <!-- (3) -->
+    <script type="text/javascript">
+        const lightbox = GLightbox();
+    </script>
+</html>
+```
+## Usage
+The usage of this plugin is splitted in two parts:
+1. The Front Matter to declare the galleries;
+2. the content, placing the *gallery* tag to render the gallery declared.
+So to declaration will be something like:
+```yaml
+gallery:
+  gallery_name_1:
+  - file: subfolder_1/image_name_1.jpg
+    title: "Title 1"
+    description: "Description 1"
+  - file: subfolder_1/image_name_2.jpg
+    title: "Title 2"
+    description: "Description 2"
+  - file: subfolder_1/image_name_3.jpg
+    title: "Title 3"
+    description: "Description 3"
+  gallery_name_2:
+  - file: subfolder_2/image_name_1.jpg
+    title: "Title 1"
+    description: "Description 1"
+```
+Each gallery has a *name* that introduces the list of items (*gallery_name_1*, *gallery_name_2*), each
+items must provide the *file* field with the relative path, a *title* and a *description*
+Supposing we are filling a *posts* content, and using all the default values, the images will take place
+under the *assets/images/posts/subfolder_1/...* and *assets/images/posts/subfolder_2/...* following the
+scheme:
+    <assets_path>/<collections_dir>/<image_folder_and_filename>
+To render the gallery in whatever point within the content:
+    {% gallery name='<gallery_name>' %}
+For example to render the second gallery:
+```liquid
+{% gallery name='gallery_name_2' %}
+```
+## More Help
+More info is available at:
+- the [project page on the Freeaptitude blog][project_page];
+- the [Jekyll-Gallery Github wiki][jekyll_gallery_wiki];
+- the [Glightbox README page][glightbox_readme].
+[glightbox]: https://biati-digital.github.io/glightbox/ "Glightbox Javascript plugin Home page"
+[glightbox_readme]: https://github.com/biati-digital/glightbox#usage "Glightbox README page - Usage"
+[seotag]: https://github.com/jekyll/jekyll-seo-tag "Jekyll-Seo-Tag Github repository"
+[wf_main]: https://github.com/fabiomux/jekyll-gallery-plugin/actions/workflows/main.yml
+[gem_version]: https://badge.fury.io/rb/jekyll-gallery-plugin
+[project_page]: https://freeaptitude.altervista.org/projects/jekyll-gallery.html "Project page on the Freeaptitude blog"
+[jekyll_gallery_wiki]: https://github.com/fabiomux/jekyll-gallery-plugin/wiki "Jekyll-Gallery wiki page on GitHub"

data/Rakefile ADDED Viewed

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+task default: %i[spec rubocop]

data/jekyll-gallery-plugin.gemspec ADDED Viewed

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require_relative "lib/jekyll/gallery/version"
+Gem::Specification.new do |spec|
+  spec.name = "jekyll-gallery-plugin"
+  spec.version = Jekyll::Gallery::VERSION
+  spec.authors = ["Fabio Mucciante"]
+  spec.email = ["fabio.mucciante@gmail.com"]
+  spec.summary = "Customizable Jekyll plugin that renders a gallery using the GLightbox Javascript library."
+  spec.description = "It applies a gallery template and checks for the files listed presence."
+  spec.homepage = "https://freeaptitude.altervista.org/projects/jekyll-gallery.html"
+  spec.required_ruby_version = ">= 2.6.0"
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/fabiomux/jekyll-gallery-plugin"
+  spec.metadata["changelog_uri"] = "https://freeaptitude.altervista.org/projects/jekyll-gallery.html#changelog"
+  spec.metadata["wiki_uri"] = "https://github.com/fabiomux/jekyll-gallery-plugin/wiki"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_dependency "jekyll", ">= 3.7", "< 5.0"
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/jekyll/gallery/config.rb ADDED Viewed

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+module Jekyll
+  module Gallery
+    #
+    # Configurations required across the gem.
+    #
+    class Config
+      def self.gconfig
+        @@gconfig ||= Jekyll.configuration.freeze
+      end
+      def self.base_url
+        @@base_url ||= gconfig["base_url"].freeze
+      end
+      def self.url
+        @@url ||= gconfig["url"].freeze
+      end
+      def self.source
+        @@source ||= gconfig["source"].freeze
+      end
+      def self.config
+        @@config ||= gconfig["jekyll-gallery"].freeze
+      end
+      def self.selector
+        @@selector ||= (config["post_selector"] || "include.post").freeze
+      end
+      def self.a_path
+        @@a_path ||= (config["assets_path"] || "assets/images").freeze
+      end
+      def self.c_paths
+        @@c_paths ||= (config["collections_dir"] || {}).freeze
+      end
+    end
+  end
+end

data/lib/jekyll/gallery/helper.rb ADDED Viewed

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module Jekyll
+  module Gallery
+    #
+    # Contains the methods that assist the code creation.
+    #
+    module Helper
+      def template(tpl, gcfg)
+        file = File.join(Dir.pwd, gcfg["includes_dir"], "jekyll-gallery-#{tpl}.html")
+        return file if File.exist? file
+        File.expand_path(File.join(__dir__, "..", "..", "jekyll-gallery-#{tpl}.html"))
+      end
+      def self.collection_path(collection)
+        Config.c_paths[collection.to_s] || collection.to_s
+      end
+      def self.expand_remote_file(file, collection)
+        base_path = Config.base_url
+        a_path = Config.a_path
+        if file =~ /\|/
+          c, f = file.split("|")
+          return [base_path, a_path, collection_path(c), f].join("/")
+        end
+        [base_path, a_path, collection_path(collection), file].join("/")
+      end
+      def self.expand_local_file(file, collection)
+        a_path = Config.a_path
+        source = Config.source
+        if file =~ /\|/
+          c, f = file.split("|")
+          return File.join(source, a_path, collection_path(c), f)
+        end
+        File.join(source, a_path, collection_path(collection), file)
+      end
+    end
+  end
+end

data/lib/jekyll/gallery/seo.rb ADDED Viewed

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+module Jekyll
+  module Gallery
+    #
+    # Expand the image:cover paths to accomplish the
+    # Jekyll-Gallery filesystem standards and return
+    # a path compatible with the Jekyll-Seo-Tag plugin.
+    #
+    class SeoImage
+      def self.setup
+        Jekyll::Hooks.register :documents, :pre_render do |document|
+          image = document["image"]
+          collection = document.type
+          update_frontmatter(image, collection)
+        end
+      end
+      def self.update_frontmatter(image, collection)
+        return unless image.is_a? Hash
+        return if image["cover"].nil?
+        file = Helper.expand_local_file(image["cover"], collection)
+        raise MissingFile, file unless File.exist?(file)
+        image["path"] = Helper.expand_remote_file(image["cover"], collection)
+      end
+    end
+  end
+end

data/lib/jekyll/gallery/tags.rb ADDED Viewed

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+module Jekyll
+  module Gallery
+    #
+    # Gallery view rendering.
+    #
+    class Gallery < Liquid::Tag
+      include Helper
+      def initialize(tag_name, text, tokens)
+        super
+        @@tpl_i ||= File.read(template("image", Config.gconfig)).freeze
+        @@tpl_g ||= File.read(template("gallery", Config.gconfig)).freeze
+        @text = text
+      end
+      def render(context)
+        init_params(@text, context)
+        site = context.registers[:site]
+        tpl = []
+        @files.each_with_index do |f, i|
+          raise MissingFileField, { name: @name, idx: i.next } if f["file"].nil?
+          file = Helper.expand_local_file(f["file"], @collection)
+          raise MissingFile, file unless File.exist?(file)
+          file = Helper.expand_remote_file(f["file"], @collection)
+          vars = {
+            "filename" => file,
+            "name" => @name,
+            "desc_position" => @desc_position,
+            "title" => f["title"],
+            "description" => f["description"],
+            "a_class" => @a_class,
+            "img_class" => @img_class,
+            "counter" => i.next
+          }
+          tpl << (Liquid::Template.parse @@tpl_i).render(site.site_payload.merge!(vars))
+        end
+        images = tpl.join("\n")
+        vars = {
+          "images" => images,
+          "g_class" => @g_class
+        }
+        (Liquid::Template.parse @@tpl_g).render site.site_payload.merge!(vars)
+      end
+      private
+      def init_params(text, context)
+        params = text.split_params(context)
+        @name = params["name"]
+        raise MissingGallery if @name.nil? || @name.empty?
+        @a_class = params["a_class"]
+        @img_class = params["img_class"]
+        @g_class = params["g_class"] || ""
+        @collection = context["#{Config.selector}.collection"] || context["page.collection"]
+        @desc_position = params["desc_position"] || Config.config["desc_position"] || "bottom"
+        @files = context["#{Config.selector}.gallery.#{@name}"] || context["page.gallery.#{@name}"]
+        raise UnknownGallery, @name if @files.nil?
+      end
+    end
+  end
+end

data/lib/jekyll/gallery/utils.rb ADDED Viewed

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+module Jekyll
+  module Gallery
+    #
+    # Convert the params to hash
+    #
+    class ::String
+      def split_params(context)
+        scan(/(\w+)=(?:(["'])(.+?)\2|([^ ]+))/)
+          .to_h do |x|
+            x[3] = context[x[3]] if x[1].nil?
+            x.delete_at 1
+            x.compact
+          end
+      end
+    end
+    #
+    # Remove nil or empty items.
+    #
+    class ::Array
+      def cleanup
+        delete_if { |x| x.nil? || x.to_s.empty? }
+      end
+    end
+    #
+    # Invalid group name error
+    #
+    class InvalidGroup < StandardError
+      def initialize(name)
+        super "The group '#{name}' is not valid!"
+      end
+    end
+    #
+    # No gallery name specified.
+    #
+    class MissingGallery < StandardError
+      def initialize
+        super "No gallery name has been specified!"
+      end
+    end
+    #
+    # The specified gallery name doesn't exist.
+    #
+    class UnknownGallery < StandardError
+      def initialize(name)
+        super "The gallery '#{name}' doesn't exist!"
+      end
+    end
+    #
+    # Not existing file.
+    #
+    class MissingFile < StandardError
+      def initialize(name)
+        super "The file '#{name}' doesn't exist"
+      end
+    end
+    #
+    # Not existing file field
+    #
+    class MissingFileField < StandardError
+      def initialize(data)
+        super "No 'file' field in the gallery '#{data[:name]}' item n.#{data[:idx]}!"
+      end
+    end
+  end
+end

data/lib/jekyll/gallery/version.rb ADDED Viewed

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+module Jekyll
+  module Gallery
+    VERSION = "1.0.0"
+  end
+end

data/lib/jekyll/gallery.rb ADDED Viewed

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+require "jekyll"
+require_relative "gallery/config"
+require_relative "gallery/helper"
+require_relative "gallery/tags"
+require_relative "gallery/utils"
+require_relative "gallery/seo"
+Liquid::Template.register_tag("gallery", Jekyll::Gallery::Gallery)
+Jekyll::Gallery::SeoImage.setup

data/lib/jekyll-gallery-gallery.html ADDED Viewed

@@ -0,0 +1,3 @@
+<div class="gallery {{g_class}}">
+  {{images}}
+</div>

data/lib/jekyll-gallery-image.html ADDED Viewed

@@ -0,0 +1,12 @@
+<figure>
+  <a href="{{filename}}"
+     class="glightbox {{a_class}}"
+     data-gallery="gallery-{{name}}"
+     data-type="image"
+     data-title="{{title}}"
+     data-description="{{description}}"
+     data-desc-position="{{desc_position}}">
+    <img src="{{filename}}" alt="{{title}}" class="{{img_class}}">
+  </a>
+  <figcaption>{{title}}</figcaption>
+</figure>

data/lib/jekyll-gallery-plugin.rb ADDED Viewed

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative "jekyll/gallery"

data/sig/jekyll/gallery/plugin.rbs ADDED Viewed

@@ -0,0 +1,8 @@
+module Jekyll
+  module Gallery
+    module Plugin
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

metadata ADDED Viewed

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-gallery-plugin
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Fabio Mucciante
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-01-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: It applies a gallery template and checks for the files listed presence.
+email:
+- fabio.mucciante@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- jekyll-gallery-plugin.gemspec
+- lib/jekyll-gallery-gallery.html
+- lib/jekyll-gallery-image.html
+- lib/jekyll-gallery-plugin.rb
+- lib/jekyll/gallery.rb
+- lib/jekyll/gallery/config.rb
+- lib/jekyll/gallery/helper.rb
+- lib/jekyll/gallery/seo.rb
+- lib/jekyll/gallery/tags.rb
+- lib/jekyll/gallery/utils.rb
+- lib/jekyll/gallery/version.rb
+- sig/jekyll/gallery/plugin.rbs
+homepage: https://freeaptitude.altervista.org/projects/jekyll-gallery.html
+licenses: []
+metadata:
+  homepage_uri: https://freeaptitude.altervista.org/projects/jekyll-gallery.html
+  source_code_uri: https://github.com/fabiomux/jekyll-gallery-plugin
+  changelog_uri: https://freeaptitude.altervista.org/projects/jekyll-gallery.html#changelog
+  wiki_uri: https://github.com/fabiomux/jekyll-gallery-plugin/wiki
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.3
+signing_key:
+specification_version: 4
+summary: Customizable Jekyll plugin that renders a gallery using the GLightbox Javascript
+  library.
+test_files: []