www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/slick/README.txt

   1
   2 Slick Carousel
   3 ================================================================================
   4
   5 Slick is a powerful and performant slideshow/carousel solution leveraging Ken
   6 Wheeler's Slick carousel.
   7 See http://kenwheeler.github.io/slick
   8
   9 Powerful: Slick is one of the sliders [1], as of 9/15, the only one [2], which
  10 supports nested sliders and a mix of lazy-loaded image/video with
  11 image-to-iframe or multimedia lightbox switchers.
  12 See below for the supported media.
  13
  14 Performant: Slick is stored as plain HTML the first time it is requested, and
  15 then reused on subsequent requests. Carousels with cacheability and lazyload
  16 are lighter and faster than those without.
  17
  18 Slick has gazillion options, please start with the very basic working
  19 samples from slick_example [3] only if trouble to build slicks. Be sure to read
  20 its README.txt. Spending 5 minutes or so will save you hours in building more
  21 complex slideshows.
  22
  23 The module supports Slick 1.6 above.
  24 Slick 2.x is just out 9/21/15, and hasn't been officially supported now, 9/27.
  25
  26 [1] https://groups.drupal.org/node/20384
  27 [2] https://www.drupal.org/node/418616
  28 [3] http://dgo.to/slick_extras
  29
  30
  31 REQUIREMENTS
  32 --------------------------------------------------------------------------------
  33 - Slick library:
  34   o Download Slick archive >= 1.6 from https://github.com/kenwheeler/slick/
  35   o Extract it as is, rename "slick-master" to "slick", so the assets are at:
  36
  37     /libraries/slick/slick/slick.css
  38     /libraries/slick/slick/slick-theme.css (optional if a skin chosen)
  39     /libraries/slick/slick/slick.min.js
  40
  41 - Download jqeasing from https://github.com/gdsmith/jquery.easing, so available
  42   at:
  43   /libraries/easing/jquery.easing.min.js
  44   This is CSS easing fallback for non-supporting browsers.
  45
  46 - Blazy.module, to reduce DRY stuffs, and as a bonus, advanced lazyloading
  47   such as delay lazyloading for below-fold sliders, iframe, (fullscreen) CSS
  48   background lazyloading, breakpoint dependent multi-serving images, lazyload
  49   ahead for smoother UX.
  50
  51   Important! Be sure to enable Blazy first before updating Slick Alphas,
  52   otherwise a requirement error.
  53
  54 FEATURES
  55 --------------------------------------------------------------------------------
  56 o Fully responsive. Scales with its container.
  57 o Uses CSS3 when available. Fully functional when not.
  58 o Swipe enabled. Or disabled, if you prefer.
  59 o Desktop mouse dragging.
  60 o Fully accessible with arrow key navigation.
  61 o Built-in lazyLoad, and multiple breakpoint options.
  62 o Random, autoplay, pagers, arrows, dots/text/tabs/thumbnail pagers etc...
  63 o Supports pure text, responsive image, iframe, video carousels with
  64   aspect ratio. No extra jQuery plugin FitVids is required. Just CSS.
  65 o Works with Views, core and contrib fields: Image, Media Entity.
  66 o Optional and modular skins, e.g.: Carousel, Classic, Fullscreen, Fullwidth,
  67   Split, Grid or a multi row carousel.
  68 o Various slide layouts are built with pure CSS goodness.
  69 o Nested sliders/overlays, or multiple slicks within a single Slick via Views.
  70 o Some useful hooks and drupal_alters for advanced works.
  71 o Modular integration with various contribs to build carousels with multimedia
  72   lightboxes or inline multimedia.
  73 o Media switcher: Image linked to content, Image to iframe, Image to colorbox,
  74   Image to photobox.
  75 o Cacheability + lazyload = light + fast.
  76
  77
  78 INSTALLATION
  79 --------------------------------------------------------------------------------
  80 Install the module as usual, more info can be found on:
  81 http://drupal.org/documentation/install/modules-themes/modules-7
  82
  83 The Slick module has several sub-modules:
  84 - slick_ui, included, to manage optionsets, can be uninstalled at production.
  85
  86 - slick_media [1], to get richer contents using Media entity.
  87
  88 - slick_video [2], to get video carousels using Video Embed Field.
  89
  90 - slick_paragraphs [3], to get more complex slides at field level.
  91
  92 - slick_views [4], to get more complex slides.
  93
  94 - slick_devel, if you want to help testing and developing the Slick.
  95 - slick_example, to get up and running quickly.
  96   Both are included in slick_extras [5].
  97
  98
  99 [1] http://dgo.to/slick_media
 100 [2] http://dgo.to/slick_video
 101 [3] http://dgo.to/slick_paragraphs
 102 [4] http://dgo.to/slick_views
 103 [5] http://dgo.to/slick_extras
 104
 105
 106
 107 OPTIONAL INTEGRATION
 108 --------------------------------------------------------------------------------
 109 Slick supports enhancements and more complex layouts.
 110
 111 - Colorbox, to have grids/slides that open up image/video in overlay.
 112 - Photobox, idem ditto.
 113 - Responsive image, in core, to get truly responsive image.
 114 - Media Entity, to have richer contents: image, video, or a mix of em.
 115   http://dgo.to/media_entity
 116 - Video Embed Media, idem ditto.
 117   http://dgo.to/video_embed_field
 118 - Paragraphs, to get more complex slides at field level.
 119   http://dgo.to/paragraphs
 120 - Mousewheel, download from https://github.com/brandonaaron/jquery-mousewheel,
 121   so it is available at:
 122   /libraries/mousewheel/jquery.mousewheel.min.js
 123
 124
 125
 126 OPTIONSETS
 127 --------------------------------------------------------------------------------
 128 To create optionsets, go to:
 129
 130   admin/config/media/slick
 131
 132 Be sure to enable Slick UI sub-module first, otherwise regular "Access denied".
 133 They will be available at field formatter "Manage display", and Views UI.
 134
 135
 136 VIEWS AND FIELDS
 137 --------------------------------------------------------------------------------
 138 Slick works with Views and as field display formatters.
 139 Slick Views is available as a style plugin included at slick_views.module.
 140 Slick field formatter included as a plugin which supports core: Image, Text.
 141
 142
 143 PROGRAMATICALLY
 144 --------------------------------------------------------------------------------
 145 See slick.api.php for samples.
 146
 147
 148 NESTED SLICKS
 149 --------------------------------------------------------------------------------
 150 Nested slick is a parent Slick containing slides which contain individual child
 151 slick per slide. The child slicks are basically regular slide overlays like
 152 a single video over the large background image, only with nested slicks it can
 153 be many videos displayed as a slideshow as well.
 154 Use Slick Paragraphs or Views to build one.
 155 Supported multi-value fields for nested slicks: Image, Text, VEF, Media entity.
 156
 157
 158 SKINS
 159 --------------------------------------------------------------------------------
 160 The main purpose of skins are to demonstrate that often some CSS lines are
 161 enough to build fairly variant layouts. No JS needed. Unless, of course, for
 162 more sophisticated slider like spiral 3D carousel which is beyond what CSS can
 163 do. But more often CSS will do.
 164
 165 Skins allow swappable layouts like next/prev links, split image or caption, etc.
 166 with just CSS. However a combination of skins and options may lead to
 167 unpredictable layouts, get yourself dirty. Use the provided samples to see
 168 the working skins.
 169
 170 Some default complex layout skins applied to desktop only, adjust for the mobile
 171 accordingly. The provided skins are very basic to support the necessary layouts.
 172 It is not the module job to match your awesome design requirements.
 173
 174 Optional skins:
 175 --------------
 176 - None
 177   It is all about DIY.
 178   Doesn't load any extra CSS other than the basic styles required by slick.
 179   Skins at the optionset are ignored, only useful to fetch description and
 180   your own custom work when not using the sub-modules, nor plugins.
 181   If using individual slide layout, do the layouts yourself.
 182
 183 - Classic
 184   Adds dark background color over white caption, only good for slider (single
 185   slide visible), not carousel (multiple slides visible), where small captions
 186   are placed over images, and animated based on their placement.
 187
 188 - Full screen
 189   Works best with 1 slidesToShow. Use z-index layering > 8 to position elements
 190   over the slides, and place it at large regions. Currently only works with
 191   Slick fields, use Views to make it a block. Use Slick Paragraphs to
 192   have more complex contents inside individual slide, and assign it to Slide
 193   caption fields.
 194
 195 - Full width
 196   Adds additional wrapper to wrap overlay video and captions properly.
 197   This is designated for large slider in the header or spanning width to window
 198   edges at least 1170px width for large monitor. To have a custom full width
 199   skin, simply prefix your skin with "full", e.g.: fullstage, fullwindow, etc.
 200
 201 - Split
 202   Caption and image/media are split half, and placed side by side. This requires
 203   any layout containing "split", otherwise useless.
 204
 205 - Grid
 206   Only reasonable if you have considerable amount of slides.
 207   Uses the Foundation 5.5 block-grid, and disabled if you choose your own skin
 208   not named Grid. Otherwise overrides skin Grid accordingly.
 209
 210   Requires:
 211   Visible slides, Skin Grid for starter, A reasonable amount of slides,
 212   Optionset with Rows and slidesPerRow = 1.
 213   Avoid variableWidth and adaptiveHeight. Use consistent dimensions.
 214   This is module feature, older than core Rows, and offers more flexibility.
 215   Available at slick_views, and configurable via Views UI.
 216
 217 If you want to attach extra 3rd libraries, e.g.: image reflection, image zoomer,
 218 more advanced 3d carousels, etc, simply put them into js array of the target
 219 skin. Be sure to add proper weight, if you are acting on existing slick events,
 220 normally < 0 (slick.load.min.js) is the one.
 221
 222 Use hook_slick_skins_info() and implement \Drupal\slick\SlickSkinInterface
 223 to register ones. Clear the cache once.
 224
 225 See slick.api.php for more info on skins.
 226 See \Drupal\slick\SlickSkinInterface.
 227
 228 Other skins are available at http://dgo.to/slick_extras
 229 Some extra skins are WIP which may not work as expected.
 230
 231
 232 GRID
 233 --------------------------------------------------------------------------------
 234 To create Slick grid or multiple rows carousel, there are 3 options:
 235
 236 1. One row grid managed by library:
 237    Visit admin/config/media/slick,
 238    Edit current optionset, and set
 239    slidesToShow > 1, and Rows and slidesperRow = 1
 240
 241 2. Multiple rows grid managed by library:
 242    Visit admin/config/media/slick,
 243    Edit current optionset, and set
 244    slidesToShow = 1, Rows > 1 and slidesPerRow > 1
 245
 246 3. Multiple rows grid managed by Module:
 247    Visit admin/structure/views/view/slick_x/edit/block_grid from slick_example,
 248    Be sure to install the Slick example sub-module first.
 249    Requires skin "Grid", and slidesToShow, Rows and slidesPerRow = 1.
 250
 251 The first 2 are supported by core library using pure JS approach.
 252 The last is the Module feature using pure CSS Foundation block-grid.
 253
 254 The key is:
 255 The total amount of Views results must be bigger than Visible slides, otherwise
 256 broken Grid, see skin Grid above for more details.
 257
 258
 259 HTML STRUCTURE
 260 --------------------------------------------------------------------------------
 261 Note, non-BEM classes are added by JS.
 262
 263 <div class="slick">
 264   <div class="slick__slider slick-initialized slick-slider">
 265     <div class="slick__slide"></div>
 266   </div>
 267   <nav class="slick__arrow"></nav>
 268 </div>
 269
 270 asNavFor should target slick-initialized class/ID attributes.
 271
 272
 273 BUG REPORTS OR SUPPORT REQUESTS
 274 --------------------------------------------------------------------------------
 275 A basic knowledge of Drupal site building is required. If you get stuck:
 276
 277   o consult the provided READMEs,
 278   o descriptions on each form item,
 279   o the relevant guidelines from the supported modules,
 280   o consider the project issue queues, your problem may be already addressed,
 281   o install slick_example.
 282
 283 If you do have bug reports, we love bugs, please:
 284   o provide steps to reproduce it,
 285   o provide detailed info, a screenshot of the output and Slick form, or words
 286     to identify it any better,
 287   o make sure that the bug is caused by the module.
 288
 289 For the Slick library bug, please report it to the actual library:
 290   https://github.com/kenwheeler/slick
 291
 292 You can create a fiddle to isolate the bug if reproduceable outside the module:
 293   http://jsfiddle.net/
 294
 295 For the support requests, a screenshot of the output and Slick form are helpful.
 296 Shortly, you should kindly help the maintainers with detailed info to help you.
 297 Thanks.
 298
 299
 300 TROUBLESHOOTING
 301 --------------------------------------------------------------------------------
 302 - When upgrading from Slick v1.3.6 to later version, try to resave options at:
 303   o admin/config/media/slick
 304   o admin/structure/types/manage/CONTENT_TYPE/display
 305   o admin/structure/views/view/VIEW_NAME
 306   only if trouble to see the new options, or when options don't apply properly.
 307   Most likely true when the library adds/changes options, or the module
 308   does something new. This is normal for any library even commercial ones, so
 309   bear with it.
 310
 311 - Always clear the cache, and re-generate JS (if aggregation is on) when
 312   updating the module to ensure things are picked up:
 313   o admin/config/development/performance
 314
 315 - If you are customizing template files, or theme functions, be sure to re-check
 316   against the latest.
 317
 318 - Be sure Slick release is similar, or later than Blazy.
 319
 320
 321 KNOWN ISSUES
 322 --------------------------------------------------------------------------------
 323 - Slick admin CSS may not be compatible with private or contrib admin
 324   themes. Only if trouble with admin display, please disable it at:
 325   admin/config/media/blazy
 326
 327 - The Slick lazyLoad is not supported with Responsive image. Slick only
 328   facilitates Responsive image to get in. The image formatting is taken over by
 329   Responsive image.
 330   Some other options such as Aspect ratio is currently not supported either.
 331
 332 - Photobox is best for:
 333   - infinite true + slidesToShow 1
 334   - infinite false + slidesToShow N
 335   If "infinite true + slidesToShow > 1" is a must, but you don't want dup
 336   thumbnails, simply override the JS to disable 'thumbs' option.
 337
 338 - The following is not module related, but worth a note:
 339   o lazyLoad ondemand has issue with dummy image excessive height.
 340     Added fixes to suppress it via option Aspect ratio (fluid | enforced).
 341     Or use Blazy lazyload for more advanced options.
 342   o Aspect ratio is not compatible with Responsive image or multi-serving
 343     images.
 344     However if you can stick to one Aspect ratio, choose 'enforced' instead.
 345     Otherwise disable Aspect ratio for multi-serving images.
 346   o If the total < slidesToShow, Slick behaves. Previously added a workaround to
 347     fix this, but later dropped and handed over to the core instead.
 348     Brought back the temp fix for 1.6+ as per 10/18/16:
 349     See https://github.com/kenwheeler/slick/issues/262
 350   o Fade option with slideToShow > 1 will screw up.
 351   o variableWidth ignores slidesToShow.
 352   o Too much centerPadding at small device affects slidesToShow.
 353   o Infinite option will create duplicates or clone slides which look more
 354     obvious if slidesToShow > 1. Simply disable it if not desired.
 355   o If thumbnail display is Infinite, the main one must be infinite too, else
 356     incorrect syncing.
 357   o adaptiveHeight is no good for vertical.
 358
 359
 360 CURRENT DEVELOPMENT STATUS
 361 --------------------------------------------------------------------------------
 362 A full release should be reasonable after proper feedbacks from the community,
 363 some code cleanup, and optimization where needed. Patches are very much welcome.
 364
 365 Alpha and Beta releases are for developers only. Be aware of possible breakage.
 366
 367 However if it is broken, unless an update is explicitly required, clearing cache
 368 should fix most issues during DEV phases. Prior to any update, always visit:
 369 /admin/config/development/performance
 370
 371 And hit "Clear all caches" button once the new Slick is in place. Regenerate CSS
 372 and JS as the latest fixes may contain changes to the assets.
 373 Have the latest or similar release Blazy to avoid trouble in the first place.
 374
 375
 376 ROADMAP
 377 --------------------------------------------------------------------------------
 378 - Bug fixes, code cleanup, optimization, and full release.
 379
 380
 381 HOW CAN YOU HELP?
 382 --------------------------------------------------------------------------------
 383 Please consider helping in the issue queue, provide improvement, or helping with
 384 documentation.
 385
 386 If you find this module helpful, please help back spread the love. Thanks.
 387
 388
 389 QUICK PERFORMANCE TIPS
 390 --------------------------------------------------------------------------------
 391 - Use lazyLoad "ondemand" / "anticipated" for tons of images, not "progressive".
 392   Unless within an ajaxified lightbox.
 393 - Choose lazyload "Blazy" for carousels below the fold to delay loading them.
 394 - Tick "Optimized" option on the top right of Slick optionset edit page.
 395 - Use image style with regular sizes containing effect "crop" in the name. This
 396   way all images will inherit dimensions calculated once.
 397 - Disable core library "slick-theme.css" as it contains font "slick" which
 398   may not be in use when using own icon font at:
 399   /admin/config/media/slick/ui
 400 - Use Blazy multi-serving images, Responsive image, or Picture, accordingly.
 401 - Uninstall Slick UI at production.
 402 - Enable Drupal cache, and CSS/ JS assets aggregation.
 403
 404
 405 AUTHOR/MAINTAINER/CREDITS
 406 --------------------------------------------------------------------------------
 407 Slick 8.x-1.x by gausarts, and other authors below.
 408 Slick 7.x-2.x by gausarts, inspired by Flexslider with CTools integration.
 409 Slick 7.x-1.x by arshadcn, the original author.
 410
 411 - https://www.drupal.org/node/2232779/committers
 412 - CHANGELOG.txt for helpful souls with their patches, suggestions and reports.
 413
 414
 415 READ MORE
 416 --------------------------------------------------------------------------------
 417 See the project page on drupal.org: http://drupal.org/project/slick.
 418
 419 More info relevant to each option is available at their form display by hovering
 420 over them, and click a dark question mark.
 421
 422 See the Slick docs at:
 423 - http://kenwheeler.github.io/slick/
 424 - https://github.com/kenwheeler/slick/