Skip to content

SlideshowFX developer documentation

Jump to bottom
Thierry Wasylczenko edited this page Jan 30, 2015 · 1 revision

SlideshowFX developer documentation

1. Introduction

SlideshowFX is an application allowing you to create HTML5 based presentation in a very common manner. Nowadays we all use PowerPoint, Keynote and their friends but with evolution of web technologies, new perspectives are now possible. Indeed there is a lot of HTML5/JavaScript based framework, like reveal.js or impress.js, that allow you to create beautiful presentations to keep your audience active. It brings you a lot of freedom like adding a YouTube video right inside your presentation, playing music, automatically syntax highlighting code example and more. But to do such presentations you have to know HTML, CSS and JavaScript programming languages.

SlideshowFX lets programming languages to developers and presentations' creation to end users. This means that you will be able to create your presentations without knowing HTML, even if it is recommended to have the basics.

But SlideshowFX isn’t just another simple presentation engine. It brings much more for you:

  • A chat is provided so your audience can send you questions using their smartphones and you will answer them whenever you want ;

  • A quizz creator so your audience can answer your quizz using their smartphones and you see results live ;

  • Present using your hands by changing slides with two fingers, have a "laser" pointer by using one finger. It’s cool isn’t it? All of this brought to you by LeapMotion.

  • Save your presentations on Dropbox or Google Drive ;

  • Insert code snippets that can be executed directly from the presentation and console’s output is displayed in the slide.

2. Developer guide

2.1. Tools & APIs

API, Tool Version Comments

Java / JavaFX

8

asciidoctorj

1.5.2

Apache Felix

4.4.1

commons-collections

3.2.1

commons-lang

2.4

freemarker

2.3.21

hamcrest-core

1.3

jackson-annotations

2.2.2

jackson-core

2.2.2

jackson-databind

2.2.2

JRuby Complete

1.7.18 

jsoup

1.8.1

LeapMotion SDK

2.2.2.24469

netty-all

4.0.21.Final

org.eclipse.mylyn.wikitext.core

2.2.0.N20140811-1615

Library used for textile support

org.eclipse.mylyn.wikitext.textile.core

2.2.0.N20140702-2138

Library used for textile support

twitter4j

4.0.2

txtmark

0.11

Library used for the markdown support

vertx-core

2.1.5

zxing-core

3.1.0

zxing-jse

3.1.0

ACE

1.1.

2.2. Project structure

SlideshowFX contains the following modules:

  • SlideshowFX-app which is the module for the desktop client of SlideshowFX ;

  • SlideshowFX-utils which defines utilities classes that may be used in other modules ;

  • SlideshowFX-engines which defines the engines that are used in SlideshowFX for working with templates and presentations ;

  • SlideshowFX-controls which defines the custom graphical controls that may be used in other modules ;

  • SlideshowFX-global-configuration which defines the classes allowing to access and interact the SlideshowFX configuration ;

  • SlideshowFX-osgi which defines the OSGi classes that are useful for other modules ;

  • SlideshowFX-markup which defines the base classes for creating an OSGi module for supporting a new markup syntax in SlideshowFX to define slides' content ;

  • SlideshowFX-asciidoctor which defines the implementation of SlideshowFX-markup to define slides' content in asciidoctor ;

  • SlideshowFX-html which defines the implementation of SlideshowFX-markup to define slides' content in HTML ;

  • SlideshowFX-markdown which defines the implementation of SlideshowFX-markup to define slides' content in markdown ;

  • SlideshowFX-textile which defines the implementation of SlideshowFX-markup to define slides' content in textile ;

  • SlideshowFX-content-extension which defines the base classes for creating an OSGi module for inserting specific content in slides (like images, …​) ;

  • SlideshowFX-alert-extension which defines the implementation of SlideshowFX-content-extension to insert beautiful alerts in slides ;

  • SlideshowFX-code-extension which defines the implementation of SlideshowFX-content-extension to insert code in slides ;

  • SlideshowFX-image-extension which defines the implementation of SlideshowFX-content-extension to insert images in slides ;

  • SlideshowFX-link-extension which defines the implementation of SlideshowFX-content-extension to insert HTML links in slides ;

  • SlideshowFX-quote-extension which defines the implementation of SlideshowFX-content-extension to insert quotes in slides ;

  • SlideshowFX-snippet-extension which defines the implementation of SlideshowFX-content-extension to insert executable code snippet in slides ;

  • SlideshowFX-hosting-connector which defines the base classes for creating an OSGi module for connecting to a file hosting service ;

  • SlideshowFX-dropbox-hosting-connector which defines the implementation of SlideshowFX-hosting-connector to connect to Dropbox ;

  • SlideshowFX-drive-hosting-connector which defines the implementation of SlideshowFX-hosting-connector to connect to Google Drive ;

  • SlideshowFX-snippet-executor which defines the base classes for creating an OSGi module for executing code snippet in a presentation ;

  • SlideshowFX-golo-executor which defines the base classes for creating an OSGi module for executing Golo code snippet in a presentation ;

  • SlideshowFX-java-executor which defines the base classes for creating an OSGi module for executing Java code snippet in a presentation.

2.3. Gradle

SlideshowFX uses gradle as build system. The version used is 2.2.1.
The following plugins are currently used in the Gradle script:

  • java

  • asciidoctor

2.3.1. Tasks

In order to build SlideshowFX, some gradle tasks have been created:

  • the jar task of the SlideshowFX-app project has been overridden in order to build the JavaFX native bundle ;

  • buildJavaFXBundle which depends on the JAR task has been created in the SlideshowFX-app project. This task creates the JavaFX bundle ;

  • installMarkupPlugins (in the root project) which copies the markup supported to the directory of plugins ;

  • installContentExtensionPlugins (in the root project) which copies the content extensions to the directory of plugins ;

  • installHostingConnectorPlugins (in the root project) which copies the hosting connectors to the directory of plugins ;

  • installSnippetExecutor (in the root project) which copies the snippet executors to the directory of plugins ;

  • installSlideshowFX (in the root project) which installs the markup, content extensions and hosting connectors in the directory of plugins and build the SlideshowFX native bundle.

2.4. Set up your environment

2.4.1. Environment variable

In order to build SlideshowFX, you will need to set JAVA_HOME to point to your JDK 8 installation and GRADLE_HOME to your gradle installation. Ensure both variables are present in the PATH environment variable.

2.4.2. Running SlideshowFX in your IDE

If you are contributing to SlideshowFX and developing some features, you probably use an IDE (IntelliJ IDEA, NetBeans, eclipse, …​).
Because SlideshowFX uses LeapMotion, you have to set up a JVM argument which is

-Djava.library.path=./lib/Leap/<platform>

Values for the platform are:

  • osx

  • windows_x86

  • windows_x64

  • linux_x86

  • linux_x64

If you want SlideshowFX manage and look where LeapMotion native libraries are located, instead of defining the -Djava.library.path JVM argument you can define the two following:

-Ddynamic.java.library.path=true -Dproject.stage=development

By doing so, SlideshowFX will automatically be looking for the folder ./lib/Leap/<platform>.

2.5. Templates

Each presentation done with SlideshowFX is based on a template.
A template is composed by three main parts:

  • A template configuration file which contains the configuration of the template. This file must be named template-config.json and is written using JSON ;

  • A template file which is the HTML page that will host all slides of the presentation ;

  • Slide’s template files which are the template for each kind of slide the user can add in his presentation.

All of this content is archived in a file with the extension .sfxt (which stands for SlideshowFX template)

A typical template archive structure is the following:

/
|- [F] template-config.json
|- [F] template.html
|- [D] resources
|- [D] slides
|------|- [D] template

Where:

  • [F] = file

  • [D] = directory

2.5.1. Template configuration file

The template configuration must be at the root of the archive and will contain all the configuration the template will need to load. An example is show below:

{
  "template" : {
    "name": "My first template",
    "file" : "template.html",
    "js-object" : "sfx",
    "resources-directory" : "resources",

    "slides" : {
      "configuration" : {
        "slides-container" : "slideshowfx-slides-div",
        "slide-id-prefix" : "slide-",
        "template-directory" : "slides/template",
        "presentation-directory" : "slides/presentation",
        "thumbnail-directory" : "slides/presentation/thumbnails"
      },
      "slides-definition" : [
        {
          "id" : 1,
          "name" : "Title",
          "file" : "title.html",
          "dynamic-ids" : [
            "${slideIdPrefix}${slideNumber}",
            "${slideNumber}-title",
            "${slideNumber}-subtitle",
            "${slideNumber}-author",
            "${slideNumber}-twitter",
          ]
        },
        {
          "id" : 2,
          "name" : "Title and content",
          "file" : "title_content.html",
          "dynamic-ids" : [
            "${slideIdPrefix}${slideNumber}",
            "${slideNumber}-title",
            "${slideNumber}-text"
          ]
        },
        {
          "id" : 3,
          "name" : "Empty",
          "file" : "empty.html",
          "dynamic-ids" : [
            "${slideIdPrefix}${slideNumber}",
            "${dslideNumber}-content"
          ],
          "dynamic-attributes" : [
            {
              "attribute" : "data-x",
              "template-expression" : "slideDataX",
              "prompt-message" : "Enter X position of the slide:"
            },
            {
              "attribute" : "data-y",
              "template-expression" : "slideDataY",
              "prompt-message" : "Enter Y position of the slide:"
            }
          ]
        }
      ]
    }
  }
}

The complete configuration is wrapped into a template JSON object. This object is described as below:

  • name : the name of the template

  • file : the HTML file that is the template, which will host the slides

  • js-object : is the name JavaScript object that will be used to callback to SlideshowFX

  • slides-container : is the ID of the HTML markup that will contain the slides

  • resources-directory : the folder that will contain the resources of the presentation, typically images file, sounds, etc

  • slides : define the configuration of slides inside the presentation, as well as their template

    • configuration : JSON object that will contain the configuration of the slides

      • slide-id-prefix : is a prefix that will be placed in the ID attribute of an HTML slide element, prefixing the slide number

      • template-directory : the directory that will contain the slide’s templates

      • presentation-directory : the directory that will contain the slides of the presentation, created by the user

      • thumbnail-directory : the directory that will contain the thumbnail of each slide created by the user

    • slides-definition : a JSON array that will contain the definition of each slide template as a JSON object with the following structure:

      • id : the ID of the slide

      • name : the name of the slide that will be displayed in SlideshowFX in the lst of available slide’s type

      • file : the template file of the slide

      • dynamic-ids : a JSON array composed of JSON string that lists all the HTML IDs that can be generated when a slide is created in the presentation. It is mainly used for copying a slide inside the application

      • dynamic-attributes : a JSON array composed of JSON object describing the attributes that can be dynamically created when creating a slide by prompting its value to the user. Each object is structured as follow:

        • attribute : the name of the attribute

        • template-expression : the name of the template token. It is the Velocity token without the dollar sign.

        • prompt-message : the message displayed to the user asking the value of the attribute.

2.5.2. Template file

The template file is the file that will host all slides, include all JavaScript libraries, CSS files and so on. In order to work, you have to:

  • insert the freemarker token ${sfxJavascriptResources} inside a script code block

  • define an ID for the HTML element that will host all slides

  • insert the following JavaScript function with the right implementation for changing slides using LeapMotion

function slideshowFXLeap(keyCode) {
  // Manage the LEFT and RIGHT key codes for changing slides
}

  • insert the JavaScript function with the right implementation returning the current slide

function slideshowFXGetCurrentSlide() {
  // Return the current slide
}

2.5.3. Slide’s template file

The template of a slide will define what HTML element a slide is. In some frameworks it will be a section markup, in others a div and so on. In order to create a template, you will have to respect some pre-requisites:

  • The slide markup must have its ID attribute set to ${slideIdPrefix}${slideNumber}

  • Each element that is editable by the user must have an ID attribute composed of the slide number and a discriminator. An example of the title of the slide:

    <h1 id="${slideNumber}-title"></h1>

  • Each element that is editable by the user must have the ondblclick attribute set to ${sfxCallback}

  • If dynamic attributes are needed, they can be defined like the following. Note that for this example, template-expression are slideDataX and slideDataY

    <section ${slideDataX} ${slideDataY}></section>

2.5.4. Valid template engine tokens

The following template engine tokens are available for SlideshowFX:

  • ${slideIdPrefix} indicates the prefix that will be placed before the slide number for each slide

  • ${slideNumber} indicates the slide number generated by SlideshowFX

  • ${sfxCallback} indicates the function that will call SlideshowFX from JavaScript

  • ${sfxJavascriptResources} indicates the JavaScript resources SlideshowFX will insert in the presentation, like the one for inserting content, calling a quiz etc

2.6. Presentations

Presentations made with SlideshowFX are an archive with the .sfx extension. The archive contains:

  • The whole template structure

  • The presentation.html file which is the whole presentation

  • The presentation-config.json which is the whole configuration of the presentation

2.6.1. Configuration file

The configuration of the presentation is wrapped into an JSON configuration file named presentation-config.json. Here is a configuration example:

{
  "presentation": {
    "custom-resources": [
        {
            "type": "<type>",
            "content": "<content encoded in Base64>"
        },
        {
           "type": "<type>",
           "content": "<content encoded in Base64>"
       }
    ],
    "slides": [
      {
        "template-id": 1,
        "id": "slide-1400836547234",
        "number": "1400836547234",
        "elements": [
          {
            "element-id": "1400836547234-author",
            "original-content-code": "HTML",
            "original-content": "<content encoded in Base64>",
            "html-content": "<content encoded in Base64>"
          },
          {
            "element-id": "1400836547234-twitter",
            "original-content-code": "HTML",
            "original-content": "<content encoded in Base64>",
            "html-content": "<content encoded in Base64>"
          },
          {
            "element-id": "1400836547234-title",
            "original-content-code": "HTML",
            "original-content": "<content encoded in Base64>",
            "html-content": "<content encoded in Base64>"
          },
          {
            "element-id": "1400836547234-subtitle",
            "original-content-code": "HTML",
            "original-content": "<content encoded in Base64>",
            "html-content": "<content encoded in Base64>"
          }
        ]
      },
      {
        "template-id": 2,
        "id": "slide-1400836587307",
        "number": "1400836587307",
        "elements": [
          {
            "element-id": "1400836587307-title",
            "original-content-code": "HTML",
            "original-content": "<content encoded in Base64>",
            "html-content": "<content encoded in Base64>"
          },
          {
            "element-id": "1400836587307-text",
            "original-content-code": "TEXTILE",
            "original-content": "<content encoded in Base64>",
            "html-content": "<content encoded in Base64>"
          }
        ]
      }
    ]
  }
}

The presentation JSON object is described below:

  • custom-resources : the JSON that will contain a JSON object for each custom resource of the presentation

    • type : the type of the resource. Possible values are JAVASCRIPT_FILE, CSS_FILE, SCRIPT and CSS

    • content : the content of the resource enconded in Base64

  • slides : the JSON array that will contain a JSON object for each slide of the presentation

    • template-id : the ID of the Slide that serves as template

    • id : the ID of the slide

    • number : the slide number

    • elements : the array containing a JSON object for each element defined in the slide

      • element-id : the ID of the slide element

      • original-content-code : the code of the markup syntax used

      • original-content : the orginal content of the element encoded in Base64. This syntax of the content must correspond to the content code

      • html-content : the original content converted in HTML encoded in Base64

Clone this wiki locally