j1_template_mde 2018.4.10

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/410_common_header_parameters.asciidoc

@@ -0,0 +1,120 @@
+[cols="3,2,2,5",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Parameter |Type |Default |Description
+
+|`background_color`
+|Hash
+|
+|The *background_color hash* contains a pair of colors to control the header
+background as a gradient.
+
+|`background_color.color_1`
+|Symbolic color \| RGB valuess
+|`md_indigo`
+|Start value (color) for the gradient used for the header box background.
+Alternatively, the color can be configured as (hexadecimal) RGB valuess of
+the form `#RRGGBB`
+
+|`background_color.color_2`
+|Symbolic color \| RGB valuess
+|`md_indigo`
+|End value (color) for the gradient used for the header box background.
+Alternatively, the color can be configured as (hexadecimal) RGB valuess of
+the form `#RRGGBB`
+
+|`margin_bottom`
+|Integer
+|`50`
+|Determine the distance, measured in pixel (px) from bottom position of the
+the *header box* to the first position of the following content
+
+|`padding_bottom`
+|Integer
+|`50`
+|Determines the distance, measured in pixel (px), from bottom position of the
+the *overlay container* to the bottom of the header box. In combination with
+`padding_top` the total size of the header box is  determined.
+
+|`padding_top`
+|Integer
+|`200`
+|Determines the distance, measured in pixel (px), from top position of the
+page and the *overlay container* that contains the title and tagline. In
+combination with `padding_bottom` the total size of the header box is
+determined.
+
+|`raised_level`
+|integer
+|`15`
+|Uplifting of the header element. Valid values are out of `[ 0 .. 24]`.
+As higher the number as more the header is uplifted.
+
+|`tagline`
+|Hash
+|n/a
+|The *tagline hash* contains all name\|value pairs to control how the page
+*tagline* is appears with the header
+
+|`tagline.align`
+|Position name (CSS)
+|`left`
+|Alignment of the tagline inside the overlay-container. Valid values are out of
+`left` \| `center` \| `right`
+
+|`tagline.animate`
+|String
+|`fadeInRight`
+|Type of animation for the tagline. Valid values are all values supported
+by AnimateCSS. See https://daneden.github.io/animate.css/[Animate.css home page]
+for details.
+
+|`tagline.color`
+|Symbolic color \| RGB values
+|`rgba_lighten_800`
+| The text color. Should be given as an *symbolic color name*. Alternatively, the
+color can be configured as (hexadecimal) RGB valuess of the form `#RRGGBB`
+
+|`tagline.size`
+|String
+|`larger`
+|Symbolic value for the text size. Valid values are out of  [`xxxsmall` .. `xxxlarge`]
+See size definitions with <<Text sizes>>
+
+|`text_emphasis`
+|String
+|`stronger`
+|Symbolic value for the text shadowing. Valid values are out of
+[`strong`, `stronger`, `strongest`]
+
+|`title`
+|Hash
+|n/a
+|The *title hash* contains all name\|value pairs to control how the page
+*title* appears with the header
+
+|`title.align`
+|Position name (CSS)
+|`left`
+|Alignment of the title inside the overlay-container. Valid values are out of
+`left` \| `center` \| `right`
+
+|`title.animate`
+|String
+|`fadeInLeft`
+|Type of animation for the title. Valid values are all values supported
+by AnimateCSS. See https://daneden.github.io/animate.css/[Animate.css home page]
+for details.
+
+|`title.color`
+|Symbolic color \| RGB value
+|`rgba_lighten_800`
+|The text color. Should be given as an *symbolic color name*. Alternatively, the
+color can be configured as (hexadecimal) RGB values of the form `#RRGGBB`
+
+|`title.size`
+|String
+|`xxxlarge`
+|Symbolic value for the text size. Valid values are out of [`xxxsmall` .. `xxxlarge`]
+See size definitions with <<Text sizes>>
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/420_common_image_header_parameters.asciidoc

@@ -0,0 +1,52 @@
+
+[cols="3,2,2,5",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Name |Type |Default |Description
+
+|`alignX`
+|Float or String
+|`0.5`
+|This parameter controls the horizontal alignment of the image.
+Can be one of `center`, `left`, `right` or any number between 0.0 and 1.0
+
+|`alignY`
+|Float or String
+|`0.5`
+|This parameter controls the vertical alignment of the image.
+Can be one of `center`, `top`, `bottom` or any number between 0.0 and 1.0
+
+|`alt`
+|String
+|n/a
+|The alternative text for this image (for screen readers)
+
+|`duration`
+|Integer
+|`5000`
+|The amount of time in between slides, when using Backstretch as a slideshow,
+expressed as the number of milliseconds
+
+|`scale`
+|String
+|`cover`
+|Controls the scaling mode. Can be one of [`cover` \| `fit` \| `fit-smaller` \| `fill`]
+
+|`transition`
+|String or Array
+|`fade`
+|Type of transition to use. If multiple are specified, then it will be chosen
+randomly
+
+|`transitionDuration`
+|Integer or String
+|`0`
+|This is the duration at which the image will transition in. Integers in
+milliseconds are accepted, as well as standard jQuery speed strings like
+`slow`, `normal` or `fast`
+
+|`url`
+|String
+|n/a
+|The url of the image or video
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/421_additional_image_header_parameters.asciidoc

@@ -0,0 +1,36 @@
+.Additional Image Header Parameter
+[cols="3,2,2,5",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Name |Type |Default |Description
+
+|`caption`
+|String
+|n/a
+|A caption text for e.g. Website, Copyright and \| or Author information
+
+|`caption_color`
+|Symbolic color \| RGB value
+|`rgba_lighten_800`
+| The `caption` text color. Should be given as an *symbolic color name*.
+Alternatively, the color can be configured as (hexadecimal) RGB values
+of the form `#RRGGBB`
+
+|`caption_href`
+|URL
+|n/a
+|A URL that points e.g. to the image source, or a website for Copyright
+and \| or Author information
+
+|`opacity`
+|Float
+|n/a
+|Opacity of the header image. Possible values are floats between 0.0 and 1.0
+
+|`spinner`
+|String
+|`false`
+|To indicate that header images are being loaded, a spinner can be displayed.
+Spinners are defined by the CSS file ~/framework/jquery/backstretch/css/backstretch.css.
+Spinner options are `pulsed` \| `rotor` \| `rotated-dots` \| `cycled-dots`
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/430_video_header_parameters.asciidoc

@@ -0,0 +1,26 @@
+[cols="3,2,2,5",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Name |Type |Default |Description
+
+|`isVideo`
+|Boolean
+|`false`
+|Pass source type *video* to the plugin, if cannot be recognized automatically
+
+|`loop`
+|Boolean
+|`false`
+|Enables\|Disables looping on videos. If `true`, `duration` is used to
+determine when to stop the video
+
+|`mute`
+|Boolean
+|`true`
+|Enables \| Disables sound on videos
+
+|`poster`
+|String
+|n/a
+|Specifying the `poster` attribute on standard tags
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/440_image_and_video_transitions.asciidoc

@@ -0,0 +1,36 @@
+
+[cols="4,8",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Transition | Description
+
+|`coverDown`
+|
+
+|`coverLeft`
+|
+
+|`coverRight`
+|
+
+|`coverUp`
+|
+
+|`fade`
+|
+
+|`fadeInOut`
+|
+
+|`pushDown`
+|
+
+|`pushLeft`
+|
+
+|`pushRight`
+|
+
+|`pushUp`
+|
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/450_image_and_video_header_defaults.asciidoc

@@ -0,0 +1,82 @@
+[cols="4,3,5",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Parameter |Default |Description
+
+|alignX
+|`0.5`
+|The horizontal-alignment for the image, can be
+`left` \| `center` \| `right` or any number between [ 0.0 .. 1.0]
+
+|alignY
+|`0.5`
+|The vertical-alignment for the image, can be on of `top` \| `center`
+\| `bottom` or any number between [ 0.0 .. 1.0]
+
+|alwaysTestWindowResolution
+|`false`
+|Test against the window width instead of the element width
+
+|animateFirst
+|`true`
+|If set to true, the first image will transition in like all the
+others (slideshows only)
+
+|bypassCss
+|`false`
+|Avoid to add any CSS styles to the IMG element
+
+|duration
+|`5000`
+|Time in between slides (if slideshow)
+
+|isVideo
+|`false`
+|Pass source type video to the plugin, if cannot be recognized automatically
+
+|loop
+|`false`
+|Enables \| Disables looping on videos. If true, duration is used to
+determine when to stop
+
+|mute
+|`false`
+|Enables \| Disables sound on videos
+
+|paused
+|`false`
+|Whether the images should slide after given duration
+
+|preload
+|`2`
+|Controls how many images preload at a time
+
+|preloadSize
+|`1`
+|Controls how many images are preloaded in parallel
+
+|scale
+|`cover`
+|Controls the scaling mode. Can be one of `cover` \| `fit` \| `fit-smaller` \| `fill`
+
+|resolutionRefreshRate
+|`2500`
+|Controls how long to wait before switching the resolution
+
+|resolutionChangeRatioThreshold
+|`0.1`
+|Controls how much a change should it be before switching resolution
+
+|start
+|`0`
+|Index of the first image to show
+
+|transition
+|`fade`
+|Type of transition between slides
+
+|transitionDuration
+|`normal`
+|Duration at which the image will transition in.Integers in milliseconds are
+accepted, as well as standard jQuery speed strings as `slow`, `normal` or `fast`
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/000_includes/tables/451_additional_image_and_video_header_defaults.asciidoc

@@ -0,0 +1,23 @@
+[cols="4,3,5",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Parameter |Default |Description
+
+|caption
+|n/a
+|The caption text placed on a image
+
+|caption_color
+|`rgba_lighten`
+|Color of the caption text
+
+|caption_href
+|n/a
+|Link to the image source or copyright statement
+
+|spinner
+|`false`
+|To indicate images are being loaded for a header, a spinner can be placed on.
+Spinners are defined by the CSS file ~/framework/jquery/backstretch/css/backstretch.css.
+A spinner an be one of `pulsed` \| `rotor` \| `rotated-dots` \| `cycled-dots
+
+|=======================================================================

data/lib/starter_web/pages/start/documentation/user_guide/100_header/100_header.adoc

@@ -0,0 +1,452 @@
+---
+title:                                  Header Module
+tagline:                                Template User Guide
+description:                            Header Module
+
+tags:                                   [ Masthead, Header, Template, Modules ]
+resources:                              [ lightbox ]
+permalink:                              /user_guide/modules/header/
+regenerate:                             false
+
+resource_options:
+
+  - toccer:
+      collapseDepth:                    3
+---
+
+// Enable the Liquid Preprocessor
+// -----------------------------------------------------------------------------
+:page-liquid:
+
+// Set other global page attributes here
+// -----------------------------------------------------------------------------
+
+// Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
+
+// Initialize entry document paths
+// -----------------------------------------------------------------------------
+{% include {{set_env_entry_document}} init_folders=all %}
+
+// Load tags and urls
+// -----------------------------------------------------------------------------
+include::{includedir}/attributes.asciidoc[tag=tags]
+include::{includedir}/attributes.asciidoc[tag=urls]
+include::{includedir}/attributes.asciidoc[tag=data]
+
+// Additional Asciidoc page attributes goes here
+// -----------------------------------------------------------------------------
+:jquery-backstretch-home:               http://www.jquery-backstretch.com/
+:jquery-backstretch-github:             https://github.com/jquery-backstretch/jquery-backstretch
+
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+
+J1 Template ships with a *header* module for all content pages of a site.
+A header always gets placed at the very top position of a page.
+
+////
+TBD: What is a master header (in compare to a so-called *header*)? For the
+following the term *header* is used for *master header* ...
+
+Actually, there is no such thing like a ``master header''. The terms header
+and masthead are pretty much used synonymously.
+////
+
+All header types provide a simple yet powerful text overlay technique to
+present animated text taken from your content pages (title and tagline)
+automatically.
+
+The jQuery plugin _jquery-backstretch_ is used as the core library for image-
+and video-based headers. The full documentation plus several examples can be
+found at {jquery-backstretch-home}[Backstretch Home Page]. The Git repository
+can be found at {jquery-backstretch-github}[Github].
+
+== Types of Headers
+
+Headers are available as simple, text-based headers as well as headers
+displaying images – supporting all common image formats like PNG (png), JPEG
+(jpg) and GIF (gif). Besides static images, video clips (online videos and
+HTML5 videos) are supported for image-based headers as well.
+
+=== Text-based Header
+
+A simple, text-based header is quite useful for common content pages. This
+header type supports a colored background and animated text overlays for both
+the title and the tagline of a page.
+
+.Text Header Example for J1 Template
+imageblock::410_text_header.png[]
+
+=== Image-based Header
+
+An image-based header is characterized by dynamically-resizable,
+slideshow-capable background images or videos. The image (or video) stretches
+the width full-size and will get resized automatically, if the size of the
+page changes.
+Image-based headers are fully responsive and get displayed in an excellent
+quality on any device like desktop computers, tablets or mobiles.
+
+.Image Header Example for J1 Template
+imageblock::400_master_header.png[]
+
+
+== Header Configuration
+
+The header module of J1 Template allows _multiple_ headers for your Web.
+Generally, a header is related to a layout and can also be individualized on
+a per page basis.
+
+////
+and ... also = bad construction – though colloquially acceptable, the second
+phrase goes beyond what's described in the first phrase in the sense of
+"plus", "furthermore", "additionally". Therefore, the two phrases are no
+longer equal.
+////
+
+The module supports setting up as many different headers as layouts exist.
+Thus, the header on the home page (layout *HOME*) may be _different_ from the
+header used for pages (layout *page*), posts (layout *post*) or collections
+(layout *collection*).
+
+While you can provide a _common_ header for all content pages that
+belong to a certain _layout_, you can further _individualize_ your header
+configuration on a _per page_ basis for pages that you like to have a unique
+header for.
+
+Configuration parameters are being processed in the following order:
+
+. Default values
+. Layout-specific values
+. Page-specific values
+
+=== General Header Configuration
+
+In J1 Template the header module gets configured by the YAML data file
+`_data/modules/j1_header.yml`. The data file consists of 3 sections:
+
+. Default header settings (text- and image-based headers)
+. Default image settings (image-based headers only)
+. Layout specific header settings (text- and image-based headers)
+
+.J1 Header Configuration File `j1_header.yml`
+[source, yaml]
+----
+# ------------------------------------------------------------------------------
+# 1. Default settings (all header)
+#
+defaults:
+  # 1.1 General settings (text- and image-based header)
+  #
+  globals:
+    debug:                              false
+    icon_family:                        ZMDI
+    icon_color:                         md_grey
+    icon_size:                          default
+
+  # 1.2 Common header default settings (text- and image-based header)
+  #
+  header:
+    raised_level:                       15
+    text_emphasis:                      stronger
+    ...
+
+  # ------------------------------------------------------------------------------
+  # 1.3 Image Header default settings (image-based header only)
+  #
+  image_header:
+    caption:                            ""
+    caption_href:                       ""
+    caption_color:                      rgba_lighten
+    ...
+# ------------------------------------------------------------------------------
+# 2. Layout specific header settings
+#
+headers:
+
+  # ------------------------------------------------------------------
+  # Home (page) header (image-based)
+  #
+  - header:
+      enabled:                          true
+      id:                               homehead
+      layout:                           [ home ]
+      ...
+----
+
+
+=== Layout-specific Header Configuration
+
+The configuration of layout-specific headers is quite simple and can be found
+in the second section of the header config file.
+Layout-specific headers are organized by the the `headers` array. This array
+consists of `header` hashes (key-value pairs) – one per layout – in which each
+header gets configured by a unique header `id` and a dedicated `layout`.
+
+[NOTE]
+====
+Layout-specific headers use the *same* key-value pairs as specified by the
+*default section*. Technically, a layout-specific header configuration
+*overloads* the parameters (by key) already specified by their defaults.
+====
+
+.Layout-specific Header Configuration
+[source, yaml]
+----
+# ------------------------------------------------------------------------------
+# 2. Layout specific header settings
+#
+headers:
+
+  # ------------------------------------------------------------------
+  # Home (page) header
+  #
+  - header:
+      enabled:                          true
+      id:                               homehead
+      layout:                           [ home ]
+      padding_top:                      300
+      margin_bottom:                    0
+      ...
+
+  # ------------------------------------------------------------------
+  # Page header
+  #
+  - header:
+      enabled:                          true
+      id:                               pagehead
+      layout:                           [ page ]
+      text_emphasis:                    strong
+      title:
+        color:                          rgba_lighten_800
+      tagline:
+        color:                          rgba_lighten_800
+        ...
+----
+
+=== Page-specific Header Configuration
+
+The config data (key-value pairs) for a page-specific configuration of a header
+are to be set in the _frontmatter_ of a page. In order to pass individual
+config data to a header, the element `master_header` in the `resource_options`
+array is used.
+
+Following is an example of how a page-specific config may look like. Here the
+image gets altered and an individual caption text is configured (photographer
+credits).
+
+.Page-specific Header Configuration
+[source, yaml]
+----
+resource_options:
+  - master_header:
+      slides:
+        # Image: Pile of Books
+        - url:                      /assets/images/books_r.jpg
+          alt:                      Pile of Books
+          transition:               fadeInOut
+          transitionDuration:       1500
+          caption:                  Photo by Kimberly Farmer on Unsplash
+          caption_href:             "https://unsplash.com/@kimberlyfarmer"
+          caption_color:            rgba_lighten_800
+----
+
+
+== Configuration Parameters
+
+A header always gets placed at the very top position of a page. Both header
+types – text and image headers – have some configuration parameters in
+common. See below for the general anatomy of a header.
+
+The common configuration parameters influence the following:
+
+* Size
+* Uplifting
+* Background color
+* Space between header and content
+* Placement, color and emphasis of title and tagline
+
+=== Anatomy of a Header
+
+Find all these configuration parameters visually displayed in the following
+image. It might be helpful for a better understanding of the common header
+parameters described in <<Common Header Configuration Parameters>>.
+
+.Anatomy of a header
+imageblock::412_header_anatomy.png[]
+
+[NOTE]
+====
+The menu bar is placed as an overlay on top of the header. For details
+how to configure the overlay style of the menu-bar with a header, see the
+NAV module documentation.
+====
+
+=== Common Header Configuration Parameters
+
+Common header parameters are used for both text-based headers _and_
+image-based headers. If _no_ image configuration is given, the header is
+treated as a text-based header. Therefore, common header parameters can be
+regarded as _Text Header Parameters_.
+
+In J1 Template the _header module_ parameters get configured in the
+YAML data file `_data/modules/j1_header.yml`. The default values are
+configured as follows:
+
+.Default Header Configuration Parameters
+[source, yaml]
+----
+header_defaults:
+  raised_level:                           15
+  text_emphasis:                          stronger
+  padding_top:                            200
+  padding_bottom:                         50
+  margin_bottom:                          50
+
+  title:
+    size:                                 xxxlarge
+    color:                                rgba_lighten_800
+    animate:                              fadeInLeft
+    align:                                left
+
+  tagline:
+    size:                                 larger
+    color:                                rgba_lighten_800
+    animate:                              fadeInRight
+    align:                                left
+
+  background_color:
+    color_1:                              md_indigo
+    color_2:                              md_indigo
+----
+
+[NOTE]
+====
+For many configuration parameters _symbolic_ values are used like `large`,
+`larger` or `xlarge` for sizes or e.g `md_indigo` or `md_red_300` for colors.
+For best results regarding responsiveness, sizes should be configured as
+_symbolic_ values. For a better reading (and standardisation) colors should
+be configured by using their _names_ taken from the template's color scheme.
+For example: the RGB value for `md_indigo` is `#3F51B5` – one out of 16
+billion possible RGB values most people won't be able to remember by heart.
+====
+
+See the following table for common header parameters – including a description
+what they are there for, what type they are and what values are possible for
+their configuration.
+
+.Common Header Configuration Parameters
+include::{tabledir}/410_common_header_parameters.asciidoc[]
+
+=== Image Header Configuration Parameters
+
+The header component of J1 Templates integrates the jQuery plugin
+``Backstretch'' for image- or video headers. Hence, image and video
+parameter belong to the Backstretch library.
+
+.Image Header Configuration Parameters
+include::{tabledir}/420_common_image_header_parameters.asciidoc[]
+
+==== Additional Image Header Configuration Parameters
+
+Images from 3rd party sources are usually protected by copyright laws.
+Depending on the respective license you might be allowed to use them, if the
+author or photographer is attributed in a proper way. As for most Creative
+Commons Licenses you need to mention the name of the author, the title of the
+work, if available and a URL that is associated with the work – in case of Web
+uses a link to the source.
+
+You can achieve this by placing a caption text for a configurable URL on the
+image.
+
+.Image Header using a caption text
+imageblock::415_image_header_caption.png[]
+
+.Additional Image Header Configuration Parameters
+include::{tabledir}/421_additional_image_header_parameters.asciidoc[Additional Image Header Configuration Parameters]
+
+=== Video Header Configuration Parameters
+
+For video-based headers some additional configuration parameters control the
+video processing – like sound or the duration the video is playing.
+
+.Video Header Configuration Parameters
+include::{tabledir}/430_video_header_parameters.asciidoc[]
+
+=== Image and Video Transitions
+
+If more than one image or video is given for a header, the header plays the
+configured items as a (slide) show.
+
+.Image and Video Transitions
+include::{tabledir}/440_image_and_video_transitions.asciidoc[]
+
+==== Multiple Transitions
+
+If multiple transitions are specified for the parameter `transition`,
+the transition is chosen randomly. This might be helpful for e.g.
+a demo.
+
+.Multiple Transitions
+[source, yaml]
+----
+  - url:        /assets/videos/headers/still/ocean.png
+    transition: "push_left|push_right|cover_up|cover_down|fade|fadeInOut"
+    ...
+----
+
+== Tables
+
+For experienced users and quick access all configuration parameters for the
+header module are summarized in tables.
+
+=== Text Header Defaults
+
+Common (text) header defaults are shown visually at <<Anatomy of a Header>>.
+Check out this section to see all parameters for a better understanding. Find
+all common parameters and their defaults for the header listed below:
+
+.Common (Text) Header Defaults
+include::{tabledir}/410_common_header_parameters.asciidoc[]
+
+=== Image Header Defaults
+
+Find all parameter and their defaults for a image header listed
+below:
+
+.Image Header Defaults
+include::{tabledir}/450_image_and_video_header_defaults.asciidoc[]
+
+==== Additional Image Header Defaults
+
+Find all parameters and their defaults for an image header listed
+below:
+
+.Additional Image Header Defaults
+include::{tabledir}/451_additional_image_and_video_header_defaults.asciidoc[]
+
+=== Video Header Defaults
+
+Find all parameters and their defaults for a image header listed
+below:
+
+.Video Header Defaults
+include::{tabledir}/430_video_header_parameters.asciidoc[]
+
+=== Image Header Transitions
+
+Find all available transition types for a image header listed
+below:
+
+.Image Header Transitions
+include::{tabledir}/440_image_and_video_transitions.asciidoc[]
+
+=== Text sizes
+
+Find all *symbolic* text *sizes* and their respective *CSS values*
+listed below:
+
+.Text sizes
+include::{tabledir}/000_text_sizes.asciidoc[]