jekyll-theme-bas-style-kit 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 43005268ee83aaa5337b6e532257497dc626f6d3
-  data.tar.gz: ac58744ceca48c0205bf4829d5a05bb40c143220
+  metadata.gz: 701f3780545273cb9e5be5babe4ba472ca48ea5f
+  data.tar.gz: 8733cd26e3f1b349a5966a59ee582a440ab9be0e
 SHA512:
-  metadata.gz: b5e731ccf2c76965384e261b14a2ff7163f4f3c0163c74dfbf10a44cd51fb6b36f8170d8cebbbb0e0db0808f18cc7720e7b1bfa40aae5a5ba7408d51930facc4
-  data.tar.gz: 34472b3459a6e0511ac07bb5f838b3be723ed47366c0541fc130ccb1dafce84c003c574ce9ee1c30b0f645205ad7889edf59844d6a98f537aa40c37bc716c284
+  metadata.gz: ece2cbf1c87461c38737df47a6dffef98825f6052d4b74a89d5e6d2d167fab9de069b7b33fcfdbe11a43d74980d0d6f6dc8d559e2f7691c04e89e79c3b6d57cb
+  data.tar.gz: f530d32dae6a5eafdbf016d97b667f9067868ccae4c5b5ded114528336b84bb7699344b56d4420b256646c40e29ec0d8ca882af79bbbbaa75101536e2402814d

data/CHANGELOG.md

@@ -5,6 +5,27 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 ## [Unreleased][unreleased]
 
+## 0.2.0 - 20/03/2017
+
+### Added
+
+* Variables data file to provide information about the theme and version of the Style Kit version used for example
+
+### Fixed
+
+* Documenting that the site base URL will be prefixed to navigation item URLs if one is defined
+
+### Changed
+
+* Body JS include now references files from a data file, and allows per-page files to loaded using front-matter
+* Updating theme screen shot
+
+## 0.1.2 - 14/03/2017
+
+### Fixed
+
+* Active site navigation item support when using 'pretty' permalinks
+
 ## 0.1.1 - Skipped
 
 ## 0.1.0 - 12/03/2017

data/README.md

@@ -167,12 +167,10 @@ include.
 
 **File:** `snippets/body-js.html`
 
-Inserts `<script>` tags for:
+Inserts `<script>` tags to reference JavaScript files. Entries defined in the `bsk_jekyll_js.json` data file will be
+output first, followed by per-page files using the `body_js_files` front-matter option.
 
-* jQuery (required for Bootstrap's JavaScript components and the cookie banner)
-* Bootstrap JavaScript components (required for components such as drop-down menus)
-* JS Cookie (required for the cookie banner)
-* cookie banner (a script to hide the cookie banner using a cookie, if the user chooses to)
+See the *JavaScript* section for more information.
 
 **Note:** This snippet is designed for loading JavaScript *after* the main page content. If a script needs to be run 
 before this content, you will need to do this manually.
@@ -229,6 +227,8 @@ All assets in this theme are scoped to the `bsk-jekyll` directory.
 website that uses this theme. This makes such sites more consistent, and gives performance benefits using browser 
 caching.
 
+**Note:** To include JavaScript files, after the page has loaded, see the *JavaScript* section.
+
 #### `bsk-jekyll/bas-style-kit-jekyll-theme.scss`
 
 CSS styles specific to this theme, designed to be the same for each site using this theme.
@@ -249,6 +249,8 @@ Simple script to set a cookie when the user dismisses the cookie banner. If this
 be shown on subsequent pages for a period of 30 days. After this time the banner will be shown again, until dismissed 
 again for another 30 days.
 
+See the *JavaScript* section for more information on how this file is loaded.
+
 #### `css/main.scss`
 
 CSS styles specific to each website. This file is empty by default and is designed to be overiden by each website.
@@ -280,6 +282,96 @@ Theme specific options which **SHOULD** be set:
 | `nav_items`         | List   | Items in this website to include in the site navigation        | *List of items*       | See the *Site navigation* section for more information                      |
 | `nav_related_sites` | List   | Items for other BAS websites to include in the site navigation | *List of items*       | See the *Site navigation* section for more information                      |
 
+### Theme variables
+
+The `bsk_jekyll_vars.json` Jekyll data file contains variables which can be used by websites using this theme.
+
+| Variable        | Type   | Description                                         | Notes |
+| --------------- | ------ | --------------------------------------------------- | ----- |
+| `theme_version` | String | Version of the BAS Style Kit Jekyll Theme           | -     |
+| `bsk_version`   | String | Version of the BAS Style Kit used within this theme | -     |
+
+### JavaScript
+
+JavaScript files can be loaded after the main site content in two ways:
+
+1. Using the `bsk_jekyll_js.json` Jekyll data file - for files that should be loaded in all pages
+2. Using the `body_js_files` front-matter option - for files that should only be loaded for specific pages
+
+Both methods are added to the page using the *Body JS* include, using the following structure for each script:
+
+| Property  | Type   | Required | Description                                       | Example Value                            | Notes                                            |
+| --------- | ------ | -------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ |
+| `comment` | String | Yes      | Used as a HTML comment added before each script   | `Code for managing cookie banner`        | -                                                |
+| `href`    | String | Yes      | Defines the location of the script to be loaded   | `/assets/bsk-jekyll/js/cookie-banner.js` | Depends on the type property value               |
+| `type`    | String | Yes      | Controls how this item is processed and displayed | `local`                                  | See below for valid values                       |
+
+Supported script types are:
+
+* `local`
+* `remote`
+
+**Note:** See the `bsk_jekyll_js.json` Jekyll data file for scripts which are included in all pages by default.
+
+**Example**
+
+For scripts referenced in the `bsk_jekyll_js.json` Jekyll data file:
+
+```json
+{
+  {
+    "comment": "Cookie library used to persistently hide the cookie banner",
+    "href": "https://cdn.web.bas.ac.uk/js-libs/js.cookie-2.1.3.min.js",
+    "type": "remote"
+  },
+  {
+    "comment": "Code for managing cookie banner",
+    "href": "/assets/bsk-jekyll/js/cookie-banner.js",
+    "type": "local"
+  }
+]
+```
+
+For scripts referenced in the `body_js_files` front-matter option:
+
+```md
+---
+title: A page
+body_js_files:
+  - comment: Cookie library used to persistently hide the cookie banner
+    href: https://cdn.web.bas.ac.uk/js-libs/js.cookie-2.1.3.min.js
+    type: remote
+  - comment: Code for managing cookie banner
+    href: /assets/bsk-jekyll/js/cookie-banner.js
+    type: local
+---
+
+# Page content
+...
+```
+
+#### Remote scripts
+
+Set the `href` property to the URL of a remote file.
+
+**Example**
+
+```
+href: https://cdn.web.bas.ac.uk/js-libs/js.cookie-2.1.3.min.js
+```
+
+#### Local scripts
+
+Set the `href` property to a URL relative to the base of the current website.
+
+**Note:** The base URL of the website will be prepended to the `href` property, if one is defined.
+
+**Example**
+
+```
+href: /assets/bsk-jekyll/js/cookie-banner.js
+```
+
 ### Site navigation
 
 Two kinds of navigation item are supported within the site navigation (an instance of the  
@@ -329,6 +421,8 @@ The most basic item type, set manually and displayed as a navbar item (link).
 | -------- | ------ | -------- | --------------------------------- | ------------- | ------------------------------------------------ |
 | `href`   | String | Yes      | Used as the link `href` attribute | `/about`      | Set the `href` property to `/` for the home page |
 
+**Note:** The base URL of the website will be prepended to the `href` property, if one is defined.
+
 **Active item**
 
 When the current page matches the `href` attribute, the item is made the active navbar item.
@@ -362,6 +456,8 @@ A more complex item type, set manually and displayed as a
 | `actions.*.name`   | String | Yes      | Used as the action text                    | `Downloads`   | Example of a single action                       |
 | `actions.*.href`   | String | Yes      | Used as the action `href` atttibute        | `/resources/downloads` | Example of a single action              |
 
+**Note:** The base URL of the website will be prepended to the `action.*.href` property, if one is defined.
+
 **Active item**
 
 When the current page matches the `href` attribute of an action in a drop-down item, the drop-down action is made 
@@ -604,7 +700,7 @@ listed it won't be included. This is separate to the Git `.gitignore` file.
 
 ## Release procedures
 
-1. bump version in `jekyll-theme-bas-style-kit.gemspec` and `docker-compose.yml`
+1. bump version in `jekyll-theme-bas-style-kit.gemspec` and `docker-compose.yml` and `_data/bsk_jekyll_vars.json`
 2. `docker-compose build`
 3. `docker-compose push`
 4. close release

data/_data/bsk_jekyll_js.json

@@ -0,0 +1,22 @@
+[
+    {
+        "comment": "jQuery (necessary for Bootstrap's JavaScript plugins)",
+        "href": "https://cdn.web.bas.ac.uk/js-libs/jquery-3.1.1.min.js",
+        "type": "remote"
+    },
+    {
+        "comment": "Compiled and minified Bootstrap JavaScript plugins, include individual plugins instead if needed",
+        "href": "https://cdn.web.bas.ac.uk/js-libs/boostrap-3.3.7.min.js",
+        "type": "remote"
+    },
+    {
+        "comment": "Cookie library used to persistently hide the cookie banner (slightly ironic we need a cookie to do this)",
+        "href": "https://cdn.web.bas.ac.uk/js-libs/js.cookie-2.1.3.min.js",
+        "type": "remote"
+    },
+     {
+        "comment": "Code for managing cookie banner",
+        "href": "/assets/bsk-jekyll/js/cookie-banner.js",
+        "type": "local"
+    }
+]

data/_data/bsk_jekyll_vars.json

@@ -0,0 +1,4 @@
+{
+    "theme_version": "0.2.0",
+    "bsk_version": "0.1.0"
+}

data/_includes/snippets/body-js.html

@@ -1,8 +1,14 @@
-<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
-<script src="https://cdn.web.bas.ac.uk/js-libs/jquery-3.1.1.min.js"></script>
-<!-- Compiled and minified Bootstrap JavaScript plugins, include individual plugins instead if needed -->
-<script src="https://cdn.web.bas.ac.uk/js-libs/boostrap-3.3.7.min.js"></script>
-<!-- Cookie library used to persistently hide the cookie banner (slightly ironic we need a cookie to do this) -->
-<script src="https://cdn.web.bas.ac.uk/js-libs/js.cookie-2.1.3.min.js"></script>
-<!-- Code for managing cookie banner -->
-<script src="{{ '/assets/bsk-jekyll/js/cookie-banner.js' | prepend: site.baseurl }}"></script>
+{% comment %}BSK Jekyll Theme core JS files{% endcomment %}
+{% for script in site.data.bsk_jekyll_js %}
+    <!-- {{ script.comment }} -->
+    {% if script.type == 'remote' %}<script src="{{ script.href }}"></script>{% endif %}
+    {% if script.type == 'local' %}<script src="{{ script.href | prepend: site.baseurl }}"></script>{% endif %}
+{% endfor %}
+{% comment %}Additional JS files listed on per-page basis{% endcomment %}
+{% if body_js_files %}
+{% for script in page.body_js_files %}
+    <!-- {{ script.comment }} -->
+    {% if script.type == 'remote' %}<script src="{{ script.href }}"></script>{% endif %}
+    {% if script.type == 'local' %}<script src="{{ script.href | prepend: site.baseurl }}"></script>{% endif %}
+{% endfor %}
+{% endif %}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-bas-style-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Felix Fennell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-14 00:00:00.000000000 Z
+date: 2017-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -64,6 +64,8 @@ files:
 - LICENSE-MIT.md
 - LICENSE.md
 - README.md
+- _data/bsk_jekyll_js.json
+- _data/bsk_jekyll_vars.json
 - _includes/layout/cookie-banner.html
 - _includes/layout/phase-banner.html
 - _includes/layout/site-footer.html