%META:TOPICINFO{author="ProjectContributor" comment="" date="1655468868" format="1.1" version="1"}%
%META:TOPICPARENT{name="Plugins"}%
---+!! Slide Show Plugin

%SHORTDESCRIPTION%

%TOC%

---++ Introduction

There is already a _de facto_ standard for presentations, so why this plugin?
This plugin makes sense for organizations that already have lots of content in Foswiki:
It is easy to create a web based presentation that contains many links to related content.
The plugin does not try to compete with the bells and whistles of other presentation programs.
However, the markup of Foswiki and other plugins such as Foswiki:Extensions/ChartPlugin, Foswiki:Extensions/GaugePlugin, Foswiki:Extensions/SpreadSheetPlugin, Foswiki:Extensions/JHotDrawPlugin can be used to create appealing presentations.

Any topic with headings can be converted into a slideshow.
Each slide starts with a ="---++"= heading.
There are two modes to view a topic:

   * Normal topic view mode:
     Headings and text are shown in the usual Foswiki rendering,
     representing the outline of the slideshow.
     This mode is useful for printing handouts.

   * Presentation mode:
     Each heading with text is shown as a slide;
     the format is based on a slide template.
     Navigation buttons are added to go to the "First", "Previous", and "Next" slide.
     Slide navigation is quick because it is done with anchor jumps to the same page. 

You can start the presentation by clicking on the "Start presentation" button.

---++ Syntax rules

---+++ How to create a slideshow

   * Start with =%<nop>SLIDESHOWSTART%=
      * Use the optional =template= parameter to specify your own slide template topic,
        e.g. =%<nop>SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%=
   * Create the slides.
     Start each slide with a ="---++"= heading and add text
     such as paragraphs, bullets, tables and images.
      * *Hint:* Make sure to keep each slide short enough
        that you do not need to scroll to see all text of a slide during the presentation.
      * *Note:* You can use any heading levels you like,
        but use the same levels for all slides.
   * End your slideshow with =%<nop>SLIDESHOWEND%=

---+++ How to create your own slide template

To create your own template topic,
copy the "Default Slide Template" section below into your own slide template topic
and customize it to your needs.
It can be activated as the default template in the plugin's =TEMPLATE= setting,
or per slideshow with the =%<nop>SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%= setting.

   * Use a DIV or an HTML table that defines a slide.
     For example, create one row for the slide title, another one for the slide text.
   * These keywords can be used:
     | *Keyword* | *What it means* |
     | =%<nop>SLIDETITLE%= | The heading of the slide |
     | =%<nop>SLIDETEXT%= | The text of the slide |
     | =%<nop>SLIDECOMMENT%= | The comment of the slide (optional; appended to slide of missing) |
     | =%<nop>SLIDENUM%= | The current slide number |
     | =%<nop>SLIDEMAX%= | The last slide number |
  * And for navigation buttons:
     | =%<nop>SLIDENAV%= | The navigation buttons for "First", "Previous", "Next" slide |
     | =%<nop>SLIDENAVALL%= | The navigation buttons for "First", "Previous", "Next", "Last" slide |
     | =%<nop>SLIDENAVFIRST%= | The navigation button for "First slide" |
     | =%<nop>SLIDENAVPREV%= | The navigation button for "Previous slide" |
     | =%<nop>SLIDENAVNEXT%= | The navigation button for "Next slide" |
     | =%<nop>SLIDENAVLAST%= | The navigation button for "Last slide" |
   * Only text between =%<nop>STARTINCLUDE%= and =%<nop>STOPINCLUDE%= is used for the template.

---++ Example

This is a short example of a slideshow.
You should see a "Start presentation" button if this plugin is installed:

%SLIDESHOWSTART%
---++!! Introduction
This is slide one. 

%TOC%

---++ Hamlet meets his father's ghost

   * Hamlet learns that his father was killed by his brother Claudius and Queen Gertrude.
   * Claudius has quickly become king.

---++ This is rather upsetting

   * The ghost demands revenge.
   * Hamlet agrees.
   * His friends swear to keep what they have seen a secret.

---++ Meanwhile...

   * the King's advisor Polonius meets his daughter Ophelia. Hamlet has upset her.
   * Hamlet is acting mad
   
---+++ Comments

   * This text is not shown in the slide if HIDECOMMENTS is set to on.
   * It can have
   * many
   * more
   * bullets

---++ Please tune this template

Tune the look of this template by using CSS
(=slideshow.css= attached to this document).

%IF{"$'URLPARAM{skin}'='slideshow'" then="http://www.ibiblio.org/wm/paint/auth/durer/large-turf.jpg"}%

---+++ Comments

One-liner: this text is not shown in the slide if HIDECOMMENTS is set to "on".
%SLIDESHOWEND%

This text is not part of the slideshow.

---++ <nop>%TOPIC% preferences

You can override the default settings for the plugin by defining the following [[%SYSTEMWEB%.PreferenceSettings][preferences]].

| *Preference* | *Meaning* | *Default* |
| SLIDESHOWPLUGIN_TEMPLATE | Default template for slides: | SlideShowPlugin |
| SLIDESHOWPLUGIN_COMMENTS_LABEL | Label for Comments section | Comments |
| SLIDESHOWPLUGIN_HIDECOMMENTS | Hide text starting with a =---+++ %COMMENTS_LABEL%= heading | |

---++ Default slide template

You can create a new topic (!MyWeb.SlidesTemplate) somewhere
and add =STARTINCLUDE &lt;your template&gt; STOPINCLUDE= to it.
Afterwards, you can add =%SLIDESHOWSTART{template="MyWeb.SlidesTemplate"}%=
to show your presentations with this new template.
%BR%

---+++ Customizing the look of your presentation

Just customize the attached =slideshow.css= file to improve the view.

---+++ Current default template

The part between the rulers defines the default format of a slide:
<verbatim class="tml">
%STARTINCLUDE%
<div class="slideText">
<h1>%SLIDETITLE%</h1>
%SLIDETEXT%
%SLIDECOMMENT%
</div>
<div class="slideShowFooter">
<div class="foswikiRight slideShowControls">%SLIDENAVALL%</div>
<div class="foswikiLeft slideShowNum">Slide %SLIDENUM% of %SLIDEMAX%</div>
%CLEAR%
</div>
%STOPINCLUDE% 
</verbatim>

---++ Plugin installation instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -&gt; "Install, Update or Remove extensions" Tab.  Click the "Search for Extensions" button.  
Enter part of the extension name or description and press search.   Select the desired extension(s) and click install. If an extension is already installed, it will *not* show up in the
search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
<verbatim>
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
</verbatim>

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

   * Test above example if the installation was successful.

---++ Change History
%TABLE{columnwidths="7em" tablewidth="100%"}%
|  09 Mar 2021: (2.40) | Foswikitask:Item15021: multiple enhancements to SlideshowPlugin |
|  06 Sep 2016: (2.32) | Foswikitask:Item14125: fix encoding of url parms of "start presentation" button; Foswikitask:Item14170: improved button layout |
|  08 Apr 2016: (2.31) | Foswikitask:Item14022: Change all foswiki.org links to https. |
|  08 Sep 2015: (2.30) | Foswikitask:Item13685: add support for scrolling slides |
|  03 Mar 2015: (2.21) | Foswikitask:Item13281: improved printout |
|  10 Jan 2014: (2.20) | Foswikitask:Item13198: Fully qualify default template topic.<br />\
                         Foswikitask:Item12583: Revert to simple decimal version strings. |
|  28 Nov 2012: (2.1.6) | Foswikitask:Item11267: Convert to perl version strings. |
|  06 Apr 2012: (2.1.5) | Foswiki:Main.RichMorin documentation cleanup%BR%\
                          Foswikitask:Item11649: SlideShowPlugin un-necessarily breaks jquery widgets (TABPANES for eg are just blank). |
|  28 Aug 2011: (2.1.4) | URL encoding of query parameters did not include the parameter names |
|  11 Apr 2011: (2.1.3) | Version released with Foswiki 1.1.3. Only a minor change related to how the plugin is being upgraded |
|  24 Nov 2010: (2.1.2) | Changed the VarSLIDESHOWSTART so the example does not add to the TOC of the Macros listing |
|  12 Sep 2010: (2.1.1) | Restored default template to HTML table as the CSS one was unfinished and not at all showing what the plugin can do. Re-added the 20 empty lines after each slide so you do not see the next slide below. Changed from using cover to using skin so the left bar margin in pattern skin is not destroying the layout | 
|  31 Jul 2010: | Foswikitask:Item9415 - Documentation updates |
|  17 Jun 2009: | 2.0 Arthur Clemens: optimize to default template and CSS to make the plugin work with older templates. |
|  31 Mar 2009: | [[Foswiki:Main.GilmarSantosJr][GilmarSantosJr]]: [[Foswiki:Tasks/Item1401]] - Make it work in persistent environments |
|  18 Feb 2009: | Fixed =HIDECOMMENTS= to really hide the comment if value is =on= - otherwise the comment is shown in the comments section; added customizable =COMMENTS_LABEL= for all non-English speaking people. Updated default template and css; cleaned up code: now uses a =cover= instead of a =skin= so the style of the installed skin is used (unless redefined in the css file); use a custom template; when in slideshow mode, hide topic text; removed extraneously generated spaces; improved error messages; from the button "End presentation" link back to the start button. |
|  05 Feb 2009: | Updated graphics; made html and css validate. |
|  21 Jan 2009: | Exchanged the current default skin by something which is not written in totaly broken html and looking acceptable ( still needs an update, still table ugly design..). You can style by CSS now %BR% Tuned the docs a bit|
|  16 Dec 2008: | Foswiki version |
|  02 Aug 2008: | Fixed corruption of preview |
|  29 Sep 2007: | Added %SYSTEMWEB%.VarSLIDESHOWSTART and %SYSTEMWEB%.VarSLIDESHOWEND to have them listed in [[%SYSTEMWEB%.Macros]] |
|  12 Feb 2007: | fixed construction of view urls (TWiki:Main/MichaelDaum) |
|  19 Nov 2006: | 12011: Preserve URL parameters in slideshow (suggested by TWiki:Main/ThomasWeigert); changed logo in default template to T-logo; fixed warning errors introduced by 1.005 |
|  16 Mar 2005: | 1.005 Crawford Currie prepped for Dakar, and fixed multiple evaluation bug |
|  21 Nov 2004: | 1.004 Added support for =%<nop>SLIDECOMMENT%= template keyword (TWiki:Main/ArthurClemens); added benchmarks |
|  21 Mar 2004: | Internal change: Fixed unofficial function call |
|  14 Dec 2002: | Added =%<nop>SLIDENAVALL%= template keyword; added HIDECOMMENTS setting |
|  23 Nov 2002: | Added =%<nop>SLIDENAVLAST%= template keyword; using print Skin for presentation mode |
|  19 Nov 2002: | Added "Start presentation" and "End presentation" buttons; added =%<nop>SLIDENAVFIRST%=, =%<nop>SLIDENAVPREV%=, =%<nop>SLIDENAVNEXT%= template keywords |
|  17 Nov 2002: | Initial version |

%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="Foswiki:Main.EugenMayer, Foswiki:Main.ArthurClemens, Foswiki:Main.MichaelDaum"}%
%META:FIELD{name="Version" title="Version" value="2.40"}%
%META:FIELD{name="Release" title="Release" value="15 Mar 2026"}%
%META:FIELD{name="Description" title="Description" value="Create web based presentations based on topics with headings"}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/distro"}%
%META:FIELD{name="Copyright" title="Copyright" value="Copyright (C) 2006-2007 Peter Thoeny, peter@thoeny.org and Foswiki Contributors; 2008-2021 Foswiki Contributors"}%
%META:FIELD{name="License" title="License" value="GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]])"}%
%META:FIELD{name="Home" title="Home" value="https://foswiki.org/Extensions/SlideShowPlugin"}%
%META:FIELD{name="Support" title="Support" value="https://foswiki.org/Support/SlideShowPlugin"}%
