Overview

Models are the things that exist within the story. They physically exist as web content. They can be configured, styled and positioned. Their properties may be animated with scripts.

Model Description
Canvas The canvas is the drawing surface of the animation. It is mapped to a single div element or the body element of an HTML page. The HTML element might be any rectangular size. For example, a body tag stretches to fit the browser window. There is only one canvas.
Frame The frame is centered within and stretches to fit the canvas, minus any padding. However, unlike the canvas, the frame always maintains a configured aspect ratio. There is only one frame.
Flows Flows control page-to-page animation, such as page stacks, carousels, etc. Each flow contains one or more pages.
Pages Pages contain the item content. The timeline navigates from page to page. Pages are analogous to slides in old-school presentation software.
Items Items are the core visuals, such as text, images, and charts.

Property Sets

All model objects, except flows, have at least one set of properties. For example, a text item has properties to position and rotate the text. Each property may have its default values overridden in an init block. The values may also be changed later in a script.

edit & play
{
  item: {
    text: "COLOR",
    init: {color:"red", font:40, style:"bold"},
    actions:[
      {anim:2, color:"#567"},
      {anim:2, color:"rgba(127,15,127,0.8)"},
      {anim:2, color:"red"}
    ]
  }
}

Multiple

Some model objects have more than one set of properties. The main set of properties uses the init and scripts entries. The additional property sets use entries named to match the set.

For example, the simple bar chart has a main set of chart properties, such as position, which apply to the overall chart. It also has properties for the individual bars, which are initialized with barsInit and scripted with barScripts.

The text item actually has four sets of properties; one for the overall text, plus one for each of the sets of lines, words, and characters. Therefore, a text item might have init, scripts, linesInit, lineScripts, wordsInit, wordScripts, charsInit and charScripts entries.

Canvas & Frame Scripts

Because step scripts are only available for pages and items, the canvas and frame must be scripted on a page, using canvasScripts and frameScripts entries. The canvas and frame properties are animated relative to when a page reaches a step.


Canvas

The canvas is the outermost container. It is mapped onto a single div or body tag of an HTML page. Think of the canvas as the drawing surface. The div or body tag might be any size, and may even be resized later. ProStyle will stretch its content to fit, regardless of the aspect ratio of the canvas.

The canvas contains a single frame.

Setup

padding

The amount of space injected between the canvas and the frame. The value represents a percentage of the canvas width.

Valid values range from 0 to 50, although a value of 50 (50% on each side) would shrink the frame down to nothing.

  • default value: 0
{
  canvas:{
    setup:{
      padding:10
    }
  }
}

mediaUrl

A relative or absolute path to be prepended to all image paths. Use this to relocate image assets. For example, this could be used to place the images in an S3 bucket or CDN.

If a relative path is provided, it will be appended to a global root URL if one is defined at ProStyle.mediaRootUrl

  • default value: ''
{
  canvas:{
    setup:{
      mediaUrl:'https://s3.foo.com/images/'
    }
  }
}

Properties

Canvas properties may be scripted with a canvasScripts entry on a page.

animation

background

border

class

corners

crop

delay

font

Use the standard font property to set a default font for all text items in the story

opacity

shadow

textColor

Example

undocumented


Frame

Each story has only one frame. It is nested as a direct child of the canvas. The frame contains one or more flow objects.

Like the canvas, the frame will resize as needed. Unlike the canvas, though, the frame always maintains an aspect ratio. So regardless of how the canvas is stretched, the frame will always have the same relative proportions. The frame stays centered within the canvas.

Setup

aspectRatio

The ratio between the frame’s width and height. A value of 2 would define a frame that is twice as wide as it is tall. The aspect ratio provides a consistent rectangular shape regardless of how large the frame is scaled within the canvas.

Some common aspect ratios include:

Ratio Value Description
1 1 Box
4/3 1.33 NTSC/PAL TV
16/9 1.77 High Def TV
37/20 1.85 Wide Screen
47/20 2.35 Cinemascope
  • default value: 1.7777
{
  frame:{
    setup:{
      aspectRatio: 1.3333
    }
  }
}

padding

Defines the amount of space injected between the frame and the area used by flows when it in frame. The value represents a percentage of the canvas width or height depending upon the configured aspect ratio of the frame and the actual aspect ratio of the canvas. Valid values range from 0 to 50, although a value of 50 (50% on each side) would shrink the flows down to nothing.

  • default value: 0
{
  frame:{
    setup:{
      padding:10
    }
  }
}

Properties

Frame properties may be scripted with a frameScripts entry on a page.

animation

background

border

class

corners

crop

delay

opacity

shadow

Virtual Camera

The frame brings each of its child flows to the forefront, one after the other. Since all of the flows are laid out in 3D space, they all appear to move as the view changes. It’s natural to think of it like a camera flying around from one flow to the next.

Demonstration

As the canvas is resized, the frame resizes to fit. However, the frame always maintains its aspect ratio. All of the content within the frame will be resized to fit as well, relative to the frame’s aspect ratio.

frame

Flows

Flows provide complex orchestration and animation between pages. For that reason, they are sometimes referred to as page flows. Every story has at least one flow, but might have many.

Flows are positioned in 3D space and brought into the frame in order, one after the other. As the last page of a flow completes, the virtual camera moves to show the first page of the next flow.

##· Simple Flow

The Simple flow is simply a stack of pages directly on top of each other. When transitioning between pages, the current one is faded out and the next is faded in. While it is technically a flow, there is no motion page-to-page motion.

Simple flow is the default flow. It will be used if the flowType entry is not specified.

Setup

pageClass

The class name that all pages within the flow automatically use. An entry may be added to classes with this name and each page within the flow will be initialized with those properties.

  • default value: page
{
  classes: {
    page: {
      background: "white",
      border: true
    }
  }
}

pageAspectRatio

The width-to-height ratio of each page in the flow. It defaults to the frame’s apect ratio.

placement

A placement relative to the camera start point, where the first flow in the story would be by default. After the last page of a flow is completed, the virtual camera moves to the first page of the next flow.

Example

{
  flowType: "simple",
  placement: { position:[100,-100,0], rotation:[0,0,0], scale:100 },
  pageClass: "simplePage" 
  pages: [
    {},
    {}
  ]
}

##· Stack Flow

The Stack flow is a premium extension that comes with ProStyle Plus. It transitions its pages from one stack to another. Each page begins on the future stack, becomes the current page, and then moves to the past stack.

The placement of the stacks, and the offset of each page in each stack may be configured. It is quite flexible.

Setup

pageClass

The class name that all pages within the flow automatically use. An entry may be added to classes with this name and each page within the flow will be initialized with those properties.

  • default value: stackedPage
{
  classes: {
    stackedPage: {
      background: "white",
      border: true
    }
  }
}

pageAspectRatio

The width-to-height ratio of each page in the flow. It defaults to the frame’s apect ratio.

placement

A placement relative to the camera start point, where the first flow in the story would be by default. After the last page of a flow is completed, the virtual camera moves to the first page of the next flow.

stacks

future A placement that describes where the next page is displayed. This placement represents the top of the future stack. It contains an offset entry with another placement. The values in the offset placement are relative to the future placement.

The future placement defines where the next page is positioned and then the offset values are added for each page after that, making a stack.
current A placement that describes where the active page is displayed. Usually this placement is left unchanged so that the page is displayed in the middle of the frame, like any other page. However, the values may be adjusted to get interesting effects. See the second story in the gallery example.
past A placement that describes where the previous page is displayed. This placement represents the top of the past stack. It contains an offset entry with another placement. The values in the offset placement are relative to the past placement.

The past placement defines where the previous page is positioned and the offset values are added for each page after that, making a stack.

Example

edit & play
{
	classes:{
		stackedPage: { border:[5,"orange"] }
	},
	flow:{
		flowType:"stack",
		pageAspectRatio:1.333,
		placement:{ pos:[-100,-100,0]},
		stacks:{
			current:{ pos:[-5,-10,-10], rot:[-10,15,-10], scale:100, opacity:100 },
			future:{ pos:[-33,-45,-35], rot:[-10,15,-10], scale:100, opacity:80,
				offset:{ pos:[-10,-9,-4], rot:[0,-5,3], scale:100, opacity:80 }},
			past:{ pos:[70,70,100], rot:[0,10,-5], scale:100, opacity:0,
				offset:{ pos:[0,0,0], rot:[0,0,0], scale:100, opacity:0 }}
		},
		pages:[
			{ item:{ text:["A 'Page Stack' with", "custom configuration."]} },
			{ item:{ text:"2"} },
			{ item:{ text:"3"} },
			{ item:{ text:"4"} },
			{ item:{ text:"5"} },
			{ item:{ text:"6"} },
			{ item:{ text:"7"} },
		]
	}
}

Pages

Pages contain zero or more items, although a page without items is kind of boring. Items on a page may be animated. Also, pages themselves may be animated as part of a flow.

Properties

animation

background

border

class

color

Use the standard textColor property to default the color of all text items on the page

corners

crop

delay

font

Use the standard font property to set a default font for all text items on the page

opacity

shadow

textShadow

Use the standard textShadow property to set a default shadow for all text items on the page


Items

Items are the core visuals, such as text, images, charts, etc. Items are always placed on a page. They may be animated independently.

##· Text Item

The text item adds single-line or multiple-line text to a page or a layer. Properties may be applied at the text, line, word or character level. Many of the property values inherit. For instance, setting text color on the lines affects all the words and characters, unless words or characters explicitly override it.

The text, lines, words and characters make up a four level hierarchy. Each may be positioned in 3D space, relative to where it would normally be.

A line might be made up of a single word, or multiple sentences. If the textWidth property is used to induce word wrapping, a single line might wrap into multiple rendered lines. Regardless, it is still animated as a single line. This makes it possible to animate paragraphs, if desired.

Setup

text

A single line of text or an array of multiple lines.

setup: {text: "ProStyle"}
setup: {
  text: [
    "ProStyle",
    "makes it easy",
    "to animate stories"
  ]
}

Properties

Properties are initialized with an init entry and scripted with scripts. You may also use lineInit and lineScripts to set properties on lines, wordInit and wordScripts to set properties on words, and charInit and charScripts to set properties on characters. The plural form, linesInit, linesScripts, and so on, are available as aliases.

Lines, words and characters may have staggered animation.

Unless otherwise noted, each of the following properties may be used with text, lines, words and characters.

animation

anchor

Use the standard anchor property. This property is only available for text. It’s not available with lines, words, and characters.

background

border

bullets

The bullets property is used to adorn individual lines with rendered pictograms. This property is only available for lines.

class

corners

crop

Use the standard crop property. This property is only available for text. It’s not available with lines, words, and characters.

delay

font

Use the standard font property to set a default font for all text items on the page

opacity

padding

position

rotation

scale

shadow

skew

textAlign

The text align property defines whether the left and/or right edges of the individual text lines line up with each other. This property is only available for text. It’s not available with lines, words, and characters.

textColor

The text color property defines the color of the text

textShadow

The text shadow property applies a shadow to the text itself

textStyle

The text style property applies bold, italic, line or smallcaps styling to the text

textWidth

The text width property forces the text area to a width which induces word wrapping. This property is only available for text. It’s not available with lines, words, and characters.

transformOrigin

Use the standard transform origin property. This property is only available for text. It’s not available with lines, words, and characters.

Example

edit & play
{
  item: {
    text: "CHARS",
    init: {
      font: 40,
      style: "bold",
      pos: {z:10},
      color: "#33F"
    },
    charAction: {
      anim: [4,"less curve",10,0,false,1.25],
      rot: [180,540,-540]
    }
  }
}

##· Image Item

The image item adds a bitmap or vector image to a page or a layer. Any format supported by the browser may be used, including png, jpeg, gif and svg.

Setup

src

An image URL. Relative paths will be appended to the global ProStyle.mediaRootUrl and the canvas mediaUrl if they are defined. Data URIs may be used for embedded images.

  • alias: img
  • alias: url
{
	src: "logo.png"
}
{
	src: "url(logo.png)"
}

width

The horizontal size of the image as a percentage of the width of the container. The container may be a page or a layer. If omitted, the width will be calculated using the height and the image’s natural aspect ratio.

{
	width: 75
}

If both width and height are not provided, the width will be 50 percent and the height will be calculated based on the image’s natural aspect ratio.

height

The vertical size of the image as a percentage of the height of the container. The container may be a page or a layer. If omitted, the height will be calculated using the provided width and the image’s natural aspect ratio.

{ 
	height: 75
}

Properties

animation

anchor

class

corners

delay

opacity

position

rotation

scale

shadow

skew

transformOrigin

Example

edit & play
{
  frame: { aspectRatio: 1 },
  item: {
    itemType: "image",
    src: "html5.png",
    height: 70, width: 70,
    init: { origin:[0,50], pos:[0,10] },
    scripts: [
      { actions: [
          { anim:0.5, pos:[0,13], scale:140 },
          { anim:0.5, pos:[0,10] }
        ]
      },
      { action: {
          delay:0.5,
          anim:[3,"more elastic"],
          scale:{x:100}}
      },
      { action: {
          delay:0.5,
          anim:[3,"extra elastic"],
          scale:{y:100}}
      }
    ]
  }
}

##· Layer Item

The layer is a container for zero or more child items. The child items are placed relative to the center of the layer, regardless of where the layer is placed within its parent. Layers make it simple to manipulate many items as a group.

Layers may be nested in layers to any reasonable depth.

Setup

items

Zero or more child items. If there is only one item then item may be used instead as a form of shortcutting.

setup: {
  itemType: "layer",
  items: [
    { 
      text: "text one",
      init: { pos: [0,-17] }
    },
    {
      text: "text two",
      init: { pos: [0,17] }
    }
  ]
}

Properties

animation

anchor

background

border

class

corners

crop

delay

moveTo

The moveTo property is undocumented

opacity

position

rotation

scale

shadow

size

The size property defines the horizontal and vertical extents of the layer

skew

transformOrigin


##· Bar Chart

The Bar Chart is a premium extension that comes with ProStyle Plus. It translates data into vertical bars. For horizontal bars, rotate the chart with the rotation property.

The chart supports both single value data and two-value range data. See the Data section below.

Multiple series may be added by using one chart per, all stacked directly on each other, using congruent range data. See the example.

Setup

bars

The number of bars the chart will display. If the data property has fewer data, zeros will be appended. Extra data will be ignored.

{
	bars: 10
}

domain

The expected range of data as an array of two numbers. The bottom number represents no bar and the top number represents a full-height bar. Data values above the domain have bars rendered proportionately higher, beyond the chart’s bounds. Values below the domain are rendered down, below the chart.

If the value provided is a single number, it will be used as the top number and the bottom number will be set to 0.

{
	domain: 100
}
{
	domain: [-10,10]
}

width

The width of the chart as a percentage of the page’s width.

default: 50

{
	width: 40
}

height

The height of the chart as a percentage of the page’s height.

default: 50

{
	height: 40
}

margin

The spacing between any two bars as a percentage of the page’s width.

default: 1

{
	margin: 1.5
}

Chart Properties

These properties may be initialized with an init entry and scripted with scripts, script, actions or action.

animation

class

crop

delay

opacity

position

rotation

scale

skew

Bar Properties

These properties may be initialized with a barsInit entry and scripted with barScripts, barScript, barActions or barAction.

animation

class

data

delay

fill

Use the fill property. The default value is "rgba(0,0,0,0.5)"

opacity

skew

Data

Use a single array of numbers to have bars that range from a bottom value of 0 to each array entry as the top value. Alternatively, use an array of arrays where each nested array provides two numbers representing the bottom and top numbers in turn. Use nested arrays to define bars with range data. See the third story in the example for a demonstration of using range data with multiple series.

Example

edit & play
{
  item: {
    itemType: "barChart",
    setup: {bars:5, domain:[30,50]},
    barAction: { 
      anim: 5,
      data: [[45,34],[42,33],[36,32],[33,27],[37,31]]
    }
  }
}