Yaffs site version 1.1

[yaffs-website] / web / modules / contrib / slick / slick_ui / README.html

<h2>Slick Carousel</h2>

<p>Slick is a powerful and performant slideshow/carousel solution leveraging Ken<br />
Wheeler's Slick carousel.<br />
See http://kenwheeler.github.io/slick</p>

<p>Slick has gazillion options, please start with the very basic working<br />
samples from <a href="http://dgo.to/slick_extras">slick_example</a> only if trouble to build slicks. Be sure to read<br />
its README.txt. Spending 5 minutes or so will save you hours in building more<br />
complex slideshows.</p>

<p>The module supports Slick 1.6 above.<br />
Slick 2.x is just out 9/21/15, and hasn't been officially supported now, 9/27.</p>

<h3>REQUIREMENTS</h3>

<ul>
  <li>Slick library:  <br />
    <ul>
      <li>Download Slick archive &gt;= 1.6 from https://github.com/kenwheeler/slick/</li>
      <li>Extract it as is, rename "slick-master" to "slick", so the assets are at:<br />
        <em>/libraries/slick/slick/slick.css</em><br />
        <em>/libraries/slick/slick/slick-theme.css</em> (optional if a skin chosen)<br />
        <em>/libraries/slick/slick/slick.min.js</em>
      </li>
    </ul>
  </li>
  <li>Download jqeasing from https://github.com/gdsmith/jquery.easing, so available&nbsp; at:<br />
    <em>/libraries/easing/jquery.easing.min.js</em><br />
    This is CSS easing fallback for non-supporting browsers.</li>
  <li>Blazy.module, to reduce DRY stuffs, and as a bonus, advanced lazyloading
  such as delay lazyloading for below-fold sliders, iframe, (fullscreen) CSS
  background lazyloading, breakpoint dependent multi-serving images, lazyload
  ahead for smoother UX.</li>
</ul>

<p>&nbsp; Important! Enable Blazy first before updating Slick Alphas,<br />
&nbsp; otherwise a requirement error.</p>

<h3>FEATURES</h3>

<ul>
  <li>Fully responsive. Scales with its container.</li>
  <li>Uses CSS3 when available. Fully functional when not.</li>
  <li>Swipe enabled. Or disabled, if you prefer.</li>
  <li>Desktop mouse dragging.</li>
  <li>Fully accessible with arrow key navigation.</li>
  <li>Built-in lazyLoad, and multiple breakpoint options.</li>
  <li>Random, autoplay, pagers, arrows, dots/text/tabs/thumbnail pagers etc...</li>
  <li>Supports pure text, responsive image, iframe, video carousels with aspect ratio. No extra jQuery plugin FitVids is required. Just CSS.</li>
  <li>Works with Views, core and contrib fields: Image, Media Entity.</li>
  <li>Optional and modular skins, e.g.: Carousel, Classic, Fullscreen, Fullwidth, Split, Grid or a multi row carousel.</li>
  <li>Various slide layouts are built with pure CSS goodness.</li>
  <li>Nested sliders/overlays, or multiple slicks within a single Slick via Views.</li>
  <li>Some useful hooks and drupal_alters for advanced works.</li>
  <li>Modular integration with various contribs to build carousels with multimedia lightboxes or inline multimedia.</li>
  <li>Media switcher: Image linked to content, Image to iframe, Image to colorbox, Image to photobox.</li>
  <li>Cacheability + lazyload = light + fast.</li>
</ul>

<h3>INSTALLATION</h3>

<p>Install the module as usual, more info can be found on:<br />
http://drupal.org/documentation/install/modules-themes/modules-7</p>

<p>The Slick module has several sub-modules:</p>

<ul>
  <li>slick_ui, included, to manage optionsets, can be uninstalled at production.</li>
  <li><a href="http://dgo.to/slick_media">slick_media</a>, to get richer contents using Media entity.</li>
  <li><a href="http://dgo.to/slick_video">slick_video</a>, to get video carousels using Video Embed Field.</li>
  <li><a href="http://dgo.to/slick_paragraphs">slick_paragraphs</a>, to get more complex slides at field level.</li>
  <li><a href="http://dgo.to/slick_views">slick_views</a>, to get more complex slides.</li>
  <li><a href="http://dgo.to/slick_extras">slick_extras</a> contains <strong>slick_devel</strong>, if you want to help testing and developing the Slick, and <strong>slick_example</strong>, to get up and running quickly.</li>
</ul>

<h3>OPTIONAL INTEGRATION</h3>

<p>Slick supports enhancements and more complex layouts.</p>

<ul>
  <li>Colorbox, to have grids/slides that open up image/video in overlay.</li>
  <li>Photobox, idem ditto.</li>
  <li>Responsive image, in core, to get truly responsive image.</li>
  <li><a href="http://dgo.to/media_entity">Media Entity</a>, to have richer contents: image, video, or a mix of em.</li>
  <li><a href="http://dgo.to/video_embed_field">Video Embed Media</a>, idem ditto.</li>
  <li><a href="http://dgo.to/paragraphs">Paragraphs</a>, to get more complex slides at field level.</li>
  <li>Mousewheel, download from https://github.com/brandonaaron/jquery-mousewheel, so it is available at:<br />
  <em>/libraries/mousewheel/jquery.mousewheel.min.js</em></li>
</ul>

<p>&nbsp;</p>

<h3>OPTIONSETS</h3>

<p>To create optionsets, go to:</p>

<p><em>&nbsp; admin/config/media/slick</em></p>

<p>Enable Slick UI sub-module first, otherwise regular "Access denied".<br />
They will be available at field formatter "Manage display", and Views UI.</p>

<h3>VIEWS AND FIELDS</h3>

<p>Slick works with Views and as field display formatters.<br />
Slick Views is available as a style plugin included at slick_views.module.<br />
Slick field formatter included as a plugin which supports core: Image, Text.</p>

<h3>PROGRAMATICALLY</h3>

<p>See slick.api.php for samples.</p>

<h3>NESTED SLICKS</h3>

<p>Nested slick is a parent Slick containing slides which contain individual child<br />
slick per slide. The child slicks are basically regular slide overlays like<br />
a single video over the large background image, only with nested slicks it can<br />
be many videos displayed as a slideshow as well.<br />
Use Slick Paragraphs or Views to build one.<br />
Supported multi-value fields for nested slicks: Image, Text, VEF, Media entity.</p>

<h3>SKINS</h3>

<p>The main purpose of skins are to demonstrate that often some CSS lines are<br />
enough to build fairly variant layouts. No JS needed. Unless, of course, for<br />
more sophisticated slider like spiral 3D carousel which is beyond what CSS can<br />
do. But more often CSS will do.</p>

<p>Skins allow swappable layouts like next/prev links, split image or caption, etc.<br />
with just CSS. However a combination of skins and options may lead to<br />
unpredictable layouts, get yourself dirty. Use the provided samples to see<br />
the working skins.</p>

<p>Some default complex layout skins applied to desktop only, adjust for the mobile<br />
accordingly. The provided skins are very basic to support the necessary layouts.<br />
It is not the module job to match your awesome design requirements.</p>

<h4><strong>Optional skins:</strong></h4>

<p><strong>- None</strong><br />
&nbsp; It is all about DIY.<br />
&nbsp; Doesn't load any extra CSS other than the basic styles required by slick.<br />
&nbsp; Skins at the optionset are ignored, only useful to fetch description and<br />
&nbsp; your own custom work when not using the sub-modules, nor plugins.<br />
&nbsp; If using individual slide layout, do the layouts yourself.</p>

<p><strong>- Classic</strong><br />
&nbsp; Adds dark background color over white caption, only good for slider (single<br />
&nbsp; slide visible), not carousel (multiple slides visible), where small captions<br />
&nbsp; are placed over images, and animated based on their placement.</p>

<p><strong>- Full screen</strong><br />
&nbsp; Works best with 1 slidesToShow. Use z-index layering &gt; 8 to position elements<br />
&nbsp; over the slides, and place it at large regions. Currently only works with<br />
&nbsp; Slick fields, use Views to make it a block. Use Slick Paragraphs to<br />
&nbsp; have more complex contents inside individual slide, and assign it to Slide<br />
&nbsp; caption fields.</p>

<p><strong>- Full width</strong><br />
&nbsp; Adds additional wrapper to wrap overlay video and captions properly.<br />
&nbsp; This is designated for large slider in the header or spanning width to window<br />
&nbsp; edges at least 1170px width for large monitor. To have a custom full width<br />
&nbsp; skin, simply prefix your skin with "full", e.g.: fullstage, fullwindow, etc.</p>

<p><strong>- Split</strong><br />
&nbsp; Caption and image/media are split half, and placed side by side. This requires<br />
&nbsp; any layout containing "split", otherwise useless.</p>

<p><strong>- Grid</strong><br />
&nbsp; Only reasonable if you have considerable amount of slides.<br />
&nbsp; Uses the Foundation 5.5 block-grid, and disabled if you choose your own skin<br />
&nbsp; not named Grid. Otherwise overrides skin Grid accordingly.</p>

<p><strong>&nbsp; Requires:</strong><br />
&nbsp; Visible slides, Skin Grid for starter, A reasonable amount of slides,<br />
&nbsp; Optionset with Rows and slidesPerRow = 1.<br />
&nbsp; Avoid variableWidth and adaptiveHeight. Use consistent dimensions.<br />
&nbsp; This is module feature, older than core Rows, and offers more flexibility.<br />
&nbsp; Available at slick_views, and configurable via Views UI.</p>

<p>If you want to attach extra 3rd libraries, e.g.: image reflection, image zoomer,<br />
more advanced 3d carousels, etc, simply put them into js array of the target<br />
skin. Add proper weight, if you are acting on existing slick events,<br />
normally &lt; 0 (slick.load.min.js) is the one.</p>

<p>Use hook_slick_skins_info() and implement \Drupal\slick\SlickSkinInterface<br />
to register ones. Clear the cache once.</p>

<p>See slick.api.php for more info on skins.<br />
See \Drupal\slick\SlickSkinInterface.</p>

<p>Other skins are available at http://dgo.to/slick_extras<br />
Some extra skins are WIP which may not work as expected.</p>

<h3>GRID</h3>

<p>To create Slick grid or multiple rows carousel, there are 3 options:</p>

<ol>
<li>One row grid managed by library:<br />
  Visit <em>admin/config/media/slick</em><br />
  Edit current optionset, and set<br />
  slidesToShow &gt; 1, and Rows and slidesperRow = 1</li>
<li>Multiple rows grid managed by library:<br />
  Visit <em>admin/config/media/slick</em><br />
  Edit current optionset, and set<br />
  slidesToShow = 1, Rows &gt; 1 and slidesPerRow &gt; 1</li>
<li>Multiple rows grid managed by Module:<br />
  Visit <em>admin/structure/views/view/slick_x/edit/block_grid from slick_example</em><br />
  Install the Slick example sub-module first.<br />
  Requires skin "Grid", and slidesToShow, Rows and slidesPerRow = 1.</li>
</ol>

<p>The first 2 are supported by core library using pure JS approach.<br />
The last is the Module feature using pure CSS Foundation block-grid.</p>

<p>The key is:<br />
The total amount of Views results must be bigger than Visible slides, otherwise<br />
broken Grid, see skin Grid above for more details.</p>

<h3>HTML STRUCTURE</h3>

<p>Note, non-BEM classes are added by JS.</p>

<code>
&lt;div class="slick"&gt;<br />
&nbsp; &lt;div class="slick__slider slick-initialized slick-slider"&gt;<br />
&nbsp;&nbsp;&nbsp; &lt;div class="slick__slide"&gt;&lt;/div&gt;<br />
&nbsp; &lt;/div&gt;<br />
&nbsp; &lt;nav class="slick__arrow"&gt;&lt;/nav&gt;<br />
&lt;/div&gt;
</code>
<p>asNavFor should target slick-initialized class/ID attributes.</p>

<h3>BUG REPORTS OR SUPPORT REQUESTS</h3>

<p>A basic knowledge of Drupal site building is required. If you get stuck:</p>

<ul>
  <li>consult the provided READMEs,</li>
  <li>descriptions on each form item,</li>
  <li>the relevant guidelines from the supported modules,</li>
  <li>consider the project issue queues, your problem may be already addressed,</li>
  <li>install slick_example.</li>
</ul>

<p>If you do have bug reports, we love bugs, please:</p>

<ul>
  <li>provide steps to reproduce it,</li>
  <li>provide detailed info, a screenshot of the output and Slick form, or words to identify it any better,</li>
  <li>make sure that the bug is caused by the module.</li>
</ul>

<p>For the Slick library bug, please report it to the actual library:<br />
&nbsp; https://github.com/kenwheeler/slick</p>

<p>You can create a fiddle to isolate the bug if reproduceable outside the module:<br />
&nbsp; http://jsfiddle.net/</p>

<p>For the support requests, a screenshot of the output and Slick form are helpful.<br />
Shortly, you should kindly help the maintainers with detailed info to help you.<br />
Thanks.</p>

<h3>TROUBLESHOOTING</h3>
<ul>
  <li>When upgrading from Slick v1.3.6 to later version, try to resave options at:<br />
    <ul>
      <li><em>admin/config/media/slick</em></li>
      <li><em>admin/structure/types/manage/CONTENT_TYPE/display</em></li>
      <li><em>admin/structure/views/view/VIEW_NAME</em><br />
      only if trouble to see the new options, or when options don't apply properly.<br />
      Most likely true when the library adds/changes options, or the module<br />
      does something new. This is normal for any library even commercial ones, so<br />
      bear with it.</li>
    </ul>
  </li>
  <li>Always clear the cache, and re-generate JS (if aggregation is on) when<br />
  updating the module to ensure things are picked up:<br />
  <em>admin/config/development/performance</em></li>
  <li>If you are customizing template files, or theme functions, re-check against the latest.</li>

  <li>Slick release is similar, or later than Blazy.</li>
</ul>

<h3>KNOWN ISSUES</h3>

<ul>
  <li>Slick admin CSS may not be compatible with private or contrib admin<br />
  themes. Only if trouble with admin display, please disable it at:<br />
  admin/config/media/blazy</li>
  <li>The Slick lazyLoad is not supported with Responsive image. Slick only<br />
  facilitates Responsive image to get in. The image formatting is taken over by<br />
  Responsive image.<br />
  Some other options such as Aspect ratio is currently not supported either.</li>
  <li>Photobox is best for:<br />
  - infinite true + slidesToShow 1<br />
  - infinite false + slidesToShow N<br />
  If "infinite true + slidesToShow &gt; 1" is a must, but you don't want dup<br />
  thumbnails, simply override the JS to disable 'thumbs' option.</li>
  <li>The following is not module related, but worth a note:<br />
    <ul>
      <li>lazyLoad ondemand has issue with dummy image excessive height.<br />
      Added fixes to suppress it via option Aspect ratio (fluid | enforced).<br />
      Or use Blazy lazyload for more advanced options.</li>
      <li>Aspect ratio is not compatible with Responsive image or multi-serving<br />
      images.<br />
      However if you can stick to one Aspect ratio, choose 'enforced' instead.<br />
      Otherwise disable Aspect ratio for multi-serving images.</li>
      <li>If the total &lt; slidesToShow, Slick behaves. Previously added a workaround to<br />
      fix this, but later dropped and handed over to the core instead.<br />
      Brought back the temp fix for 1.6+ as per 10/18/16:<br />
      See https://github.com/kenwheeler/slick/issues/262</li>
      <li>Fade option with slideToShow &gt; 1 will screw up.</li>
      <li>variableWidth ignores slidesToShow.</li>
      <li>Too much centerPadding at small device affects slidesToShow.</li>
      <li>Infinite option will create duplicates or clone slides which look more<br />
      obvious if slidesToShow &gt; 1. Simply disable it if not desired.</li>
      <li>If thumbnail display is Infinite, the main one must be infinite too, else<br />
      incorrect syncing.</li>
      <li>adaptiveHeight is no good for vertical.</li>
    </ul>
  </li>
</ul>

<h3>CURRENT DEVELOPMENT STATUS</h3>

<p>A full release should be reasonable after proper feedback from the community,<br />
some code cleanup, and optimization where needed. Patches are very much welcome.</p>

<p>Alpha and Beta releases are for developers only. Be aware of possible breakage.</p>

<p>However if it is broken, unless an update is explicitly required, clearing cache<br />
should fix most issues during DEV phases.</p>
<ul>
  <li>Prior to any update, always visit:
  <em>/admin/config/development/performance</em></li>
  <li>Hit "Clear all caches" button once the new Slick is in place.</li>
  <li>Regenerate CSS and JS as the latest fixes may contain changes to the assets.</li>
  <li>Have the latest or similar release Blazy to avoid trouble in the first place.</li>
</ul>

<h3>ROADMAP</h3>

<p>- Bug fixes, code cleanup, optimization, and full release.</p>

<h3>HOW CAN YOU HELP?</h3>

<p>Please consider helping in the issue queue, provide improvement, or helping with documentation.</p>

<p>If you find this module helpful, please help back spread the love. Thanks.</p>

<h3>QUICK PERFORMANCE TIPS</h3>
<ul>
  <li>Use lazyLoad "ondemand" / "anticipated" for tons of images, not "progressive".
   Unless within an ajaxified lightbox.</li>
  <li>Choose lazyload "Blazy" for carousels below the fold to delay loading them.</li>
  <li>Tick "Optimized" option on the top right of Slick optionset edit page.</li>
  <li>Use image style with regular sizes containing effect "crop" in the name. This
  way all images will inherit dimensions calculated once.</li>
  <li>Disable core library "slick-theme.css" as it contains font "slick" which
  may not be in use when using own icon font at:
  /admin/config/media/slick/ui</li>
  <li>Use Blazy multi-serving images, Responsive image, or Picture, accordingly.</li>
  <li>Uninstall Slick UI at production.</li>
  <li>Enable Drupal cache, and CSS/ JS assets aggregation.</li>
</ul>

<h3>AUTHOR/MAINTAINER/CREDITS</h3>

<p>Slick 8.x-1.x by gausarts, and other authors below.<br />
Slick 7.x-2.x by gausarts, inspired by Flexslider with CTools integration.<br />
Slick 7.x-1.x by arshadcn, the original author.</p>

<p>- https://www.drupal.org/node/2232779/committers<br />
- CHANGELOG.txt for helpful souls with their patches, suggestions and reports.</p>

<h3>READ MORE</h3>

<p>See the project page on drupal.org: http://drupal.org/project/slick.</p>

<p>More info relevant to each option is available at their form display by hovering<br />
over them, and click a dark question mark.</p>

<p><strong>See the Slick docs at:</strong><br />
- http://kenwheeler.github.io/slick/<br />
- https://github.com/kenwheeler/slick/</p>