j1-template 2020.0.0

data/lib/starter_web/pages/public/learn/roundtrip/000_bs_tour_api.adoc

@@ -0,0 +1,644 @@
+---
+title:                                  Roundtrip
+tagline:                                bootstrap tour api
+description:                            J1 Template Roundtrip - Present Bootstrap
+
+tags:                                   [ Page, Roundtrip ]
+index:                                  [ Template, Roundtrip, Images ]
+categories:                             [ pages ]
+
+toc:                                    true
+scrollbar:                              false
+
+permalink:                              /pages/public/learn/roundtrip/bs_tour_api/
+regenerate:                             false
+
+resources:                              [ bs_tour ]
+resource_options:
+  - attic:
+      padding_top:                      400
+      padding_bottom:                   50
+      opacity:                          0.5
+      slides:
+        - url:                          /assets/images/pages/roundtrip/images-1920x1280-bw.jpg
+          alt:                          Photo by Ricardo Gomez Angel on Unsplash
+          badge:
+            type:                       unsplash
+            author:                     Ricardo Gomez Angel
+            href:                       https://unsplash.com/@ripato/portfolio
+---
+
+// Enable the Liquid Preprocessor
+// -----------------------------------------------------------------------------
+:page-liquid:
+
+// Set other global page attributes here
+// -----------------------------------------------------------------------------
+//:my-asciidoc-attribute:
+
+//  Load Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
+
+// Initialize entry document environmental attributes
+// -----------------------------------------------------------------------------
+{% include {{set_env_entry_document}} %}
+
+// Load tag, url and data attributes
+// -----------------------------------------------------------------------------
+include::{includedir}/attributes.asciidoc[tag=tags]
+include::{includedir}/attributes.asciidoc[tag=urls]
+include::{includedir}/attributes.asciidoc[tag=data]
+
+// Set local page attributes
+// -----------------------------------------------------------------------------
+:images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
+
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+== Bootstrap Tour
+
+lorem:sentences[5] +
+lorem:sentences[3] +
+
+=== Global Options
+
+lorem:sentences[5] +
+lorem:sentences[3] +
+
+[source, js]
+----
+var tour = Tour({
+  name: "tour",
+  steps: [],
+  container: "body",
+  keyboard: true,
+  storage: window.localStorage,
+  debug: false,
+  backdrop: false,
+  backdropContainer: 'body',
+  backdropPadding: 0,
+  redirect: true,
+  orphan: false,
+  duration: false,
+  delay: false,
+  basePath: "",
+  template: '<div class="popover tour">
+    <div class="arrow"></div>
+    <h3 class="popover-title"></h3>
+    <div class="popover-content"></div>
+    <div class="popover-navigation">
+        <button class="btn btn-default" data-role="prev"> Prev</button>
+        <span data-role="separator">|</span>
+        <button class="btn btn-default" data-role="next">Next »</button>
+    </div>
+    <button class="btn btn-default" data-role="end">End tour</button>
+  </div>',
+  afterGetState: function (key, value) {},
+  afterSetState: function (key, value) {},
+  afterRemoveState: function (key, value) {},
+  onStart: name(tour) {},
+  onEnd: name(tour) {},
+  onShow: name(tour) {},
+  onShown: name(tour) {},
+  onHide: name(tour) {},
+  onHidden: name(tour) {},
+  onNext: name(tour) {},
+  onPrev: name(tour) {},
+  onPause: name(tour, duration) {},
+  onResume: name(tour, duration) {},
+  onRedirectError: name(tour) {}
+});
+----
+
+[cols="1,1,3a,7a", options="header", width="100%", role="table-responsive"]
+|===============================================================================
+|Name |Type |Default |Description
+
+|name
+|String
+|`tour`
+|This option is used to build the name of the storage item
+where the tour state is stored. The name should contain only
+alphanumerics, underscores and hyphens. You can initialize several tours
+with different names in the same page and application.
+
+|steps
+|Array
+|`[]`
+|A list of object representing the steps to be included in
+the tour. Jump to link:#step-options[Step options] for the single step
+API.
+
+|container
+|String
+|`body`
+|Appends the step popover to a specific element. +
+_See Usage section of
+http://getbootstrap.com/javascript/#popovers[Popover]._
+
+|autoscroll
+|Boolean
+|`true`
+|Autoscrolls the window when the step popover is out of view. 
+
+|keyboard
+|Boolean
+|`true`
+|This option set the left and right arrow navigation.
+
+|storage
+|Object
+|`window.localStorage`
+|The storage system you want to use. Could be the
+objects window.localStorage, window.sessionStorage or your own object. +
+You can set this option as `false` to disable storage persistence (the
+tour starts from beginning every time the page is loaded). +
+_Read more about
+https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage[DOM
+Storage interfaces]._
+
+|debug
+|Boolean
+|`false`
+|Set this option to true to have some useful
+informations printed in the console. 
+
+|backdrop
+|Boolean
+|`false`
+|Show a dark backdrop behind the popover and its
+element, highlighting the current step. 
+
+|backdropContainer
+|String
+|`body`
+|HTML element (jQuery selector) on which the backdrop should be shown. 
+
+|backdropPadding
+|Number\|Object
+|`0`
+|Add padding to the backdrop element
+that highlights the step element. +
+It can be a number or a object containing optional `top`, `right`,
+`bottom` and `left` numbers.
+
+|redirect
+|Boolean \|Function
+|`true`
+|Set a custom function to execute as
+redirect function. The default redirect relies on the traditional
+`document.location.href`.
+
+|orphan
+|Boolean\|String\|function
+|`false`
+|Allow to show the step regardless
+whether its element is not set, is not present in the page or is hidden.
+The step is fixed positioned in the middle of the page.
+
+|duration
+|Boolean\|Number
+|`false`
+|Set a expiration time for the steps. When
+the current step expires, the next step is automatically shown. See it
+as a sort of guided, automatized tour functionality. The value is
+specified in milliseconds.
+
+|delay
+|Boolean\|Number
+|`0`
+|Specifies a delay for the showing and hiding the tour steps. It can be:
+* a falsy - there is no delay
+* a number - used as a delay for both showing and hiding. In milliseconds
+* a object containing optional `show` and `hide` numbers - defines the
+  delays for showing and hiding respectively.
+
+|basePath
+|String
+|empty string
+|Specify a default base path prepended to the `path`
+option of every single step. Very useful if you need to reuse the same
+tour on different environments or sub-projects.
+
+|template callout:1[]
+|String\|Function
+|See *Description*
+|String or function that returns a string of
+the HTML template for the popovers. If you pass a Function, two
+parameters are available: *i* is the position of step in the tour and
+*step* is the an object that contains all the other step options. +
+From version 0.5, the navigation template is included inside the
+template so you can easily rewrite it. However, Bootstrap Tour maps the
+_previous_, _next_ and _end_ logics to the elements which have the
+related `data-role` attribute. Therefore, you can also have multiple
+elements with the same `data-role` attribute. +
+            
+|afterGetState \| afterSetState \| afterRemoveState  callout:2[]
+|Function
+|`name(key, value){}`
+|You may want to do something right after Bootstrap Tour read, write or
+remove the state. Just pass functions to these. +
+Your functions can have two parameters:
+
+* *key* Contains the name of the state being saved. It can be
+  `current_step` (for the state where the latest step the visitor viewed
+  is saved) or `end` (for the state which is saved when the user complete
+  the tour). Note that Bootstrap Tour prepends the key with `tour_` when
+  saving the state.
+* *value* The value of the state been saved. Can be the index of the
+  current step if the key is `current_step`, or `yes` if the key is `end`.
+
+A simple example if to send a post request to your server each time
+there is a change.
+
+|onStart
+|Function 
+|`name(tour){}`
+|Function to execute when the tour starts.
+
+|onEnd
+|Function
+|`name(tour){}`
+|Function to execute when the tour ends.
+
+|onShow
+|Function
+|`name(tour){}`
+|Function to execute right before each step is shown.
+
+|onShown
+|Function
+|`name(tour){}`
+|Function to execute right after each step is shown.
+
+|onHide
+|Function
+|`name(tour){}`
+|Function to execute right before each step is hidden.
+
+|onHidden
+|Function
+|`name(tour){}`
+|Function to execute right after each step is hidden.
+
+|onNext
+|Function
+|`name(tour){}`
+|Function to execute when next step is called.
+
+|onPrev
+|Function
+|`name(tour){}`
+|Function to execute when prev step is called.
+
+|onPause
+|Function
+|`name(tour, duration){}`
+|Function to execute when pause is called. The
+second argument refers to the remaining duration.
+
+|onResume
+|Function
+|`name(tour, duration){}`
+|Function to execute when resume is called. The
+second argument refers to the remaining duration.
+
+|onRedirectError
+|Function
+|`name(tour){}`
+|Function to execute when there is a
+redirection error. This happens when bootstrap tour cannot redirect to
+the path of the step.
+
+|===============================================================================
+
+.Template default settings callout:1[]
+[source, html]
+----
+<div class="popover tour">
+  <div class="arrow"></div>
+  <h3 class="popover-title"></h3>
+  <div class="popover-content"></div>
+  <div class="popover-navigation">
+    <button class="btn btn-default" data-role="prev'"> Prev</button>
+    <span data-role="separator">\|</span>
+    <button class="btn btn-default" data-role="next">Next »</button>
+    <button class="btn btn-default" data-role="end">End tour</button>
+  </div>
+</div>
+----
+
+State function example callout:2[]
+[source, js]
+----
+var tour = Tour({
+  afterSetState: function (key, value) {
+    $.post("/some/path", value);
+  }
+});            
+----
+
+
+=== Step Options
+
+[source, js]
+----
+tour.addStep({
+  path: "",
+  host: "",
+  element: "",
+  placement: "right",
+  title: "",
+  content: "",
+  next: 0,
+  prev: 0,
+  animation: true,
+  container: "body",
+  backdrop: false,
+  backdropContainer: 'body',
+  backdropPadding: false,
+  redirect: true,
+  reflex: false,
+  orphan: false,
+  template: "",
+  onShow: name(tour) {},
+  onShown: name(tour) {},
+  onHide: name(tour) {},
+  onHidden: name(tour) {},
+  onNext: name(tour) {},
+  onPrev: name(tour) {},
+  onPause: name(tour) {},
+  onResume: name(tour) {},
+  onRedirectError: name(tour) {}
+});
+----
+
+// |Name |Type |Description |Default
+
+[cols="1,1,3a,7a", options="header", width="100%", role="table-responsive"]
+|===============================================================================
+|Name |Type |Default |Description
+
+|path
+|String or RegExp
+|`''`
+|Path to the page on which the step should be
+shown. This allows you to build tours that span several pages.
+
+|host NEW
+|String or RegExp
+|`''`
+|Host of the page on which the step should
+be shown. This allows you to build tours for several sub-domains.
+
+|element
+|String
+|`''`
+|HTML element (jQuery selector) on which the step
+popover should be shown. +
+_If orphan is false, this option is required._
+
+|placement
+|String\|Function
+|`right`
+|How to position the popover. Possible
+choices: `'top'`, `'bottom'`, `'left'`, `'right'`, `'auto'`. When "auto"
+is specified, it will dynamically reorient the popover. For example, if
+placement is "auto left", the popover will display to the left when
+possible, otherwise it will display right.
+
+|title
+|String\|Function
+|`''`
+|Step title
+
+|content
+|String\|Function
+|`''`
+|Step content
+
+|next
+|Integer
+|`0`
+|Index of the step to show after this one, starting from
+`0` for the first step of the tour. `-1` to not show the link to next
+step. By default, the next step (in the order you added them) will be
+shown. +
+_This option should be used in conjunction with `prev`._
+
+|prev
+|Integer
+|`0`
+|Index of the step to show before this one, starting from
+`0` for the first step of the tour. `-1` to not show the link to
+previous step. By default, the previous step (in the order you added
+them) will be shown. +
+_This option should be used in conjunction with `next`._
+
+|animation
+|Boolean
+|`true`
+|Apply a css fade transition to the tooltip.
+
+|container
+|String
+|`body`
+|Attachment of popover. Pass an element (jQuery selector) to append the 
+popover to. By default the popover is appended
+after the 'element' above. This option is particularly helpful for
+Internet Explorer.
+
+|backdrop
+|Boolean
+|`false`
+|Show a dark backdrop behind the popover and its
+element, highlighting the current step.
+
+|backdropContainer NEW 
+|String (jQuery selector)
+|`body`
+|HTML element on which the backdrop should be shown. 
+
+|backdropPadding NEW
+|Boolean\|Object
+|`0`
+|Add padding to the backdropelement that highlights the step element. +
+It can be a number or a object containing optional `top`, `right`,
+`bottom` and `left` numbers.
+
+|redirect
+|Boolean\|Function
+|`true`
+|Set a custom function to execute as redirect function. The default 
+redirect relies on the traditional `document.location.href`.
+
+|reflex UPDATED
+|Boolean\|String
+|`false`
+|Enable the reflex mode: attach an
+handler on `click` on the step element to continue the tour. +
+In order to bind the handler to a custom event, you can pass a string
+with its name. +
+Also, the class `tour-step-element-reflex` is added to the element, as
+hook for your custom style (e.g: cursor: pointer).
+
+|orphan
+|Boolean\|String\|Function
+|`false`
+|Allow to show the step regardless
+whether its element is not set, is not present in the page or is hidden.
+The step is fixed positioned in the middle of the page. +
+You can use a string or function that returns a string of the HTML
+template for the orphan popovers.
+
+|duration NEW 
+|Boolean\|String
+|`false`
+|Set a expiration time for the steps. When
+the step expires, the next step is automatically shown. See it as a sort
+of guided, automatized tour functionality. The value is specified in
+milliseconds.
+
+|template
+|String\|Function
+|See *blabla*
+|String or function that returns a string of
+the HTML template for the popovers. If you pass a Function, two
+parameters are available: *i* is the position of step in the tour and
+*step* is the object that contains all the other step options. +
+From version 0.5, the navigation template is included inside the
+template so you can easily rewrite it. However, Bootstrap Tour maps the
+_previous_, _next_ and _end_ logics to the elements which have the
+related `data-role` attribute. Therefore, you can also have multiple
+elements with the same `data-role` attribute.
+
+|onShow
+|Function
+|`name(tour) {}`
+|Function to execute right before the step is shown.
+It overrides the global `onShow` option.
+
+|onShown
+|Function
+|`name(tour) {}`
+|Function to execute right after the step is shown.
+It overrides the global `onShown` option.
+
+|onHide
+|Function
+|`name(tour) {}`
+|Function to execute right before the step is hidden.
+It overrides the global `onHide` option.
+
+|onHidden
+|Function
+|`name(tour) {}`
+|Function to execute right after the step is hidden.
+It overrides the global `onHidden` option.
+
+|onNext
+|Function
+|`name(tour) {}`
+|Function to execute when next step is called. It
+overrides the global `onNext` option.
+
+|onPrev
+|Function
+|`name(tour) {}`
+|Function to execute when prev step is called. It
+overrides the global `onPrev` option.
+
+|onPause NEW
+|Function
+|`name(tour, duration) {}`
+|Function to execute when pause is called. The
+second argument refers to the remaining duration. It overrides the
+global the `onPause` option.
+
+|onResume NEW
+|Function
+|`name(tour, duration) {}`
+|Function to execute when resume is called. The
+second argument refers to the remaining duration. It overrides the
+global `onResume` option.
+
+|onRedirectError NEW
+|Function
+|`name(tour) {}`
+|Function to execute when there is a
+redirection error. This happens when bootstrap tour cannot redirect to
+the path of the step. It overrides the global `onRedirectError` option.
+
+|===============================================================================
+
+
+=== Methods
+
+If, for some reasons, you want to force the tour to be displayed, pass 
+*true* to the *start()* method.
+
+[cols="3,9a",options="header",]
+|===============================================================================
+|Name |Description
+|addSteps(`[]`)
+|Add multiple steps to the tour. Pass an array of objects.
+
+|addStep(`{}`)
+|Add single step to the tour. Pass an object.
+
+|init()
+|Initialize the tour. You must do it before calling start.
+
+|start(`true`)
+|Start the tour. Pass `true` to force the start.
+
+|restart()
+|Restart the tour after it ended.
+
+|end()
+|End the tour prematurely.
+
+|next()
+|Skip to the next step.
+
+|prev()
+|Go back to the previous step.
+
+|goTo(`i`)
+|Skip to a specific step. Pass `i` as the index of
+the step in the tour (0-based). +
+_From version 0.7.0, the method has been renamed since some Javascript
+compilers are confused by the property name *goto*, which is a reserved
+word)_ .
+
+|pause()
+|Pause the duration timer. It works only if tour or current step has duration.
+
+|resume()
+|Resume the duration timer. It works only if tour or current step has duration.
+
+|ended() |Verify if the tour ended. Returns boolean.
+
+|getStep(`i`)
+|Get the step object. Pass `i` as the index of the step in the tour (0-based).
+
+|getCurrentStep()
+|Get the index of the current step.
+
+|setCurrentStep(`i`)
+|Override the current step. Pass `i` as the index of the step in the 
+tour (0-based).
+
+|redraw()
+|Triggers a redraw on the overlay element. Useful for dynamically sized 
+tour targets.
+
+|===============================================================================
+
+