jekyll-event-pages 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3fe69adec0d18ea6c775dff7f70f6e383a6012b3eddc564a290e45617c059917
+  data.tar.gz: 86fa94cd83e4e08c9800f5b90262dd7e7d4e14761e3fe06568c34351f507cfde
+SHA512:
+  metadata.gz: c09a8bf8ffb8086fe150cf6f3ab60e36decd795cad3183073b8e973e37f14c514faef5c53f3c04260e5abaae5a6e3322b208e80555cdf3f74cdfd9e5c519e68f
+  data.tar.gz: c379c9898a17f05b626f1f0b238d2119beafb678a5813d8917117d00115249d2160ae1d4b538e6dbd6b01c64b6ac08d714fce51ff13123498419922ca5f6cc69

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) since 2017 by Wolfram Schroers
+Written by Wolfram Schroers <Wolfram.Schroers -at- field-theory.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,208 @@
+# jekyll-event-pages
+
+[![Gem Version](https://img.shields.io/gem/v/jekyll-event-pages.svg)](https://rubygems.org/gems/jekyll-event-pages)
+
+This plugin is deeply inspired by based on [jekyll-category-pages](https://github.com/field-theory/jekyll-category-pages) plugin. It works on an attribute called events in place of categories.
+This plugin adds event index pages with and without pagination.  
+Benefits are:
+* Easy to setup and use, fully compatible with the default [pagination
+    plugin](https://github.com/jekyll/jekyll-paginate) (also cf. the
+    [official documentation](https://jekyllrb.com/docs/pagination/)).
+* Supports event keys with spaces and other special characters.
+* Complete documentation and a usage example.
+* Test coverage of key features.
+* event index pages are generated based on a customizable template.
+
+## Usage
+
+Assign one or more events in the YAML front matter of each page:
+```yaml
+events: [event Pages Plugin, jekyll]
+```
+Generate the site and the event pages are generated:
+```
+_site/event/
+├── event-pages-plugin/
+│   └── index.html
+├── 好的主意/
+│   └── index.html
+└── jekyll/
+    ├── index.html
+    ├── page2.html
+    └── page3.html
+```
+In this example there are three paginated index pages for the `jekyll`
+event (apparently, there are many posts for this event), a
+single index page for the `好的主意` event and another single index
+page for the `event Pages Plugin` event.
+
+Note that the YAML `events` entry should always use brackets `[]`
+to make it explicit that it is an array!
+
+You can find this example in the `example` directory of the
+[git repository](https://github.com/field-theory/jekyll-event-pages).
+
+### The example project
+
+The `example` directory contains a basic example project that
+demonstrates the different use cases. In order to run Jekyll on these
+examples use:
+```shell
+bundle install
+bundle exec rake example
+```
+The result is put in `example/_site`.
+
+## Installation and setup
+
+Installation is straightforward (like other plugins):
+1. Add the plugin to the site's `Gemfile` and configuration file and
+   also install the `jekyll-paginate` gem (the latter is a required
+   dependency even if you don't use it):
+    ```ruby
+    group :jekyll_plugins do
+      gem "jekyll-paginate"
+      gem "jekyll-event-pages"
+    end
+    ```
+2. Add the plugin to your site's `_config.yml`:
+    ```ruby
+    plugins:
+      - jekyll-event-pages
+    ```
+3. This step is optional, but recommended: Also add this line to
+   `_config.yml` which excludes events from file URLs (they are
+   ugly and don't work properly in Jekyll, anyways):
+   ```ruby
+   permalink: /:year/:month/:day/:title:output_ext
+   ```
+4. Configure any other options you need (see below).
+5. Add template for event pages (see below).
+6. Set appropriate `events` tags on each blog post YAML front
+   matter.
+
+### Configuration
+
+The following options can be set in the Jekyll configuration file
+`_config.yml`:
+* `event_path`: Root directory for event index pages. Defaults
+    to `event` if unset.  
+    In the example this places the index file for event `jekyll` at
+    `example/_site/event/jekyll/index.html`.
+* `event_layout`: Basic event index template. Defaults to
+    `event_index.html`. The layout **must** reside in the standard
+    `_layouts` directory.  
+    In the example the layout is in
+    `example/_layouts/event_index.html`.
+* `paginate`: (Maximum) number of posts on each event index
+    page. This is the same for the regular (front page) pagination. If
+    absent, pagination is turned off and only single index pages are
+    generated.  
+    In the example `paginate` is set to 2.
+
+### Template for event pages
+
+The template for a event index page must be placed in the site's
+`_layouts` directory. The attribute `event` indicates the current
+event for which the page is generated. The page title also defaults
+to the current event. The other attributes are similar to the
+default Jekyll pagination plugin.
+
+If no pagination is enabled the following attributes are available:
+
+| Attribute     | Description                               |
+| ------------- | ----------------------------------------- |
+| `event`    | Current page event                     |
+| `posts`       | List of posts in current event         |
+| `total_posts` | Total number of posts in current event |
+
+If pagination is enabled (i.e., if setting `site.paginate` globally in
+`_config.yml`) then a `paginator` attribute is available which returns
+an object with the following attributes:
+
+| Attribute            | Description                                                                      |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `page`               | Current page number                                                              |
+| `per_page`           | Number of posts per page                                                         |
+| `posts`              | List of posts on the current page                                                |
+| `total_posts`        | Total number of posts in current event                                        |
+| `total_pages`        | Total number of pagination pages for the current event                        |
+| `previous_page`      | Page number of the previous pagination page, or `nil` if no previous page exists |
+| `previous_page_path` | Path of previous pagination page, or `''` if no previous page exists             |
+| `next_page`          | Page number of the next pagination page, or `nil` if no subsequent page exists   |
+| `next_page_path`     | Path of next pagination page, or `''` if no subsequent page exists               |
+
+An example can be found in `example/_layouts/event_index.html`
+which demonstrates the various attributes and their use.
+
+### event listing
+
+A event overview with a full listing of all events can be
+created as follows:
+```html
+<ul>
+{% for event in site.events %}
+<li><a href="{{ site.url }}/event/{{ event | first | slugify }}/index.html">{{ event | first }}</a></li>
+{% endfor %}
+</ul>
+```
+Note that the event page paths are URL-encoded when generated by
+this plugin. Thus, you have to use `slugify` when linking to each
+event. This saves you from problems with spaces or other special
+characters in event names.
+
+An example listing can be found in `example/index.html` which
+shows a full listing of events with corresponding links.
+
+### events on a single page
+
+Listing the events in a single page is particularly simple since
+the events listed in the YAML front matter are directly available
+as strings in `page.events`.  However, unlike the site-wide
+event list in `site.events` the content of `page.events`
+are just strings and can thus be added as follows (with references):
+```html
+<ul>
+{% for event in page.events %}
+<li><a href="{{ site.url }}/path-to-event-index/{{ event | slugify }}/index.html">{{ event }}</a></li>
+{% endfor %}
+</ul>
+```
+
+## Development
+
+This project contains a `Rakefile` that supports the following
+tasks:
+* `build`: Runs all tests and builds the resulting gem file.
+* `test`: Run all tests.
+* `example`: Run Jekyll for the example project.
+* `clean`: Clean up all transient files.
+
+To run all test cases use:
+```shell
+bundle exec rake test
+```
+The tests run different Jekyll configurations and produce output files
+that can be read by Ruby. These are then evaluted and validated using
+[Ruby RSpec](http://rspec.info).
+
+To build the gem use:
+```shell
+bundle exec rake build
+```
+The result is put in the current directory after all tests have been
+run.
+
+## Gotchas
+
+The following issues and limitations are known:
+* Jekyll currently does not properly escape special HTML entities
+  (like `&` or `<`) in permalink paths. Because of that you cannot use
+  them in event names. If you still want to use them you need to
+  adjust the `permalink` path as shown above -- it must not contain
+  event names.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://github.com/etcware/jekyll-event-pages/blob/master/LICENSE).

data/lib/jekyll/event_pages.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+# Encoding: utf-8
+
+#
+# attribute_pages
+# Add attribute index pages with and without pagination.
+#
+# (c) since 2022 by Alessandra Donnini
+# Written by Alessandra Donnini <a dor donnini -at- etcware dot it>
+#
+# Copyright: Since 2022 Alessandra Donnini - MIT License
+# See the accompanying file LICENSE for licensing conditions.
+#
+
+require 'jekyll'
+
+module Jekyll
+
+  # aggiunge il metodo events alla classe Site
+  module EventMethod
+  	def events
+  	  post_attr_hash("events")
+  	end
+  end
+  Site.class_eval { include EventMethod }
+  class Site
+  	include EventMethod
+  end
+  
+  module EventPages
+    INDEXFILE = 'index.html'
+
+    # Custom generator for generating all index pages based on a supplied layout.
+    #
+    # Note that this generator uses a layout instead of a regular page template, since
+    # it will generate a set of new pages, not merely variations of a single page like
+    # the blog index Paginator does.
+    class Pagination < Generator
+      # This generator is safe from arbitrary code execution.
+      safe true
+      priority :lowest
+
+      # Generate paginated event pages if necessary.
+      #
+      # site - The Site object.
+      def generate(site)
+        event_base_path = site.config['event_path'] || 'event'
+        event_layout_path = File.join('_layouts/', site.config['event_layout'] || 'event_index.html')
+
+        if Paginate::Pager.pagination_enabled?(site)
+          # Generate paginated event pages
+          generate_paginated_events(site, event_base_path, event_layout_path)
+        else
+          # Generate event pages without pagination
+          generate_events(site, event_base_path, event_layout_path)
+        end
+      end
+
+      # Sort the list of events and remove duplicates.
+      #
+      # site - The Site object.
+      #
+      # Returns an array of strings containing the site's events.
+      def sorted_events(site)
+        events = []
+        #puts site.events 
+        site.events.each_pair do |event, pages|
+          events.push(event)
+        end
+        events.sort!.uniq!
+        return events
+      end
+
+      # Generate the paginated event pages.
+      #
+      # site               - The Site object.
+      # event_base_path - String with the base path to the event index pages.
+      # event_layout    - The name of the basic event layout page.
+      def generate_paginated_events(site, event_base_path, event_layout)
+        events = sorted_events site
+
+        # Generate the pages
+        for event in events
+          posts_in_event = site.events[event]
+          event_path = File.join(event_base_path, Utils.slugify(event))
+          per_page = site.config['paginate']
+
+          page_number = EventPager.calculate_pages(posts_in_event, per_page)
+          page_paths = []
+          event_pages = []
+          (1..page_number).each do |current_page|
+            # Collect all paths in the first pass and generate the basic page templates.
+            page_name = current_page == 1 ? INDEXFILE : "page#{current_page}.html"
+            page_paths.push page_name
+            new_page = EventIndexPage.new(site, event_path, page_name, event, event_layout, posts_in_event, true)
+            event_pages.push new_page
+          end
+
+          (1..page_number).each do |current_page|
+            # Generate the paginator content in the second pass.
+            previous_link = current_page == 1 ? nil : page_paths[current_page - 2]
+            next_link = current_page == page_number ? nil : page_paths[current_page]
+            previous_page = current_page == 1 ? nil : (current_page - 1)
+            next_page = current_page == page_number ? nil : (current_page + 1)
+            event_pages[current_page - 1].add_paginator_relations(current_page, per_page, page_number,
+                                                                     previous_link, next_link, previous_page, next_page)
+          end
+
+          for page in event_pages
+            # Finally, add the new pages to the site in the third pass.
+            site.pages << page
+          end
+        end
+
+        Jekyll.logger.debug("Paginated events", "Processed " + events.size.to_s + " paginated event index pages")
+      end
+
+      # Generate the non-paginated event pages.
+      #
+      # site               - The Site object.
+      # event_base_path - String with the base path to the event index pages.
+      # event_layout    - The name of the basic event layout page.
+      def generate_events(site, event_base_path, event_layout)
+        events = sorted_events site
+
+        # Generate the pages
+        for event in events
+          posts_in_event = site.events[event]
+          event_path = File.join(event_base_path, Utils.slugify(event))
+
+          site.pages << EventIndexPage.new(site, event_path, INDEXFILE, event, event_layout, posts_in_event, false)
+        end
+
+        Jekyll.logger.debug("Events", "Processed " + events.size.to_s + " event index pages")
+      end
+
+    end
+  end
+
+  # Auto-generated page for a event index.
+  #
+  # When pagination is enabled, contains a EventPager object as paginator. The posts in the
+  # event are always available as posts, the total number of those is always total_posts.
+  class EventIndexPage < Page
+    # Attributes for Liquid templates.
+    ATTRIBUTES_FOR_LIQUID = %w(
+      event
+      paginator
+      posts
+      total_posts
+      content
+      dir
+      name
+      path
+      url
+    )
+
+    # Initialize a new event index page.
+    #
+    # site              - The Site object.
+    # dir               - Base directory for all event pages.
+    # page_name         - Name of this event page (either 'index.html' or 'page#.html').
+    # event          - Current event as a String.
+    # event_layout   - Name of the event index page layout (must reside in the '_layouts' directory).
+    # posts_in_event - Array with full list of Posts in the current event.
+    # use_paginator     - Whether a EventPager object shall be instantiated as 'paginator'.
+    def initialize(site, dir, page_name, event, event_layout, posts_in_event, use_paginator)
+      @site = site
+      @base = site.source
+      if ! File.exist?(File.join(@base, event_layout)) && 
+        ( site.theme && File.exist?(File.join(site.theme.root, event_layout)) )
+          @base = site.theme.root
+      end
+      
+      super(@site, @base, '', event_layout)
+      @dir = dir
+      @name = page_name
+
+      self.process @name
+
+      @event = event
+      @posts_in_event = posts_in_event
+      @my_paginator = nil
+
+      self.read_yaml(@base, event_layout)
+      self.data.merge!('title' => event)
+      if use_paginator
+        @my_paginator = EventPager.new
+        self.data.merge!('paginator' => @my_paginator)
+      end
+    end
+
+    # Add relations of this page to other pages handled by a EventPager.
+    #
+    # Note that this method SHALL NOT be called if the event pages are instantiated without pagination.
+    # This method SHALL be called if the event pages are instantiated with pagination.
+    #
+    # page               - Current page number.
+    # per_page           - Posts per page.
+    # total_pages        - Total number of pages.
+    # previous_page      - Number of previous page or nil.
+    # next_page          - Number of next page or nil.
+    # previous_page_path - String with path to previous page or nil.
+    # next_page_path     - String with path to next page or nil.
+    def add_paginator_relations(page, per_page, total_pages, previous_page_path, next_page_path, previous_page, next_page)
+      if @my_paginator
+        @my_paginator.add_relations(page, per_page, total_pages,
+                                    previous_page, next_page, previous_page_path, next_page_path)
+        @my_paginator.add_posts(page, per_page, @posts_in_event)
+      else
+        Jekyll.logger.warn("Categories", "add_relations does nothing since the event page has been initialized without pagination")
+      end
+    end
+
+    # Get the event name this index page refers to
+    #
+    # Returns a string.
+    def event
+      @event
+    end
+
+    # Get the paginator object describing the current index page.
+    #
+    # Returns a EventPager object or nil.
+    def paginator
+      @my_paginator
+    end
+
+    # Get all Posts in this event.
+    #
+    # Returns an Array of Posts.
+    def posts
+      @posts_in_event
+    end
+
+    # Get the number of posts in this event.
+    #
+    # Returns an Integer number of posts.
+    def total_posts
+      @posts_in_event.size
+    end
+  end
+
+  # Handle pagination of event index pages.
+  class EventPager
+    attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
+                :previous_page, :previous_page_path, :next_page, :next_page_path
+
+    # Static: Calculate the number of pages.
+    #
+    # all_posts - The Array of all Posts.
+    # per_page  - The Integer of entries per page.
+    #
+    # Returns the Integer number of pages.
+    def self.calculate_pages(all_posts, per_page)
+      (all_posts.size.to_f / per_page.to_i).ceil
+    end
+
+    # Add numeric relationships of this page to other pages.
+    #
+    # page               - Current page number.
+    # per_page           - Posts per page.
+    # total_pages        - Total number of pages.
+    # previous_page      - Number of previous page or nil.
+    # next_page          - Number of next page or nil.
+    # previous_page_path - String with path to previous page or nil.
+    # next_page_path     - String with path to next page or nil.
+    def add_relations(page, per_page, total_pages, previous_page, next_page, previous_page_path, next_page_path)
+      @page = page
+      @per_page = per_page
+      @total_pages = total_pages
+      @previous_page = previous_page
+      @next_page = next_page
+      @previous_page_path = previous_page_path
+      @next_page_path = next_page_path
+    end
+
+    # Add page-specific post data.
+    #
+    # page              - Current page number.
+    # per_page          - Posts per page.
+    # posts_in_event - Array with full list of Posts in the current event.
+    def add_posts(page, per_page, posts_in_event)
+      total_posts = posts_in_event.size
+      init = (page - 1) * per_page
+      offset = (init + per_page - 1) >= total_posts ? total_posts : (init + per_page - 1)
+
+      @total_posts = total_posts
+      @posts = posts_in_event[init..offset]
+    end
+
+    # Convert this EventPager's data to a Hash suitable for use by Liquid.
+    #
+    # Returns the Hash representation of this EventPager.
+    def to_liquid
+      {
+          'page' => page,
+          'per_page' => per_page,
+          'posts' => posts,
+          'total_posts' => total_posts,
+          'total_pages' => total_pages,
+          'previous_page' => previous_page,
+          'previous_page_path' => previous_page_path,
+          'next_page' => next_page,
+          'next_page_path' => next_page_path
+      }
+    end
+  end
+end

data/lib/jekyll-event-pages/version.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# Copyright: Since 2022 Alessandra Donnini - MIT License
+# Encoding: utf-8
+
+#
+# jekyll-event-pages
+# Add event index pages with and without pagination.
+#
+# (c) since 2022 by Alessandra Donnini
+# Written by Alessandra Donnini <a dor donnini -at- etcware dot it>
+#
+# Copyright: since 2022 by Alessandra Donnini - MIT License
+# See the accompanying file LICENSE for licensing conditions.
+#
+
+module Jekyll
+  module EventPages
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/jekyll-event-pages.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# Copyright: Since 2022 Alessandra Donnini - MIT License
+# Encoding: utf-8
+
+#
+# jekyll-event-pages
+# Add category index pages with and without pagination.
+#
+# (c) since 2022 by Alessandra Donnini
+# Written by Alessandra Donnini <a dor donnini -at- etcware dot it>
+#
+# Copyright: since 2022 by Alessandra Donnini - MIT License
+# See the accompanying file LICENSE for licensing conditions.
+#
+
+require "jekyll/event_pages"

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-event-pages
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alessandra Donnini
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-09-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: jekyll-paginate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  This plugin is for all authors that tag their pages using a selected attribute. It generates
+  event overview pages with a custom layout. Optionally, it also adds proper
+  pagination for these pages.
+
+  Please refer to the README.md file on the project homepage at
+  https://github.com/etcware/jekyll-event-pages
+email: a.donnini@etcware.it
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll-event-pages.rb
+- lib/jekyll-event-pages/version.rb
+- lib/jekyll/event_pages.rb
+homepage: https://github.com/etcware/jekyll-event-pages
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Add event index pages with and without pagination.
+test_files: []