Commit 28fdf111 authored by NickWilde's avatar NickWilde

Issue #2937494: Improve Documentation

parent b4678ef8
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Views Slideshow</title>
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1 id="views-slideshow">Views Slideshow</h1>
<h2 id="introduction">INTRODUCTION</h2>
<p>Views Slideshow can create slideshows out any content on your Drupal site - whether that is images, images on content or full rendered entities. The <code>views_slideshow</code> module provides a base/plugin system/api for building full featured slideshows within the Views UI. This project also includes a module implementing that base; <code>views_slideshow_cycle</code>. For most users, you’ll just want to enable both of them and install pre-reqs. For advanced users you can create your own implementation - and there are other implementations for Drupal 7 available (see below).</p>
<p>Built in and most/all of the implementations are powered by jQuery, and are highly customizable: you may choose slideshow settings for each View display you create.</p>
<h3 id="potential-uses">Potential Uses</h3>
<ul>
<li>News item slideshow (such as the title, image and teaser of the last 5 news articles submitted)</li>
<li>The Last X number of X submitted (images, videos, blog entries, forum posts, comments, testimonials, etc.).</li>
<li>Rotate any image, based on any filters you can apply in views.</li>
<li>Hottest new products for any ecommerce drupal site.</li>
<li>Rotate contact links, share links, etc.</li>
<li>You can even rotate entire nodes, categories, image galleries, etc.</li>
<li>It’s also a great space saver. Places where you had multiple images or items such as RSS feeds or category listings can now be presented in a slideshow.</li>
</ul>
<h2 id="requirements">REQUIREMENTS</h2>
<ul>
<li>Views Slideshow 8.x-4.x requires Drupal 8 &amp; the core Views module enabled.</li>
<li>There is no upgrade path from Views Slideshow for Drupal 7.</li>
<li>Views Slideshow Cycle (Which most users should use) requires some JavaScript libraries:
<ul>
<li><a href="https://github.com/malsup/cycle">jQuery Cycle 3.x</a></li>
<li><a href="https://github.com/douglascrockford/JSON-js">JSON2</a></li>
<li><a href="https://github.com/briancherne/jquery-hoverIntent">jQuery HoverIntent</a></li>
<li><a href="https://github.com/tobia/Pause">jQuery Pause</a></li>
</ul></li>
</ul>
<h2 id="installation">INSTALLATION</h2>
<p>Install as you would normally install a contributed Drupal module. See the <a href="https://drupal.org/documentation/install/modules-themes/modules-8">Drupal 8 Instructions</a> if required in the Drupal documentation for further information. Note there are two modules included in this project; Views Slideshow &amp; Views Slideshow Cycle. In most cases you will need/want to enable both of them.</p>
<p>If you are using the Views Slideshow Cycle sub-module, you will also need to install some JavaScript libraries. The required libraries are:</p>
<ul>
<li><a href="https://github.com/malsup/cycle">jQuery Cycle 3.x</a> in <code>/libraries/jquery.cycle</code></li>
<li><a href="https://github.com/douglascrockford/JSON-js">JSON2</a> in <code>/libraries/json2</code></li>
<li><a href="https://github.com/briancherne/jquery-hoverIntent">jQuery HoverIntent</a> in <code>/libraries/jquery.hoverIntent</code></li>
<li><a href="https://github.com/tobia/Pause">jQuery Pause</a> in <code>/libraries/jquery.pause</code></li>
</ul>
<p>It is recommended to use <a href="https://drush.org">Drush</a> to automatically install the requirements to the right spot. To install all of the libraries to the right places, run <code>drush dl-cycle-lib</code>.</p>
<p>If you don’t have Drush available, or would prefer to install manually, you can do so. An example of code you could run in your Drupal root dir to download to the right place:</p>
<pre><code> mkdir -p libraries/jquery.cycle &amp;&amp; cd $_ &amp;&amp; wget https://malsup.github.io/jquery.cycle.all.js \
&amp;&amp; mkdir -p ../../libraries/jquery.hoverIntent &amp;&amp; cd $_ &amp;&amp; wget https://raw.githubusercontent.com/briancherne/jquery-hoverIntent/master/jquery.hoverIntent.js \
&amp;&amp; mkdir -p ../../libraries/json2 &amp;&amp; cd $_ &amp;&amp; wget https://raw.githubusercontent.com/douglascrockford/JSON-js/master/json2.js \
&amp;&amp; mkdir -p ../../libraries/jquery.pause &amp;&amp; cd $_ &amp;&amp; wget https://raw.githubusercontent.com/tobia/Pause/master/jquery.pause.js</code></pre>
<h2 id="configuration">CONFIGURATION</h2>
<p>Configuration is on a per view/display basis.</p>
<p>Most standard views settings will work fine in conjunction with Views Slideshow. However, grouping may or may not work. Under most use cases the pager should be set to either <code>Display a specified number of items</code> or <code>Display all</code>.</p>
<p>To get started configuring your slideshow, set <code>Slideshow</code> as the display format and configure the slideshow as desired under Format Settings. Next select the <em>Skin</em> - usually <code>Default</code> (only one provided with the module). Then select the <em>Slideshow Type</em>; for most users, this will just be <code>cycle</code> with the <code>views_slideshow_cycle</code> module.</p>
<p>Below that, there is a lot of different options which should have better documentation.</p>
<h3 id="see-also">See also:</h3>
<ul>
<li><a href="https://www.ostraining.com/blog/drupal/drupal-8-slideshows">OS Training tutorial on Views Slideshow</a></li>
</ul>
<h2 id="contributors">CONTRIBUTORS</h2>
<p>Current maintainers:</p>
<ul>
<li><a href="https://www.drupal.org/u/nickwilde">Nick Wilde</a></li>
</ul>
<p>Past maintainers:</p>
<ul>
<li><p><a href="https://www.drupal.org/u/vbouchet">vbouchet</a> Initial 8.x port</p></li>
<li><p><a href="https://www.drupal.org/u/redndahead">Adam Moore</a></p></li>
<li><p><a href="https://www.drupal.org/u/aaron">aaron</a></p></li>
<li><p><a href="https://www.drupal.org/u/xiukun.zhou">xiukun.zhou</a></p></li>
<li><p><a href="https://www.drupal.org/u/wangqizhong">wangqizhong</a></p></li>
</ul>
<p>Also, thanks to the many contributors via the issue queues.</p>
</body>
</html>
# Views Slideshow
## INTRODUCTION
Views Slideshow can create slideshows out any content on your Drupal site -
whether that is images, images on content or full rendered entities. The
`views_slideshow` module provides a base/plugin system/api for building full
featured slideshows within the Views UI. This project also includes a module
implementing that base; `views_slideshow_cycle`. For most users, you'll just
want to enable both of them and install pre-reqs. For advanced users you can
create your own implementation - and there are other implementations for Drupal
7 available (see below).
Built in and most/all of the implementations are powered by jQuery, and are
highly customizable: you may choose slideshow settings for each View display
you create.
### Potential Uses
* News item slideshow (such as the title, image and teaser of the last 5 news
articles submitted)
* The Last X number of X submitted (images, videos, blog entries, forum posts,
comments, testimonials, etc.).
* Rotate any image, based on any filters you can apply in views.
* Hottest new products for any ecommerce drupal site.
* Rotate contact links, share links, etc.
* You can even rotate entire nodes, categories, image galleries, etc.
* It's also a great space saver. Places where you had multiple images or items
such as RSS feeds or category listings can now be presented in a slideshow.
## REQUIREMENTS
* Views Slideshow 8.x-4.x requires Drupal 8 & the core Views module enabled.
* There is no upgrade path from Views Slideshow for Drupal 7.
* Views Slideshow Cycle (Which most users should use) requires some JavaScript
libraries:
* [jQuery Cycle 3.x](https://github.com/malsup/cycle)
* [JSON2](https://github.com/douglascrockford/JSON-js)
* [jQuery HoverIntent](https://github.com/briancherne/jquery-hoverIntent)
* [jQuery Pause](https://github.com/tobia/Pause)
## INSTALLATION
Install as you would normally install a contributed Drupal module. See the
[Drupal 8 Instructions](https://drupal.org/documentation/install/modules-themes/modules-8)
if required in the Drupal documentation for further information. Note there are
two modules included in this project; Views Slideshow & Views Slideshow Cycle.
In most cases you will need/want to enable both of them.
If you are using the Views Slideshow Cycle sub-module, you will also need to
install some JavaScript libraries. The required libraries are:
* [jQuery Cycle 3.x](https://github.com/malsup/cycle) in
`/libraries/jquery.cycle`
* [JSON2](https://github.com/douglascrockford/JSON-js) in `/libraries/json2`
* [jQuery HoverIntent](https://github.com/briancherne/jquery-hoverIntent)
in `/libraries/jquery.hoverIntent`
* [jQuery Pause](https://github.com/tobia/Pause) in `/libraries/jquery.pause`
It is recommended to use [Drush](https://drush.org) to automatically install
the requirements to the right spot. To install all of the libraries to the
right places, run `drush dl-cycle-lib`.
If you don't have Drush available, or would prefer to install manually, you can
do so. An example of code you could run in your Drupal root dir to download to
the right place:
```
mkdir -p libraries/jquery.cycle && cd $_ && wget https://malsup.github.io/jquery.cycle.all.js \
&& mkdir -p ../../libraries/jquery.hoverIntent && cd $_ && wget https://raw.githubusercontent.com/briancherne/jquery-hoverIntent/master/jquery.hoverIntent.js \
&& mkdir -p ../../libraries/json2 && cd $_ && wget https://raw.githubusercontent.com/douglascrockford/JSON-js/master/json2.js \
&& mkdir -p ../../libraries/jquery.pause && cd $_ && wget https://raw.githubusercontent.com/tobia/Pause/master/jquery.pause.js
```
## CONFIGURATION
Configuration is on a per view/display basis.
Most standard views settings will work fine in conjunction with Views Slideshow.
However, grouping may or may not work. Under most use cases the pager should be
set to either `Display a specified number of items` or `Display all`.
To get started configuring your slideshow, set `Slideshow` as the display
format and configure the slideshow as desired under Format Settings. Next
select the *Skin* - usually `Default` (only one provided with the module).
Then select the *Slideshow Type*; for most users, this will just be `cycle`
with the `views_slideshow_cycle` module.
Below that, there is a lot of different options which should have better
documentation.
### See also:
* [OS Training tutorial on Views Slideshow](https://www.ostraining.com/blog/drupal/drupal-8-slideshows)
## CONTRIBUTORS
Current maintainers:
* [Nick Wilde](https://www.drupal.org/u/nickwilde)
Past maintainers:
* [vbouchet](https://www.drupal.org/u/vbouchet) Initial 8.x port
* [Adam Moore](https://www.drupal.org/u/redndahead)
* [aaron](https://www.drupal.org/u/aaron)
* [xiukun.zhou](https://www.drupal.org/u/xiukun.zhou)
* [wangqizhong](https://www.drupal.org/u/wangqizhong)
Also, thanks to the many contributors via the issue queues.
INTRODUCTION
------------
* Views Slideshow can be used to create a slideshow of any content (not just
images) that can appear in a View. Powered by jQuery, it is heavily
customizable: you may choose slideshow settings for each View you create.
REQUIREMENTS
------------
* Views Slideshow 8.x-4.x requires Drupal 8 & the core views module enabled.
* There is no upgrade path from views slideshow for Drupal 7.
INSTALLATION
------------
* Install as you would normally install a contributed Drupal module. See the
<a href='http://drupal.org/documentation/install/modules-themes/modules-8'>
Drupal 8 instructions</a> if required in the Drupal documentation for further
information. Note there are two modules included in this project; "Views
Slideshow" & "Views Slideshow Cycle". In most cases you will need/want to
enable both of them.
* You will also need to download some JavaScript libraries. You can do this
semi-automatically via drush using `drush dl-cycle-lib` or if preferred,
manually from the sources.
* Required libraries
* https://malsup.github.io/jquery.cycle.all.js
* https://raw.githubusercontent.com/briancherne/jquery-hoverIntent/master/jquery.hoverIntent.js
* https://raw.githubusercontent.com/douglascrockford/JSON-js/master/json2.js
* an example of code you could run in your Drupal root directory to download
to the right place:
```
mkdir -p libraries/jquery.cycle && cd $_ && wget https://malsup.github.io/jquery.cycle.all.js \
&& mkdir -p ../../libraries/jquery.hoverIntent && cd $_ && wget https://raw.githubusercontent.com/briancherne/jquery-hoverIntent/master/jquery.hoverIntent.js \
&& mkdir -p ../../libraries/json2 && cd $_ && wget https://raw.githubusercontent.com/douglascrockford/JSON-js/master/json2.js
```
CONFIGURATION
-------------
* Configuration is on a per view/display basis. Select 'Slideshow' as the
display format and then configure settings as desired under Format
Settings.
* See also:
https://www.ostraining.com/blog/drupal/drupal-8-slideshows
MAINTAINERS
-----------
Current maintainers:
* vbouchet (https://www.drupal.org/u/vbouchet) (Initial port & primary 8.x-4.x maintainer)
* NickWilde (https://www.drupal.org/u/nickwilde) (Secondary 8.x-4.x maintainer)
* aaron (https://www.drupal.org/u/aaron)
* xiukun.zhou (https://www.drupal.org/u/xiukun.zhou)
* wangqizhong (https://www.drupal.org/u/wangqizhong)
......@@ -83,11 +83,11 @@ class Cycle extends ViewsSlideshowTypeBase {
$cycle = \Drupal::service('library.discovery')->getLibraryByName('views_slideshow_cycle', 'jquery_cycle');
if (!isset($cycle['js'][0]['data']) || !file_exists($cycle['js'][0]['data'])) {
$form['views_slideshow_cycle']['no_cycle_js'] = [
'#markup' => '<div style="color: red">' . $this->t('You need to install the jQuery cycle plugin. Create a directory in libraries (which should be in your Drupal root folder, if not create the same) called jquery.cycle, and then copy jquery.cycle.all.js into it. You can find the plugin at @url.',
'#markup' => '<div style="color: red">' . $this->t('You need to install the @url plugin. If you have installed it check file paths. See the readme for more details.',
[
'@url' => Link::fromTextAndUrl('http://malsup.com/jquery/cycle', Url::FromUri('http://malsup.com/jquery/cycle'), [
'@url' => Link::fromTextAndUrl('jQuery Cycle', Url::FromUri('http://malsup.com/jquery/cycle', [
'attributes' => ['target' => '_blank'],
])->toString(),
]))->toString(),
]) . '</div>',
];
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment