PRESENTA Lib

# Reference

# Root options

Each PRESENTA Lib document can be configured with some root options and properties defined in the config object:

Live Edit!

When you see that white code pane, you can live-edit.

Option Description Default Values
scenes The list of scene objects (required) Array
aspect Define the ratio between width and height 1.6 Number
adapt Override aspect inferring it from the container size. If the dimensions are not positive, a fallback size will be used. true Boolean
plugins An array of objects URL to install external plugins at run-time. This is not the primary and suggested way to install plugins. Additional info here. Array
noResize Disable the built-in resize feature false Boolean

The size of the presentation is based on the container size. If it hasn't a positive dimension, a fallback will be used, which is 360x200 pixels.

# Look&Feel

The Look&Feel can be defined by combining different properties. There's a great opportunity in finding unexpected results by combining many interconnected properties.

Let's play a little bit with some of them:

The following properties can be set to the whole presentation, to a specific scene and to a specific block as well.

Property Description Default Value
colors The colors scheme to use none String value from Presenta.colors
fonts The fonts set to use none String value from Presenta.fonts
colorVar The combination variation as defined in the colors scheme main String value from Presenta.colorvars

# Transitions

The transition property can be set both at presentation level and at scene level as well.

Property Description Default Value
transition The transition type. none String value from Presenta.transitions

# Layouts

The layout property can be set both at presentation level and at scene level as well.

Property Description Default Value
layout The scene layout. It has effect only with more than one block. cols String value from Presenta.layouts

Here an example of using the transition as well as the layout property to have text and image stacked:

{
  transition: 'fadeIn',
  scenes:[{
    layout: 'stack',
    blocks:[{
      type: 'image',
      url: 'https://path-to/image.jpg'
    },{
      type:'text',
      text:'<h1>Hello there!</h1>'
    }]
  }]
}

# Scenes

A scene contains one or more blocks. A scene can be extended with modules.

# Modules

Modules are scene extensions.

# Steps

Steps module handles the in-block fragments progressive show/hide behaviour, such as:

It's already active and it needs to be configured within the scene context.

There's a section with examples to learn all the details of this module.

# Jump

Jump module allows to go to specific scene by clicking any HTML element that contains the jump attribute with a valid value, such as:

<h1 jump="3">
  Go to scene 3
</h1>

Here an example:

More modules!

Modules can be created as external PRESENTA Lib plugin. You can find additional modules here.

# Blocks

A block is the minimal piece of content. It can sit together with other blocks in a scene.

As already mentioned, you can set Look&Feel properties at block level to override the inherit values.

Depending of the block type, further properties can be added.

Let's learn about the buint-in block types of PRESENTA Lib:

# Text

The text block is possibly the most obvious one allowing to display formatted text by using a subset of HTML tags.

The text automatically scales down if there is not enough available space. The additional scale option allows to fine-tune the behavior.

Option Description Default Value
type The block type (required) "text"
text The text in HTML you want to display (required) String
scale It allows to control the size of the text box within the available block space 1 Number
Property Description Default Value
textVar The text layout variations String ('title', 'text', 'section', 'mention')

# Image

The image block allows to display an image.

By default the image will cover the available block area.

Option Description Default Value
type The block type (required) "image"
url The path or URL to the image resource (required) URL

# Video

The video block allows to include a video file (encoded in a browser compatible(opens new window) format).

By default, the video won't start automatically. To control the playback (play/pause) you can use the SPACEBAR keyboard key. To rewind the video, use the r key.

To change the audio volume, use m to toggle the mute. Use + and - to increase/descrease the volume by 10% factor.

By default the video will cover the available block area.

Option Description Default Value
type The block type (required) "video"
url The path or URL to the video resource (required) URL
loop Loop the playback Boolean
autoplay Autoplay as soon as it's ready Boolean
poster The optional poster image URL

# Embed

The embed block allows to embed external web objects by means of an iframe tag.

The simplest way to embed a web resource is by using the url property.

If you have the embed code (the iframe code) you can use the code property:

Option Description Default Value
type The block type (required) "embed"
url The path or URL to the webpage resource (required) URL
code The complete iframe code, (required) if url is not set String
poster The optional poster image URL

# Svg

The svg block allows to inject and render an external SVG file.

The reason why of this, instead of using the svg as image (btw, you can do it with the image block), is to exploit its DOM with the built-in library Steps feature.

Option Description Default Value
type The block type (required) "svg"
url The path or URL to the SVG file (required) URL
code The raw svg code, (required) if url is not set String

# Group

The group block is a special one. It allows to stack two or more regular blocks together. By default, it includes a semi-transparent layer between the two blocks.

Option Description Default Value
type The block type (required) "group"
Property Description Default Value
layout The group layout. It has effect only with more than one sub-block. cols cols, rows, head, foot, stack

# External blocks

Blocks can be created as PRESENTA plugin. You can find additional blocks here.

#

# Controllers

PRESENTA Lib includes some general functions and behaviours that are commons in presentational documents. These functions are called Controllers because they act globally on the whole presentation, usually referring to the internal Router component that is responsible to control the document' navigation.

Each Controller needs to be activated (and optionally configured) in the main config object under the controllers field, such as:

{
  scenes:[...],
  controllers:{
    keyboard: true,
    arrows: true
  }
}

Here the list of built-in controlles alongside their default activation status:

# Keyboard

Allows to navigate back and forth using the keyboard arrows keys. Use ArrowRight and ArrowDown to go next, ArrowLeft and ArrowUp to go previous.

keyboard: true // default true

# Arrows

Allows to show two UI arrow elements to allows the back and forth navigation by clicking on them.

arrows: true // default true

# Black

Allows to show/hide a black screen by pressing the keyboard key b.

black: true // default true

To change the key, use the String char instead the Boolean.

# Fullscreen

Allows to run the presentation in fullscreen by pressing the keyboard key f. To change the key, use the String char instead the Boolean.

fullscreen: true // default true

This controller exposes a public toggle() function to allows external control.

# Hidden

It hides a specific scene or block if it has the hidden option set to true.

hidden: true // default true

An hidden scene:

scenes:[{
  hidden: true
  blocks:[...]
}]

An hidden block:

scenes:[{
  blocks:[{
		hidden: true
  	type: '...'
  }, {
    type: '...'
  }]
}]

# Limitswitch

It provides a visual feedback when the user tries to navigate over the presentation begin or end.

limitswitch: true // default true

# Cache

It fetches external resources in order to inject the content in their relative config object

cache: true // default true

# Autoplay

It turns the navigation in auto-play mode. Default delay is 4000ms. Set a Number instead a Boolean to override that delay.

autoplay: true // or 4000, default false

This Controller reads from each scene configuration the property autoplay in order to override the default delay time on a specific scene

scenes:[{
  autoplay: 8000 // to override the default/global setting
  blocks:[...]
}]

# Loop

It allows to loop the navigation, meaning, when the last scene is reached, the next navigation command will jump to the first scene.

loop: true // default false

# Focus

It allows to set the focus automatically instead waiting for the user click, allowing to use keyboard events without a first mouse interaction.

The detection is based on the viewport intersection, thus, the last instance that got intersected with the viewport gets the focus.

focus: true // default false

# Progressbar

It shows a tiny progress bar representing the progress of the current navigation.

progressbar: true // default false

# Shuffle

It randomize the order of the scenes on each instance session.

shuffle: true // default false

# Current

Set the start scene according to the passed number.

current: <Integer> // default false

# Pagenum

It shows the current page number and total pages based on the current navigation.

pagenum: true // default false

The default template '%s / %S' can be configured passing that String instead Bollean. %s is the current scene, %S is the total scenes.

pagenum: 'Page %s of total %S'

# Preload

It preloads images and videos from image and video blocks. It's very useful to avoid image loading progress when activating a scene with images. Of course, this leads to a loading waterfall which is not ideal if you put the presentation online.

As a rule of thumb: Use it when performing a speech. Keep it disabled in other situations.

preload: true // default false

# Sync

It keeps in sync multiple instance of the same presentation that are in the same origin. It works in all the modern browsers except on Safari which doesn't support the native BroadcastChannel.

It basically syncs interactive events (keyboard, mouse, touch, still experimental).

sync: true // default false

# RSync

It keeps the router events sync on multiple instance of the same presentation. Same limitations as the sync controller.

rsync: true // default false

# BaseURL

It infers the asset relative paths prepending a base-URL passed as value.

baseurl: 'http://localhost:8080' // default false

# Fonts

It loads at runtime external font resources setting the CSS variables used in the library. It requires an object with one or both the field heading and text. Both fields contain an object with url and name of the font-family you want to use.

fonts:{
  heading:{
    url: 'href="https://fonts.googleapis.com/css2?family=Roboto&display=swap',
    name: 'Roboto'
  }
}

# Brand

Allow to add a logo or heading passing an HTML fragment

brand: '<img src="myLogo.png" />' // default false

# Minitools

It adds a list of buttons in a mini toolbar.

minitools: true // default false

# External controllers

Controllers can be created as external PRESENTA Lib plugin. You can find additional controllers here.

# Instance

First off, a PRESENTA Lib instance is a Promise(opens new window) , therefore to get its meaningful object you have to write something like:

new Presenta('#app', config).then(preso => {
  console.log(preso)
})

Now you can access the following properties:

Property Description
config The config object digested by the library. The library doesn't clone the object before decorate with its internals.
router The internal Router instance to access its public methods
destroy() Clear all the internals to avoid memory leaks. Use it when you're rebuilding it many times (i.e. within an editor)

# Router

PRESENTA Lib contains an internal router to handle the navigation between scenes.

It can be controlled and extended using controllers.

Any PRESENTA Lib instance exposes its router instance:

new Presenta('#app', {...}).then(preso => {
  var router = preso.router
  router.next()
})

It contains the following public methods:

Method name Description
next() Go to the next scene
prev() Go to the previous scene
goto(index) Go to a specific index of a scene (zero-based)
currentIndex() Get the current index of a scene (zero-based)
currentStep() Get the current step of the current scene (zero-based)
totalScenes() The number of scenes
totalSteps() The number of steps in the current scene
controllers The object map of the active controllers. Some controller expose public methods and properties, this is the way to reach them out.
on(evt) Subscribe to router events
off(evt) Unsubscribe to router events

Here the list of events you can subscribe to:

Event name Description
indexChanged Every time the scene index changes
nextIndex When the Router moves foreward
prevIndex When the Router moves backward
begin When the Router reaches the presentation begin
end When the Router reaches the presentation end
init Only once, when the Router initializes
stepChanged When the Router increment the in-scene step index

A Router Event includes always the following information:

Property Description
name The event name
currentIndex Current index of the current scene
currentStep Current index of the step of the current scene
totalScenes The total number of scenes
totalSteps The number of steps of the current scene
isFirst Boolean, if the scene is the first one
isLast Boolean, if the scene is the last one

# Global object

The PRESENTA Lib object exposes some static properties and methods that can be useful, i.e. to know its version:

console.log(Presenta.version)
Property Description
version The version of the library
installed The array of installed plugins
Method Description
use() Method to install an external Plug-in

← Examples →