Initial commit

CHANGELOG.md

@@ -0,0 +1,7 @@
+# v0.1.0
+##  2019-08-08
+
+1. [](#new)
+    * Glossary plugin created.
+    * Site-wide abbreviations enabled.
+    * Glossary search implemented.

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Michele Laurenti, 2019 Nathan Parsons
+
+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.

README.md

@@ -0,0 +1,72 @@
+# Glossary Plugin
+
+The **Glossary** Plugin for [Grav CMS](http://github.com/getgrav/grav) allows you to maintain a glossary of terms that can be formatted into a searchable page, as well as optionally inserting `<abbrev>` tags into your content via Markdown Extra.
+
+## Example output
+
+![Example output of the Glossary plugin in details/summary mode, with the search bar](assets/example_output.png)
+
+
+## Installation
+
+### GPM Installation (Preferred)
+
+The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm), either through the Admin panel, or via your system's terminal by navigating to your site root and running:
+
+```sh
+  bin/gpm install glossary
+```
+
+### Manual Installation
+
+Alternatively, you can download a zip of this repository, unzip it to `/your/site/grav/user/plugins`, and rename the folder to `glossary`.
+
+
+## Usage
+
+### Glossary terms
+
+Glossary terms are defined in the plugin configuration via the `definitions` key. This should contain a list of key-value pairs that define each term, as shown below:
+
+```yaml
+definitions:
+  -
+    term: Some long complicated term
+    abbrev: SLCT
+    definition: "Definition of the term (can include markdown)"
+```
+
+The `term` is required, and you should define at least one of `abbrev` and `definition`. Items that have only a term and abbreviation are excluded from the glossary, but will be applied to your pages as abbreviations if this functionality is enabled.
+
+The definition will be formatted with Markdown when inserted it into the template, so you can include links, emphasis, etc.
+
+
+### Glossary page
+
+Adding a glossary page to your site is as simple as creating a page with the `glossary_plugin` template.
+
+There are two modes for printing the glossary contents, which are set in the plugin configuration via the `item_template` key:
+
+- `dt_dd`: This uses HTML definition lists (ie. `<dl>`, `<dt>`, `<dd>`).
+- `details_summary` makes use of the accordion panel-like functionality of `<details>` and `<summary>` tags. Some browsers, such as Edge, don't support the opening and closing of `details` tags, but fallback to having them always open, so the content should always be accessible to visitors.
+
+Glossary items are listed in alphabetical order. If a glossary item has no definition, it is ignored by the template and thus excluded from the glossary page. If an abbreviation is defined, this will be included in brackets after the term.
+
+You are of course free to write your own templates based on the ones provided if you want. If you think that your changes are more widely useful, a pull request would be welcomed.
+
+
+### Site-wide abbreviations
+
+You can add abbreviation tags `<abbrev>` to all abbreviations on your site by enabling Markdown Extra and the `abbreviations` configuration option of this plugin. When a user hovers on these elements, the long form of the abbreviated term is shown.
+
+**Note:** Currently, abbreviations only work within the page content, and so tags aren't applied to parts of the page that are generated by other means.
+
+
+## Credits
+
+The implementation of the abbreviation insertion is taken from the [acronyms](https://github.com/asmeikal/grav-plugin-acronyms) plugin originally developed by [Michele Laurenti](https://github.com/asmeikal). If you just want the acronym component of this plugin, you could use the original [acronyms](https://github.com/asmeikal/grav-plugin-acronyms) plugin, although it is not currently in the GPM.
+
+
+## License
+
+This plugin is licensed under the [MIT License](LICENSE)

blueprints.yaml

@@ -0,0 +1,92 @@
+name: Glossary
+version: 0.1.0
+description: Maintain a glossary of words and automatically add abbreviations to all pages via Markdown Extra.
+icon: list
+author:
+  name: Nathan Parsons
+  email: [email protected]
+  url: https://github.com/n-parsons
+keywords: grav, plugin, glossary, abbreviation, definitions
+homepage: https://github.com/n-parsons/grav-plugin-glossary
+bugs: https://github.com/n-parsons/grav-plugin-glossary/issues
+license: MIT
+
+form:
+  validation: strict
+  fields:
+    enabled:
+      type: toggle
+      label: Plugin status
+      highlight: 1
+      default: 0
+      options:
+        1: PLUGIN_ADMIN.ENABLED
+        0: PLUGIN_ADMIN.DISABLED
+      validate:
+        type: bool
+    builtin_css:
+      type: toggle
+      label: Use builtin CSS
+      highlight: 1
+      default: 1
+      options:
+        1: PLUGIN_ADMIN.ENABLED
+        0: PLUGIN_ADMIN.DISABLED
+      validate:
+        type: bool
+    show_search:
+      type: toggle
+      label: Search on glossary page
+      info: Requires Simple Search
+      highlight: 1
+      default: 1
+      options:
+        1: PLUGIN_ADMIN.ENABLED
+        0: PLUGIN_ADMIN.DISABLED
+      validate:
+        type: bool
+    fa_search_icon:
+      type: text
+      label: Search icon
+      placeholder: "eg. fas fa-search"
+    fa_reset_icon:
+      type: text
+      label: Reset icon
+      placeholder: "eg. fas fa-times"
+    item_template:
+      type: select
+      label: Item template
+      default: "dt_dd"
+      options:
+        "dt_dd": "Definition list (dl, dt, dd)"
+        "details_summary": "Accordion (details, summary)"
+    abbreviations:
+      type: toggle
+      label: Site-wide abbreviations
+      help: Requires Markdown Extra to be enabled
+      highlight: 1
+      default: 1
+      options:
+        1: PLUGIN_ADMIN.ENABLED
+        0: PLUGIN_ADMIN.DISABLED
+      validate:
+        type: bool
+    definitions:
+      type: list
+      style: vertical
+      label: Definitions
+      collapsed: true
+      collapsible: true
+      fields:
+        .term:
+          type: text
+          label: Term
+          validate:
+            required: true
+        .abbrev:
+          type: text
+          label: Abbreviation
+        .definition:
+          type: editor
+          size: small
+          label: Definition

css/glossary.css

@@ -0,0 +1,33 @@
+.glossary {
+  margin: 1.5rem 0;
+}
+
+.glossary dt,
+.glossary summary {
+  font-weight: bold;
+}
+
+.glossary dd:not(:last-child),
+.glossary details:not(:last-child) {
+  margin-bottom: 0.75rem;
+}
+
+.glossary summary:not(:first-child) {
+  margin-top: 0.5rem;
+}
+
+.search-results .search-query {
+  font-weight: bold;
+}
+
+.search-wrapper .clear-filter {
+  margin-left: 0.5rem;
+}
+
+.search-wrapper form * {
+  vertical-align: middle;
+}
+
+.search-wrapper form .clear-filter {
+  margin-left: 0;
+}

glossary.php

@@ -0,0 +1,94 @@
+<?php
+namespace Grav\Plugin;
+
+use Grav\Common\Plugin;
+use RocketTheme\Toolbox\Event\Event;
+
+class GlossaryPlugin extends Plugin
+{
+    /**
+     * @return array
+     */
+    public static function getSubscribedEvents()
+    {
+        return [
+            'onPageContentRaw' => ['insertAbbreviations', 0],
+            'onTwigTemplatePaths' => ['onTwigTemplatePaths', 0],
+            'onGetPageTemplates' => ['onGetPageTemplates', 0],
+        ];
+    }
+
+    /**
+     * Add templates to Twig lookup paths
+     */
+    public function onTwigTemplatePaths()
+    {
+        $this->grav['twig']->twig_paths[] = __DIR__.'/templates';
+    }
+
+    /**
+     * Add templates to Grav Admin
+     */
+    public function onGetPageTemplates(Event $event)
+    {
+        $event->types->scanTemplates(__DIR__."/templates");
+    }
+
+    /**
+     * Insert abbreviations into the raw content
+     *
+     * Taken from https://github.com/asmeikal/grav-plugin-acronyms (MIT License).
+     * Minor modifications have been made to adapt it for the current use case.
+     */
+    public function insertAbbreviations(Event $event)
+    {
+        // Get config
+        $pluginConfig = $this->config->get('plugins.glossary', array());
+
+        // Check if abbreviations are enabled
+        if (! array_key_exists("abbreviations", $pluginConfig) ||
+            ! $pluginConfig["abbreviations"]) {
+            return;
+        }
+
+        // Get the terms if they exist, exit otherwise
+        if (array_key_exists("definitions", $pluginConfig)) {
+            $terms = $pluginConfig["definitions"];
+        } else {
+            return;
+        }
+
+        $page = $event['page'];
+        $config = $this->mergeConfig($page);
+
+        $enabled = $config->get('enabled');
+
+        // Check that page processes markdown
+        $enabled = $enabled && $page->process()['markdown'];
+
+        // Check that markdown extra is enabled
+        if (isset($page->header()->markdown) &&
+            array_key_exists('extra', $page->header()->markdown)) {
+            $enabled = $enabled && $page->header()->markdown['extra'];
+        } else {
+            $enabled = $enabled && $this->config->get('system.pages.markdown.extra');
+        }
+
+        // Inject the abbreviations into the page
+        if ($enabled && (count($terms) > 0)) {
+            // Get initial content
+            $raw = $page->getRawContent();
+            $raw .= "\n\n";
+
+            // Append acronyms to page (if abbrev is defined)
+            foreach ($terms as $term) {
+                if (array_key_exists("abbrev", $term)) {
+                    $raw .= "*[${term['abbrev']}]: ${term['term']}\n";
+                }
+            }
+
+            // Put content back in
+            $page->setRawContent($raw);
+        }
+    }
+}

glossary.yaml

@@ -0,0 +1,10 @@
+enabled: true
+builtin_css: true
+show_search: true
+item_template: "dt_dd"
+abbreviations: true
+definitions:
+  -
+    term: Some long complicated term
+    abbrev: SLCT
+    definition: Definition of the term (can include markdown)

templates/glossary_plugin.html.twig

@@ -0,0 +1,49 @@
+{% extends 'default.html.twig' %}
+
+{% set plugin_config = config.plugins.glossary %}
+
+{% if plugin_config.builtin_css %}
+  {% do assets.addCss('plugin://glossary/css/glossary.css', 100)  %}
+{% endif %}
+
+
+{% set terms = plugin_config["definitions"] %}
+
+{% set query = uri.param("query") %}
+
+
+{% set definitions = {} %}
+{% for term in terms %}
+  {# if 'has definition' and 'matches query' #}
+  {% if term.definition and (not query or query in (term.term ~ " " ~ term.abbrev ~ " " ~ term.definition)|lower) %}
+    {% set definitions = definitions|merge({(term.term): [term.abbrev, term.definition]}) %}
+  {% endif %}
+{% endfor %}
+
+{% set definitions = definitions|ksort %}
+
+
+{% block content %}
+  <h1>{{ page.title }}</h1>
+
+  {{ content|raw }}
+
+  {% if config.plugins.simplesearch.enabled and plugin_config.show_search %}
+    {% include 'partials/glossary_simplesearch.html.twig' %}
+  {% endif %}
+
+  {% if plugin_config.item_template is same as("details_summary") %}
+    <div class="glossary">
+      {% for key, value in definitions %}
+        {% include 'partials/glossary_details_summary.html.twig' with {term: key, item: value } %}
+      {% endfor %}
+    </div>
+  {% else %}
+    <dl class="glossary">
+      {% for key, value in definitions %}
+        {% include 'partials/glossary_dt_dd.html.twig' with {term: key, item: value } %}
+      {% endfor %}
+    </dl>
+  {% endif %}
+
+{% endblock %}