Instant Swipe (c5.6)

Documentation

Installing the Instant Swipe addon will provide the Instant Swipe block. There are no dashboard pages.

Getting Started

To use Instant Swipe you need to know a little bit about CSS or JQuery selectors. For each Instant Swipe block you will need to provide a selector for:

  • A unique selector for the region where it is watching for swipes.
  • A unique selector for where it will trigger events for each type of swipe. This will usually be the "Next" or "Previous" buttons, but can be anything.

Go to a page to which you want to add swipe behaviour and click to put it in edit mode. A nice easy candidate is a page with a gallery such as Sortable Fancybox Gallery, however you could just as easily get started with any of the Swipe Configurations listed later on this page or with a bit of selector knowledge easily create your own. 

Beneath the gallery block, add an Instant Swipe block.

In the Swipe Region tab, add a selector for the region that will respond to swipes. For Sortable Fancybox Gallery this will typically be "#fancybox-outer".

In the Events Triggered tab, add a selector for each of the next and previous buttons to the Swipe Left and Swipe Right sections respectively. For Sortable Fancybox Gallery this will typically be "#fancybox-right-ico" and "#fancybox-left-ico". For the event to trigger, select "Click" for both left and right.

What this means is that when a Left Swipe is detected on "#fancybox-outer", the button "#fancybox-right-ico" will be clicked. Similarly, when a Right Swipe is made on "#fancybox-outer", the button "#fancybox-left-ico" will be clicked.

Note how the naming of buttons and directions may at first appear counter intuitive. However, swiping left to ascend in a list and right to descend in a list are the behaviours users expect in most situations.

Save the block, publish the page and try it out. By default, Instant Swipe will also respond to mouse gestures, so you can make an initial test straight from your desktop browser. However, don't forget to also check the swipes behave as you want on a range of touch screen devices.

 

In More Detail

Swipe Region tab

Minimum length of swipe governs how long a swipe has to be in pixels before it is recognised.

Time limit for swipe to occur within creates a cutoff limit in milliseconds. Any touch-hold-move gesture taking longer than this will not trigger a swipe.

Swipes are compound events combining a sequence of touch-hold-move. Scrolling and other gestures within the swipe region will be partially blocked by the act of watching for swipes. When there are no up or down swipe gestures configured, X-Y wobble can be used to set an up-down limit that left or right swipes must remain within. This can facilitate browser scrolling within the swipe region.

Disable on desktop will prevent Instant Swipe from supporting mouse equivalent gestures on non-touch devices.

Show a hand cursor over swipe region will only show a hand cursor on desktop browsers as touch devices usually do not show cursors!

Again because swipes are compound events combining a sequence of touch-hold-move, a browser may interpret the similar sequences of events as text selection. Checking Prevent text selection during swipe will block text selection within the swipe region.

Swipe event handlers are attached directly to the selector for the swipe region. If a swipe region is being created and removed by other JavaScript this can result in the event handler not attaching. Checking Delegate event handling will result in the event handler being attached directly to the document body with the swipe region selector being used to delegate events. This can be less efficient, but has the advantage of being more tolerant swipe regions that appear and disappear.

Events Triggered tab

Swipe events can be set up for any of

  • Swipe Left
  • Swipe Right
  • Swipe Up
  • Swipe Down

Note that configuring swipe events may block other touch screen gestures such as scrolling, particularly when Swipe Up or Swipe Down gestures are configured. The X-Y wobble slider can be used to make this more or less sensitive. It is important to note that X-Y wobble appropriate to one swipe device may not be appropriate to another device. A good value to start with is 10 or 20 pixels.

The event to trigger can be any of:

none

No event will be triggered. Use this to disable a swipe

Click

A click event will be triggered directly on the selected element.

Change

A change event will be triggered directly on the selected element.

Submit

A submit event will be triggered directly on the selected element.

Click nearest link

If the selected element is a link, a click event will be triggered on the selected element. If the selected element is not a link, a click event will be triggered on the first descendant element that is a link.

Force Navigation

Some browsers will not navigate to other pages when a click event on a link element is triggered from a script. Force Navigation will look for the href attribute of a link or of the first descendant link and then force a browser navigation to the url in the href attribute.

Click prev/next in list

Sometimes you will want to move through a list that does not have previous or next buttons to click, such as a set of tabs like Magic Tabs. With Click previous in list and Click next in list the selector should be the currently selected 'li' item in a list or any child of that item, such as a link. Instant Swipe will then look for the respective previous or next item in the list and click that, or whatever child is clickable, as for Click nearest link.

Force Navigation prev/next in list

If the list you want to move through contains external links, such as an Autonav block, using Force Navigation previous in list and Force Navigation next in list will combine the behaviour of Click prev/next in list with Force Navigation.

Developer Assistance tab

When checked, Enable developer assistance will place differently coloured dashed outlines about the swipe region and the swipe event targets.

  • The swipe region - pink.
  • The swipe left target - red.
  • The swipe left target - green.
  • The swipe left target - blue.
  • The swipe left target - yellow.

These may interfere with other page styling and CSS, so should only be enabled during development. Developer assistance will also log copious traces of swipe events to the developer console.

 

Swipe Configurations

Some Instant Swipe configurations to use.

Sortable Fancybox Gallery

  • Swipe Region: "#fancybox-outer"
  • Swipe Left: "#fancybox-right-ico" Click
  • Swipe Right: "#fancybox-left-ico" Click

This will add swipe behaviour to all Sortable Fancybox Gallery blocks on the page.

Page List, default template

  • Swipe Region: ".ccm-page-list,.ccm-pagination"
  • Swipe Left: ".ccm-page-right" Force Navigation
  • Swipe Right: ".ccm-page-left" Force Navigation

If there is more than one Page List on a page, you should also name the block to limit selectors to specific page lists.

  • Swipe Region: "#page_list_block_name .ccm-page-list, .page_list_block_name .ccm-pagination"
  • Swipe Left: "#page_list_block_name .ccm-page-right" Force Navigation
  • Swipe Right: "#page_list_block_name .ccm-page-left" Force Navigation

Uber List

  • Swipe Region: ".uber_list_container"
  • Swipe Left: ".uber_list_paginate_container a.uber_list_next_inner" Click
  • Swipe Right: ".uber_list_paginate_container a.uber_list_prev_inner" Click

As with the Page List, If there is more than one Uber List on a page you should also name the block to limit selectors to specific Uber Lists.

Fluid Gallery

  • Swipe Region: "#lightbox-wrap"
  • Swipe Left: "#lightbox-right-ico" Click
  • Swipe Right: "#lightbox-left-ico" Click

This will add swipe behaviour to all Fluid Gallery blocks on the page.

Lightbox Gallery

  • Swipe Region: ".lb-container"
  • Swipe Left: "a.lb-next:visible" Click
  • Swipe Right: "a.lb-prev:visible" Click

This will add swipe behaviour to all Lightbox Gallery blocks on the page. Note the addition of the ":visible" filter on the selector. Without this filter, the display could go past the ends of the gallery!

Superbox Gallery

  • Swipe Region: "#my_block_name .superbox-show"
  • Swipe Left: "#my_block_name .superbox-show a.superbox-next" Click
  • Swipe Right: "#my_block_name .superbox-show a.superbox-prev" Click

Because Superbox Gallery shows within the page, if there is more than one on the page the selectors will also need a #block_name, as with Page List.

Webslider

  • Swipe Region: "#my_block_name .web_slider"
  • Swipe Left: "#my_block_name .web_slider .previous" Click
  • Swipe Right: "#my_block_name .web_slider .next" Click

Because Webslider shows within the page, if there is more than one on the page the selectors will also need a #block_name, as with Page List. Also of note is that swipe left triggers the previous button and right triggers the next button. Finally, the buttons are just classes, not 'a' elements like many galleries display.

Nivo Gallery

  • Swipe Region: "#my_block_name .nivoGallery"
  • Swipe Left: "#my_block_name .nivoGallery a.nivoGallery-next" Click
  • Swipe Right: "#my_block_name .nivoGallery a.nivoGallery-prev" Click

Because Nivo Gallery shows within the page, if there is more than one on the page the selectors will also need a #block_name, as with Page List. 

Whale jCarousel

  • Swipe Region: "#my_block_name .jcarousel-container"
  • Swipe Left: "#my_block_name  .jcarousel-container .jcarousel-next" Click
  • Swipe Right: "#my_block_name  .jcarousel-container .jcarousel-prev" Click

Because Whale jCarousel shows within the page, if there is more than one on the page the selectors will also need a #block_name, as with Page List. Note that the prev and next selectors do not use 'a' elements, so are just styles.

Magic Tabs

Magic Tabs creates classes based on the context it creates tabs in. For the purposes of this example, we will assume there is a single set of Magic Tabs in the Main area of a page with a Greek Yogurt theme.

  • Swipe Region: "#main-content-inner .jl_magic_tabs_main"
  • Swipe Left: "#main-content-inner .jl_magic_tabs_main.jl_magic_tabs_controls li.ccm-nav-active" Click next in list
  • Swipe Right: "#main-content-inner .jl_magic_tabs_main.jl_magic_tabs_controls li.ccm-nav-active" Click prev in list

The above will make the entire tab area swipe sensitive. You can see it in action on the home page of my c5magic site. If you would prefer just the tabs themselves to be swipe sensitive, the Swipe Region can be refined to just:

  • Swipe Region: "#main-content-inner .jl_magic_tabs_main.jl_magic_tabs_controls"

Autonav

For this example, we will add swipe behaviour to the header navigation in a Greek Yogurt theme. The Instant Swipe block should be inserted into the Sitewide Header Nav global area. The Autonav is a small target to swipe over, so we will use the entire header region of the theme as a swipe target.

  • Swipe Region: "#header"
  • Swipe Left: "#header ul.nav li.nav-selected" Force Navigation next in list
  • Swipe Right: "#header ul.nav li.nav-selected" Force Navigation prev in list

With this  Instant Swipe block in the global Header Nav area, every page in the site will now have swipe navigation to link to the previous or next page in the Autonav list.

Image Slider

  • Swipe Region: "#my_block_name .ccm-imageSlider-wrapper"
  • Swipe Left: "#my_block_name  .ccm-imageSlider-wrapper span.ccm-imageSlider-nextBtn" Click nearest link
  • Swipe Right: "#my_block_name  .ccm-imageSlider-wrapper span.ccm-imageSlider-prevBtn" Click nearest link

The core team Image Slider block shows within the page, so if there is more than one on the page the selectors will also need a #block_name, as with Page List. Note that the prev and next 'a' link elements do not have a convenient selector, so the surrounding span elements are selected and Click nearest link used so Instant Swipe will then find the appropriate 'a' element to click.

Advanced Slider

  • Swipe Region: "#my_block_name ul.slides"
  • Swipe Left: "#my_block_name  .slide-wrapper .slide-arrows .next" Click
  • Swipe Right: "#my_block_name  .slide-wrapper .slide-arrows .previous" Click

The Advanced Slider block shows within the page, so if there is more than one on the page the selectors will also need a #block_name, as with Page List or Image Slider. 

 

 


More Configurations

Please send me your Instant Swipe configurations and I will add them to this section.

 

For developers

The core functionality of Instant Swipe is built into a concrete5 helper, so supporting direct integration within other blocks or adding directly into page templates.

The triggered swipe events list is contained within its own model. If you want to extend it further events to trigger, you can override this model.

 

Older versions of concrete5

Instant Swipe will only be supported with concrete5 for versions 5.6+. The block is actually capable of working as far back as concrete5.5, the earliest concrete5 version where the requisite jQuery 1.7 is available.

To install, you would need to edit the minimum version given in the Instant Swipe package controller. Whilst it will install and work quite happilly with concrete5.5, you will need to fumble your way through a muddled block edit dialog when adding Instant Swipe blocks to concrete5.5 sites.