Grav SectionWidget Plugin

About

SectionWidget is a plugin for Grav. This readme describes version 0.1.4. This plugin splits, with special section marker, large content into sections. Only one or all sections are visible at a time. The content of a section is up to the author. It creates a configurable HTML widget that lets one navigate to the first, previous, next or last section. Or a drop down menu that jumps directly into a specific section. Only one section or all sections are visible at a time. The widget layout is done with a partial twig template. The included CSS styling fits well with the antimatter theme.

Your reasons for splitting content into sections might be:

• To make the content more digestible
• Your readers might prefer to peek into the conclusion first
• The content type makes clicking next, next, next ... more natural (e.g. a series of lyrics)
• ...

These screen shots gives you an idea how this might look like. First the page is opened with all sections visible.


Here section two is active (highlighted in the pull down menu). The user is about to select section 3 (Footnotes).

Requirements

FontAwesome 4.4.0 is used for showing the "full" control in the widget (to get around, change the icon fa-map-o in templates/sectionwidget.html.twig)

Note

You might be interested in my other Grav plugins:

• GoogleMaps
• GroupWidget

Issues

Please open a new issue for defects or new functionality requests.

Known limitations

Here are some limitation:

• You can only have one set of sections per page; so it does not work for modular pages where each module needs its HTML section widget. You can however have different HTML section widgets on a page to control one set of sections. An extensive widget at the top and a simple one at the bottom of the page is therefore possible.
• The section plugin does not integrate perfectly with the similar named GroupWidget plugin.
• Sections don't open up automatically when a link inside these was targetted. This might be annoying when used in combination with the TOC plugin or footnotes (with markdown extra).

Installation and Updates

There's a manual install and update method by downloading this plugin and extracting all plugin files to </your/site>/grav/user/plugins/sectionwidget.

Alternatively, Grav has a command line tool, bin/gpm to manage this plugin's life-cycle.

Usage

The plugin comes with a sensible and self explanatory default plugin configuration (sectionwidget.yaml), a layout (templates/partials/sectionwidget.html.twig) and a styling (assets/css/sectionwidget.css) for antimatter.

Integrate the plugin's twig template into the theme

The partial twig needs integration into the theme. This diff shows how that can be done for the screen shots above, in antimatter theme's default.html.twig

 {% extends 'partials/base.html.twig' %}

 {% block content %}
+    {% if config.plugins.sectionwidget.enabled %}
+        {% include 'partials/sectionwidget.html.twig' %}
+    {% endif %}
+
        {{ page.content }}
+
+    {% if config.plugins.sectionwidget.enabled %}
+        {% include 'partials/sectionwidget.html.twig' with { 'controls':['prev','next'] } %}
+    {% endif %}
 {% endblock %}

Notice the controls overrides sectionwidgets.controls value in the second diff hunk.

SectionWidget's configuration

Here's an extended configuration example:

enabled: true                                        # enabled by default
built_in_css: true                                   # use the build-in css
marker: ======                                       # the section marker
controls: [ first, prev, full, fullmenu, next, last] # controls to show
initial: 0                                           # supports full as well (whole page visible)

• marker allows to redefine the section marker (in case the default clashes with other uses).
• controls holds the list of controls that are rendered in the section widget.
  • first, prev, next and last are navigation button controls.
  • fullmenu is a drop down control from which to select a section. The last menu item does not corresponds with a particular section: it shows the whole page (all sections).
  • full is a button control to show the whole page (all sections).
• initial has an integer value representing the section to show after the page is loaded. The value full with show all sections; the whole page.

The section marker

The content of a section is everything between 2 section markers (or the end of the file). This marker is specified with the marker configuration (by default six consecutive equals signs ======). The menu items in the drop down menu that represent each section, are taken from the first H<x> element after the section marker that is not empty. If a section does not contain any header element, or on the contrary multiple titled paragraphs, put a descriptive title right after the section marker (see the simplified example markdown below).

The markdown content right before the very first section marker, does not end up in its own section; it's shown in from of each single section. In this part is typically the page summary, a main title, the TOC etc.

Here's the markdown content that resulted in the screen shots above. It illustrates:

• The whole page is opened; all sections are visible due to the option initial: full
• Some content in front of the first section marker
• The use of a title right after the section marker (Section 2 Most work and Footnotes)
• Three sections (The footnotes is a separate section)

---
title: Test SectionWidget English
icon: bomb
toc:
  title: false
  baselevel: 3
sectionwidget:
  initial: full
---
The summery text

===
# 
## Page Title
The intro text the waterfall is not agile[^global]
[TOC]

======
### Requirements
The requirements text

====== Section 2 Most work
### Design phase
The design text

### Implementation
The implementation text[^section2]

======Footnotes
[^global]: note global
[^section2]: note section 2

License

Copyright 2015 Francis Meyvis.

Licensed for use under the terms of the MIT license.