Project file

Related links:

You can provide additional detail about your content to the LivePreso platform. This information lives in the project.yaml file in the root of your content project. Project files provide metadata for the files in a pack, which is then converted to a manifest.json file by the CDK before being packaged up with your deck content and uploaded to the server.

Basic example:

version: 2
name: Demo
src: ./src
dist: ./dist
key: demo
maintainer: your.email@example.org
servers:
  - title: Production
    api: 'https://server.livepreso.com'
  - title: Staging
    api: 'https://staging-server.livepreso.com'
dimensions:
  width: 1920
  height: 1080
common:
  js:
    - js/deck.js
  css:
    - css/core.css
hooks: js/hooks/hooks.js
feeds: {}
fixtures:
	feeds: feeds.json
	context: context.json
screenshotpreferences:
  backend: chrome
  vector: true
sections:
  - key: were_innovative
    title: "We're innovative"
    slides:
      - { key: introduction, title: "Introduction" }
      - { key: super_stats, title: "Super stats" }
      - { key: fancy_infographic, title: "Fancy infographic" }
  - key: product_suite
    title: "Product suite"
  - key: thank_you
    title: "Thank you"

Version

Your project.yaml should contain a version number. This ensures your older project files don't break when we make any format changes in the future.

version: 1

Name

Currently only used in the CDK, adding a name to your deck's project.yaml will make browsing through existing deck links easier, and keep you informed as to what deck you are currently previewing and working on.

name: Demo

Source and distribution

Source and target distribution directories. THe distribution directory is packaged up with the manifest.json and uploaded to a server to create a deck version.

src: ./src
dist: ./dist

Deck key

References the key given to a deck on the server, determines which deck your content will be uploaded to.

key: starting-point-deck

Maintainer

The inclusion of a maintainer email address in the project.yaml registers the email to receive processing notifications from the server for such events as:

deck version upload success
any screenshot job failure

maintainer: your.email@example.org

Servers

Used to determine which servers the deck can be uploaded to.

The example below shows the staging and production servers for a deck.

servers:
  - title: Production
    api: "https://server.salespreso.com"
  - title: Staging
    api: "https://staging-server.salespreso.com"

Dimensions

Determines the dimensions of the deck:

16:9 - 1920px wide x 1080px high (recommended)
4:3 - 1024px wide x 768px high

dimensions:
  width: 1920
  height: 1080

info

If omitted, the 4:3 dimensions will be applied.

Common

Refers to the location of any javascript and css files that you want made available to the entire deck.

For example, the following compiled structure:

.
├── css
│   ├── core.css
│   └── img
│       └── navigation-btns.png
└── js
    └── deck.js

would be referenced as such in the project.yaml:

common:
  js:
    - js/deck.js
  css:
    - css/core.css

info

The order in which you list your common assets reflects their load order. This is particularly important when referencing common JS files.

Hooks

Hooks allows you to integrate dynamic content from the deck into the application. Use the hooks object in the project.yaml to define where in your deck your hooks.js file is located.

hooks: js/hooks.js

Using hooks allows you to perform such features as:

Add dynamic inputs to an appointment's creation process
Save default values to the context for later use
Turn slides on/off based on context information and/or dynamic inputs
Reorder slides based on context information and/or dynamic inputs
Dynamically generate subslides (aka. adjunct subslides)

For more information about the types of hooks available and how to use them, visit the application hooks section.

Data feeds

Data feeds define live sources of data which Slides may source information from. Feeds only need a source defined:

feeds:
	product-prices:
		source: "https://catalog.customer.com/prices.json"

This feed could now be retrieved from within a Slide like:

Bridge.Feed.get("product-prices");

The working with API data guide has more detailed information about retrieving information from feeds. For now, we'll keep talking about how to define feeds in your project file.

Templated Sources

Templating a source allows you to use presentation-specific information in a feed URL. This can be handy to trim down the amount of information a feed returns. Sometimes a data source may also require specific information to return any useful data. Imagine, for example, sourcing CRM data for a specific customer when that CRM manages thousands of customers.

To template a source, you only need to use special tokens in your source URL. The tokens are per the Django template language. Our CRM example above may result in a source which looks like:

customer-data:
  source: "https://crm.example.org/customers/{{ customer.profile.crm_id }}/"

Now assuming a user creates a presentation for a Customer with a crm_id of 'oscilloscope', our feed would be fetched from https://crm.example.org/customers/oscilliscope/.

Some of the values which are available to use inside the URL depend on the LivePreso integration you're working on. However, many will always be available. These include the current user's information such as email address and name, and the customer details for which the current presentation has been created.

More advanced features of the templating language can be used. Imagine a custom integration where selecting a list of suburbs is part of the presentation creation screen, and you need to fetch details for those suburbs. You can use the join template filter to turn an array of suburbs into a comma-separated list:

source: "https://example.org/suburb_data/{{ suburbs|join:',' }}/"

Resulting in a URL like https://example.org/suburb_data/west_hattington,east_hattington,upper_downton/.

It's also possible to use conditional logic and looping structures inside source URLs, though we recommend against it for sanity reasons.

Again, the available values will depend on the integration you are working on. The folks working on the data integration should be able to specify a templated URL for you to use.

Fixtures

Defines any fixtures you want the deck to use.

fixtures:
  feeds: feeds.json
  context: context.json

Screenshots

When uploading your deck to LivePreso, each slide and subslide is captured by a screenshot server for use in thumbnails. It is also run when sending PDFs. This is done using Chrome.

screenshotpreferences:
  backend: chrome
  vector: true

See the project file screenshotpreferences reference for more information on changing the screenshot backend.

caution

phantomjs was originally available as a backend option, but has since been removed. Any presos created from old deck versions that would have used phantomjs will now be screenshotted using Chrome.

Sections, slides & subslides

In the LivePreso platform, content comes in one of three flavours. In descending order of heirarchy, these are Sections, Slides, and Subslides.

Keys

To provide metadata for sections, slides & subslides, you first need a way of referring to them. All content has a key, which is constructed using simple rules. You'll use the project file to link these keys to metadata.

Sections and Slides take their keys from the directories that contain them. Subslides cannot, since they are DOM elements rather than files. Their key comes from their DOM ID. By convention, they're simply numbered: subslide-1, subslide-2, etc.

The On-Disk Structure directory structure above is used as an example, and for illustrative purposes we assume that the "Fancy Infographic" Slide has two subslides in its index.html:

<div class="subslide" id="subslide-1"><!--- ... ---></div>
<div class="subslide" id="subslide-2"><!--- ... ---></div>

Object	File	Key
Section	sections/were_innovative/index.html	were_innovative
Slide	sections/were_innovative/slides/introduction/index.html	were_innovative/introduction
Slide	sections/were_innovative/slides/super_stats/index.html	were_innovative/super_stats
Slide	sections/were_innovative/slides/fancy_infographic/index.html	were_innovative/fancy_infographic
Subslide	sections/were_innovative/slides/fancy_infographic/index.html	were_innovative/fancy_infographic/subslide-1
Subslide	sections/were_innovative/slides/fancy_infographic/index.html	were_innovative/fancy_infographic/subslide-2

Choosing Keys

warning

Hey! Don't skip this section!

Key names are used in the project file, but they're also used for tracking and statistics.

LivePreso records tracking events against objects in a Version. When you create a new Version by importing a Pack, existing events continue to point at the previous Version. We need to link up events across Versions, and we do that by matching the keys you've assigned to Sections, Slides and Subslides.

An example of where this is useful is counting how many times a Slide has been viewed in presentations. If "Slide Monkey" has been viewed three times in version 1, then twice more in version 2, we want to recognise that as five views.

However, sometimes we do want the link to be broken. If a Slide's content changes radically, it no longer makes sense to associate it with its previous version.

As a content creator, you are responsible for recognising this distinction, and retaining or changing key names as appropriate. The basic idea is:

If, between two versions, a Section, Slide or Subslide's content retains the same message or purpose, then don't change the keys.
If a Section, Slide or Subslide's content does change (for example, you might divide a slide Products into Products: Home and Products: Professional), then do change the keys.

Unique Keys

info

It is a requirement that each computed key is unique (eg. were_innovative/fancy_infographic).

It is highly recommended that all individual slide keys are also unique - this allows for easier comparison logic (eg. when working with application hooks), fewer updates if a slide is moved between sections during development and less confusion when locating slide source files.

Specifying Titles

The project file can provide human-friendly titles for Sections, Slides, and Subslides.

sections:
  - key: were_innovative
    title: "We're innovative"
    slides:
      - { key: introduction, title: "Introduction" }
      - { key: super_stats, title: "Super stats" }
      - { key: fancy_infographic, title: "Fancy infographic" }
  - key: product_suite
    title: "Product suite"
  - key: thank_you
    title: "Thank you"

note

A slide's final key - as discussed in the content keys section above, is the combination of its containing section's directory name, as well as its own directory's name. These names are concatenated from the project file to create the final key, so you only need to list the slide's immediate directory name in the project file.

Ordering

Sections and Slides have their default orders defined in the project.yaml. This ordering can later be overridden by administrators, and can again be changed by salespeople when they create presos.

Sections or Slides not mentioned in project.yaml are removed from the deck's compiled directory on upload. Your deck directory structure must always match the project.yaml.

The ordering of the sections list defines the ordering that the Sections and Slides will have.

example:

sections:
  - key: were_innovative
    title: "We're innovative"
    slides:
      - { key: introduction, title: "Introduction" }
      - { key: super_stats, title: "Super stats" }
      - { key: fancy_infographic, title: "Fancy infographic" }
  - key: product_suite
    title: "Product suite"
  - key: thank_you
    title: "Thank you"

result:

were_innovation: 1
were_innovation/introduction: 2
were_innovation/super_stats: 3
were_innovation/fancy_infographic: 4
product_suite: 5
thank_you: 6

Slides should be listed with their individual key - e.g. introduction rather than their namespaced key were_innovative/introduction. These keys are then combined with their parent section name's - where applicable, to create the final keys as mentioned in the content keys section.

Tags

Tagging is used in the project file to add extra information to sections and slides when they are being uploaded to the server. This allows you to trigger LivePreso functionality such as editable slides and PDF limitations, as well as the inclusion of custom tags which you can use for your specific deck's features. All of the tags in the project.yaml that aren't LivePreso tags will be added to the server when a deck version is uploaded. A manager can use PresoManager to add these tags to sections or slides, or remove existing tags from sections and slides.

LivePreso tags

There are several standard tags used by the LivePreso app to trigger specific functionality:

prep-only

Used to make a slide only viewable in prep and review modes.

Slides you may want to exclude from presentations include:

slides used for user admin
information gathering slides which the user needs to fill in prior to presenting

sections:
  - key: your_quarterly_review
    title: "Your quarterly review"
    slides:
      - { key: checklist, title: "Check list", tags: [prep-only] }
      - { key: calculator, title: "Calculator", tags: [prep-only] }
      - { key: quarterly_review, title: "Quarterly review" }

not-for-sharing

Used to prevent a slide from being included in OnlinePresos or published in shared PDFs.

Slides you may want to exclude from sharing include:

sensitive information that cannot be shared outside of a guided preso
information gathering slides that must be completed with the presenter

sections:
  - key: how_we_measure_up
    title: "How we measure up"
    slides:
      - { key: our_performance, title: "Our performance" }
      - {
          key: our_competitors,
          title: "Our competitors",
          tags: [not-for-sharing],
        }
      - {
          key: your_feedback_form,
          title: "Your feedback",
          tags: [not-for-sharing],
        }

not-for-pdf-export

Used to prevent a slide from being published in shared PDFs.

Slides you may want to exclude from PDFs include:

video slides
slides that require interactivity to tell their story
sensitive information that should not be published in print

sections:
  - key: were_innovative
    title: "We're innovative"
    slides:
      - { key: about_us_video, title: "About us", tags: [not-for-pdf-export] }
      - { key: super_stats, title: "Super stats" }
      - {
          key: fancy_infographic,
          title: "Fancy infographic",
          tags: [not-for-pdf-export],
        }

off-by-default

Used to turn select slides off by default at preso creation.

Slides you may want turned off by default include:

optional editable slide
additional product information

sections:
  - key: agenda
    title: "Agenda"
    slides:
      - {
          key: previous_meeting_notes,
          title: "What we covered last time",
          tags: [editable, off-by-default],
        }

Caveats

off-by-default is not applied when creating a new preset from the app's presets page.
During preso creation, if a preset has been selected, off-by-default is ignored with preference given to the slide's visibility in the chosen preset.
Selections code also runs after the tag is applied and any preset has been loaded, and can independently affect the visibility of slides and sections.

editable

Slides that make use of LivePreso's editable feature need to be tagged as editable in the project file.

sections:
  - key: thank_you
    title: "Thank you"
    tags: [editable]

See the editable slides guide for more information.

subslide_container

In order to allow adjunct subslides to be generated by the selections.js, the target slide is required to be tagged as subslide_container in the project file.

sections:
  - key: a_first_class_team
    title: "A first class team"
    slides:
      - { key: our_agents, title: "Our agents", tags: [subslide_container] }

See the dynamically generate subslides guide for more information.

Custom tags

Tags can also be custom, allowing you to add information required specifically by your deck.

A good example would be to tag specific product types, which are then referenced in an uploaded Excel spreadsheet on preso creation, before using selections to turn the relevant slides on/off.

sections:
  - key: product_suite
    title: "Product suite"
    slides:
      - { key: awesome_product, title: "Awesome product", tags: [premium] }
      - {
          key: great_product,
          title: "Great product",
          tags: [standard, limited_release],
        }
      - { key: good_product, title: "Good product", tags: [standard] }

Further functionality

Not all options are covered here, read more in the project file reference.

Version​

Name​

Source and distribution​

Deck key​

Maintainer​

Servers​

Dimensions​

Common​

Hooks​

Data feeds​

Templated Sources​

Fixtures​

Screenshots​

Sections, slides & subslides​

Keys​

Choosing Keys​

Unique Keys​

Specifying Titles​

Ordering​

Tags​

LivePreso tags​

Custom tags​

Further functionality​

Version

Name

Source and distribution

Deck key

Maintainer

Servers

Dimensions

Common

Hooks

Data feeds

Templated Sources

Fixtures

Screenshots

Sections, slides & subslides

Keys

Choosing Keys

Unique Keys

Specifying Titles

Ordering

Tags

LivePreso tags

Custom tags

Further functionality