Skip to content

Latest commit

 

History

History
759 lines (543 loc) · 26.4 KB

documentation.md

File metadata and controls

759 lines (543 loc) · 26.4 KB
Raw

Flowtime.js

Flowtime.js Documentation

How to build minified Flowtime.js

You need node.js, npm and grunt installed in order to build a minified version of Flowtime.js and to autoprefix CSS files.
You can install dependencies by running

npm install

To create the minified build and autoprefixed CSS just run

grunt

How to Include Flowtime.js in Your Projects

Include the required CSS inside the <head> tag in your document. You have to include the css/flowtime.css file and a theme CSS file; Flowtime.js comes with the css/themes/default.css theme.
Optional: you can also add some modifiers, like the Standard Ordered List one, from css/modifiers/standard-ol.css.

If you want to contribute to Flowtime.js development you can write your own theme or modifier and make a pull request.

Include the required JavaScript files at the bottom of your document, just before the </body> tag. You have to include both the js/brav1toolbox.js and js/flowtime.js files in this exact order:

<script src="js/brav1toolbox.js"></script>
<script src="js/flowtime.js"></script>

or the single js/flowtime.min.js file:

<script src="js/flowtime.min.js"></script>

How to Build the Markup

The markup of Flowtime.js is really simple and easy to learn. All you have to do is wrap some elements in a <div class="flowtime"> parent. Then create the sections applying class="ft-section" and the single pages applying class="ft-page". To better understand the markup take a look at this snippet:

    <div class="flowtime">
      <div class="ft-section">
        <div class="ft-page">Section 1 / Page 1</div>
        <div class="ft-page">Section 1 / Page 2</div>
      </div>
    </div>

If you want to use the alternate layout you have to add the class ft-cross to the Flowtime element and Flowtime.js takes care of the rest:

    <div class="flowtime ft-cross">
      <div class="ft-section">
        <div class="ft-page">Section 1 / Page 1</div>
        <div class="ft-page">Section 1 / Page 2</div>
      </div>
    </div>

Every single page is a full window view — or a single slide if you prefer — and it’s a relative formatting context. Even if you have only single slides ordered in a row you have to nest the pages in sections; take a look at this markup which creates two slides one aside the other:

    <div class="flowtime">
      <div class="ft-section">
        <div class="ft-page">Section 1 / Page 1</div>
      </div>
      <div class="ft-section">
        <div class="ft-page">Section 2 / Page 1</div>
      </div>
    </div>

Titles and Pages URL

Flowtime.js automatically sets the title in the browser’s tab on navigation reading it from the first h1 on the page. If you want to override a title, or use a different string instead of the heading content, you can set a data-title attribute to the page. You can add the data-title attribute both to ft-section and to ft-page elements; if a data-title attribute was found on a section it will be used to write the title in the browser tab with this schema:

<title> text content [ | data-title on ft-section ] | h1 text content or data-title on ft-page

A data-prog attribute is added to every div marked as ft-section or as ft-page in order to manage the navigation. If you want to customize the URL and the hashtag you can add some data attributes to any section or page. You can add the data-id attribute both to ft-section and to ft-page elements; if this attribute was found it will be used to build the page URL. To better understand the use of data attributes here it is an example:

    <div class="flowtime">
      <div class="ft-section" data-id="section-1">
        <div class="ft-page" data-id="page-1">
            <h1>Heading Title</h1>
            When navigating to this page the title will be "site name | Heading Title"
            and the URL will be "http://site_URL/#/section-1/page-1/"
        </div>
      </div>
      <div class="ft-section" data-title="Section 2 Title" data-id="section-2">
        <div class="ft-page" data-title="Page 1 Title" data-id="page-1">
            When navigating to this page the title will be "site name | Section 2 Title | Page 1 Title"
            and the URL will be "http://site_URL/#/section-2/page-1/"
        </div>
      </div>
      <div class="ft-section"data-id="section-3">
        <div class="ft-page" data-title="Page Title" data-id="page-1">
            When navigating to this page the title will be "site name | Page Title"
            and the URL will be "http://site_URL/#/section-3/page-1/"
        </div>
      </div>
    </div>

Fragments

If you want to reveal single elements of a page just add the class ft-fragment on the elements you want to discover step by step. Here is an example.

    <div class="flowtime">
      <div class="ft-section" data-title="Section 1 Title" data-id="section-1">
        <div class="ft-page" data-title="Page 1 Title" data-id="page-1">
            <p>First Paragraph; this text is visible from start.</p>
            <p class="ft-fragment">This paragraph shows up only when you navigate forward and disappears when you navigate back.</p>
        </div>
      </div>
    </div>

You can also add some classes to trigger special behaviours for fragments. The step class partially fades out a fragment when the next one is selected; use: <p class="ft-fragment step"> The shy class completely hides a fragment when it lose the focus; use: <p class="ft-fragment shy">

Parallax

If you want to enable the parallax effect on some elements add a parallax class to these elements and, optionally, set the parallax distance value adding a data-parallax attribute specifying the x and y values separated by a comma. If you don't specify a data-parallax attribute the default lengths will be used.

    <div class="flowtime">
      <div class="ft-section" data-id="section-1">
        <div class="ft-page" data-id="page-1">
            <p class="parallax">Parallaxed element. Will use the default lengths.</p>
            <p class="parallax" data-parallax="100,150">Parallaxed element. Will use the `data-parallax` attribute values.</p>
            <p class="parallax" data-parallax="200">Parallaxed element. Will use the `data-parallax` attribute value; x and y will be the same length.</p>
        </div>
      </div>
    </div>

Javascript API

Flowtime.js has a lot of useful configuration APIs, for customizing the experience and the installation, and navigation APIs, for controlling navigation and get the state of the application.

Configuration API

Flowtime.start();

Starts the application logic with custom options. Calling this method is optional (but highly recommended) unless you change some configuration parameters. If you doesn’t call the start() method Flowtime.js starts itself but some configuration parameters will be applied only after the first navigation action. You can pass as optional parameters the same parameters that are accepted by the gotoPage method (see below) to let the presentation navigating to a specific page at start.

Flowtime.updateNavigation(Boolean fireEvent);

Force the update of the navigation object which stores the data about every possible destination in the site (the sub pages). If you change the number of sub pages at runtime call this method after the DOM manipulation. When you update the navigation the navigationevent is fired. If you do not want to fire the event (or call the navigation callback) just pass false as a value.

Flowtime.showProgress(Boolean show);

Default false. Show the default progress when in page mode (the standard content navigation mode). The default progress is a miniature of the structure placed in the lower left corner with the current page highlighted. Clicking on a page thumb in the default progress indicator triggers the navigation to that page. The default value is false, so if you wanto to show the progress you have to call Flowtime.showProgress(true); and then start the presentation. Calling this API during the navigation causes the progress to appear or disappear manipulating the DOM so watch out for performance issues. You are not limited to the default progress indicator. If you want to build your own progress bar or another indicator with a custom logic you can listen for the navigation events and use the event properties (check out the event section).

Flowtime.fragmentsOnSide(Boolean show);

Default false. Enable the fragments navigation also on section navigation (left and right arrows) and not only on page navigation. If true it also set fragmentsOnBack to true.

Flowtime.fragmentsOnBack(Boolean show);

Default true. Shows or hide the fragments when navigating back from a section to a page with fragments inside.

Flowtime.fragmentsAlwaysOnOnceRevealed(Boolean show);

Default false. Keeps already revealed fragments always on when navigating back and forward. Works in both directions and with both Flowtime.fragmentsOnSide and Flowtime.fragmentsOnBack.

Flowtime.useHistory(Boolean use);

Default true. Enable or disable the use of HTML History API; If History API is not used Flowtime.js fallbacks on the hashchange event.

Flowtime.slideInPx(Boolean usePx);

Default false. If true performs the calculation for the container translation in pixels and not in % values. Use true if you want to alter the default placement of the sections (i.e. setting vertical-align different from top) or in any case the pages does not perfectly fit the viewport (i.e. Safari for Windows with the font-size: 0; bug).

Flowtime.useOverviewVariant(Boolean use);

Default false. Uses a built in overview variant which does not show all the pages in a single view but center the current page in the available space scroualtirlling the view when navigating with the arrows. In Webkit browsers the default overview mode can cause rendering problems if the pages are too much; using the variant you can minimize the problem.

Flowtime.defaultParallaxValues(Number x, [Number y]);

Sets the default values for parallax elements so you doesn’t have to set the values for every single element. If you only pass the x value the y value will be the same.

Flowtime.parallaxInPx(Boolean usePx);

Default false. By default all the parallax length are computed in % units. If true the length expressed in defaultParallaxValues and in data-parallax attributes will be computed in pixels.

Flowtime.autoplay(Boolean status, [Number delay], [Boolean autostart], [Boolean skipFragments]);

Sets the status of the autoplay feature. status parameter sets the autoplay flag to true or false, if true you can use play() and pause() functions to start and stop the autoplay. delay sets the time between the page navigation in milliseconds; the default value is 10 seconds (10000 milliseconds). If autostart is true the autoplay feature starts just right after this call (default true). skipFragments allows to go to the next page skipping all the fragments on the page (default false).

Flowtime.loop(Boolean loop);

Default false. If true you can loop the navigation both for the sections and for the pages so you can back to the start of the presentation navigating forward from the last page.

javascript Flowtime.clicker(Boolean clicker);


If passed `true` PageUp and PageDown keys are reconfigured to go to the previous and next page instead to the first and the last page of the section.
This option useful if you use some wireless presenter like the Logitech R400; see issue ([#15](https://github.com/marcolago/flowtime.js/issues/15)) for more information.

```javascript```
Flowtime.setCrossDirection(Boolean cross);

Force the cross direction layout for sections and pages at runtime. Pass trueto use the optional horizontal layout or pass false to use the standard vertical layout. Every related option will be automatically reconfigured. Related options are keyboard bindings, touchpad and touch gestures and pages coordinates cache.

Flowtime.setDebouncingDelay(Number value);

Set the debouncing delay time in milliseconds to trigger the event used for the scroll handler.

Flowtime.getTransitionTime(Number milliseconds);

Get the global navigation transition time in milliseconds.

Flowtime.setTransitionTime(Number milliseconds);

Set the global navigation transition time in milliseconds. This value overrides the time specified in CSS.

Flowtime.setMomentumScrollDelay(Number milliseconds);

Set the delay time used to ignore the scrollwheel events fired by the momentum scroll on MacOS. The default value is 4 times the default transition time. Tweak this value to fit your needs.

Section Navigation Options

Flowtime.js comes with a lot of ways to navigate through sections; you can set up your installation with some, simple to use, options to fit your needs.

Flowtime.gridNavigation(Boolean value);

Grid Navigation True (default) Demo
Grid Navigation False Demo

Default true. The default behaviour out-of-the-box. When navigating from section to section with left and right arrows (or swipe) you will go to the same page index of the previous or next sections, if available, or to the nearest (highest number) page if the section is shorter. If you set this to false you will ever go to the first page of every section instead.

Flowtime.backFromPageToTop(Boolean value);

Default false. If true when navigating to the previous section from the first page of the current section Flowtime.js always goes to the first page of the previous section.

Flowtime.nearestPageToTop(Boolean value);

Nearest Page To Top Demo

Default false. If true when navigating to a section that is shorter than the current one Flowtime.js always goes to the first page of the new section. This does not affect the navigation to sections longer than, or as, the current section.

Flowtime.rememberSectionsStatus(Boolean value);

Remember Sections Status Demo

Default false. If true Flowtime.js will remember the last page visited in every section and, when navigating from section to section, will go to the last page visited for that section. This setting overrides the gridNavigation one only for previously visited sections but use the gridNavigation and nearestPageToTop values for sections not visited yet.

Flowtime.rememberSectionsLastPage(Boolean value);

Remember Sections Last Page Demo

Default false. If true Flowtime.js will remember the last page visited in the last section and stores this value for horizontal navigation purposes. It’s similar to the gridNavigation(true) setting but when navigating from a section with less pages to a section with the at least as page as the index stored Flowtime.js goes to the index stored and not to the adjacent page. This setting overrides the rememberSectionsStatus one.

Flowtime.scrollTheSection(Boolean value);

Scroll the Section Demo

Default false. If true Flowtime.js will scroll only the current section and not the entire Flowtime wrapper. This could improve the performance while scrolling and is a nice effect if the wrapper doen not fill the screen.

Flowtime.toSectionsFromPages(Boolean value);

Default true. If false Flowtime.js will prevent next and previous page navigation via keyboard, mouse and scroll or via navigation APIs nextPage and prevPage, to go to the next or previous section. To go to the next or previous section you have to use section’s navigation options via keyboard, mouse and scroll or via APIs nextSection and prevSection or targeting a specific page.

Navigation API

Flowtime.prevSection([Boolean top]);` and `Flowtime.nextSection([Boolean top]);

Navigate to the previous or the next section. If the optional top parameter is true the section starts at the first page; if the top parameter is false the section starts at the page with the same index than the previous section or, if the index does not exist, at the last page available.

Flowtime.prev([Boolean jump]);` and `Flowtime.next([Boolean jump]);

Navigate to the previous or the next page or, if there are fragments, to the previous or next fragment. If the optional jump parameter is true all the fragments will be jumped.

Flowtime.prevFragment();` and `Flowtime.nextFragment();

Navigate to the previous or the next fragment.

Flowtime.gotoHome()

Navigate to the first page of the presentation.

Flowtime.gotoEnd()

Navigate to the last page of the presentation.

Flowtime.gotoTop()

Navigate to the first page of the current section.

Flowtime.gotoBottom()

Navigate to the last page of the current section.

Flowtime.gotoPage(Number sectionIndex, Number pageIndex)

Navigate to the section/page pair.

Flowtime.gotoPage(String sectionId, String pageId)

Navigate to the section/page pair.

Flowtime.gotoPage(HTMLElement target)

Navigate to the page element.

Flowtime.toggleOverview([Boolean back]);

Toggles the overview mode switching between overview and page mode. If the optional back parameter is true toggling the overview mode when in overview does not navigate to the highlighted page but will returns to the active page; default false.

Flowtime.showOverview(Boolean show, [Boolean back]);

Sets the overview mode to the given state. See Flowtime.toggleOverview([Boolean back]);.

Flowtime.play();

Starts the autoplay timer with the configured values (see Flowtime.autoplay() method) or with the default ones.

Flowtime.pause();

Pauses the autoplay timer without resetting the delay.

Flowtime.stop();

Stops the autoplay timer resetting the delay.

Disabling the Navigation via APIs

You can disable all the navigation logics together or selectively one by one via some API’s methods.

Flowtime.enableNavigation(Boolean links, Boolean keyboard, Boolean scroll, Boolean touch);

Enables the navigation logic. If you pass true for a parameter the navigation will be enabled for that input type. You can also use the shorthand Flowtime.enableNavigation(); instead of Flowtime.enableNavigation(true, true, true, true);.

Flowtime.disableNavigation(Boolean links, Boolean keyboard, Boolean scroll, Boolean touch);

Disables the navigation logic. If you pass true for a parameter the navigation will be disabled for that input type. You can also use the shorthand Flowtime.disableNavigation(); instead of Flowtime.disableNavigation(true, true, true, true);.

Flowtime.setLinksNavigation(Boolean enable);

Enables (true) or disables (false) the links navigation logic. If you disable the links navigation you will not be able to change slide via anchor links.

Flowtime.setKeyboardNavigation(Boolean enable);

Enables (true) or disables (false) the keyboard navigation logic. If you disable the links navigation you will not be able to change slide via arrow keys.

Flowtime.setScrollNavigation(Boolean enable);

Enables (true) or disables (false) the scroll navigation logic. If you disable the scroll navigation you will not be able to change slide via mouse scrollwheel or trackpad scroll gestures.

Flowtime.setTouchNavigation(Boolean enable);

Enables (true) or disables (false) the touch navigation logic. If you disable the touch navigation you will not be able to change slide via touch swipe gestures.

Flowtime.enableSectionNavigation(Boolean prev, Boolean next);
Flowtime.disableSectionNavigation(Boolean prev, Boolean next);

Enables or disables the section navigation for keyboard, scroll and touch inputs.
You can choose to enable or disable a single direction setting prev and next parameters.
The section navigation is enabled by default.

Flowtime.enablePageNavigation(Boolean prev, Boolean next);
Flowtime.disablePageNavigation(Boolean prev, Boolean next);

Enables or disables the page navigation for keyboard, scroll and touch inputs.
You can choose to enable or disable a single direction setting prev and next parameters.
The page navigation is enabled by default.

Data API

Flowtime.getSection();

Gets a reference to the current section HTML Element.

Flowtime.getPage();

Gets a reference to the current page HTML Element.

Flowtime.getSectionIndex();

Gets the index starting at 0 of the current section.

Flowtime.getPageIndex();

Gets the index starting at 0 of the current page.

Flowtime.getPrevSection();

Gets a reference to the previous section HTML Element.

Flowtime.getNextSection();

Gets a reference to the next section HTML Element.

Flowtime.getPrevPage();

Gets a reference to the previous page HTML Element.

Flowtime.getNextPage();

Gets a reference to the next page HTML Element.

Events and Callback

When navigating Flowtime.js dispatches a flowtimenavigation event useful for create custom behaviours and callbacks. You can register the event using Flowtime.addEventListener("flowtimenavigation", callback, useCapture); API. The callback receive an event parameter with some custom properties useful to manage the navigation status. Here it is the list of the properties, supposing the event parameter is named e:

e.section

The HTMLElement reference to the current section.

e.page

The HTMLElement reference to the current page.

e.sectionIndex

The current section index starting at 0.

e.pageIndex

The current page index starting at 0.

e.pastSectionIndex

The previous visited section index starting at 0.

e.pastPageIndex

The previous visited page index starting at 0.

e.prevSection

Boolean value, if true there is a previous section.

e.nextSection

Boolean value, if true there is a next section.

e.prevPage

Boolean value, if true there is a previous page.

e.nextPage

Boolean value, if true there is a next page.

e.fragment

If the navigation targets a fragment returns the fragment itself as HTMLElement, otherwise returns undefined.

e.fragmentIndex

Returns the index of the current fragment starting at 0; otherwise returns -1.

e.isOverview

Boolean value, true if the overview mode is on, false if the overview mode is off.

e.progress

The current page sequential index number starting at 0.

e.total

The last page sequential index.

e.isAutoplay

The status of the autoplay feature.

e.isLoopable

true if Flowtime.js is configured for looping.

If you prefer setting a callback instead of register an event to get the navigation data object you can do it with the onNavigation method:

Flowtime.onNavigation(callback);

callback is the function you want to be called every time Flowtime.js navigate. The callback function receive the same navigation data object as the event handler.

Customizing and Styling Default Components and Behaviours

As said before Flowtime.js comes with some default components like the two overview variants and a progress indicator. You can change the way these parts appears editing or overwriting some CSS properties.

Calculating the Completion Percentage for Custom Visualization

In the flowtimenavigation event handler calculate the progress in % using this formula:

    function navigationHandler(e)
    {
      var value = Math.round(e.progress * 100 / e.total);
      console.log('Completion: ' + value + '%');
    }

The first page of the first section ever returns 0 as progress value. progress and total values do not consider fragments.

Customize the Fragments Animation

Every animation in Flowtime.js is managed with native CSS3 transitions so if you would customize the fragment animation (and you want to do this on a website, I know) just edit the following CSS classes to override the transitions or set the default value of the opacity to 1.

  .ft-fragment {
    opacity: 0;
    transition: all 0.3s cubic-bezier(.77, .10, .22, 1);
  }

  .ft-fragment.revealed, .ft-fragment.revealed-temp {
    opacity: 1;
  }

  .ft-overview .ft-default-progress {
    opacity: 0;
    pointer-events: none;
  }

Customize the Look of Pages in Overview Mode

To customize the way the thumbnails in overview mode look when idle, hovered and higlighted edit or override this CSS classes:

  /* default progress page thumb */

  .ft-page-thumb {
    box-sizing: border-box;
    width: 1rem;
    height: 0.7rem;
    margin-right: 1px;
    margin-bottom: 1px;
    background-color: rgba(0,0,0,0.7);
    cursor: pointer;
    transition: background-color 0.5s;
  }

  .ft-page-thumb:hover {
    background-color: rgba(255,255,255,0.7);
  }

  .ft-page-thumb.actual {
    background-color: rgba(255,255,255,0.5);
    border: 1px solid #ffffff;
  }

  /* overview mode page highlighting */

  .ft-overview .ft-page.actual {
    opacity: 0.3;
  }

  .ft-overview .ft-page.hilite {
    opacity: 1;
  }

  .ft-overview .ft-page:hover {
    opacity: 1;
  }