The Juicebox File Layout

Two versions of the Juicebox file layout exist. Both run on the same Juicebox kernel code. The versions are distinguished by

app.yaml

  juicebox_version: '4'

Version 3

Version 3 is designed so that each stack directory contains all resources needed for that stack.

app.yaml                   App details, list of stacks to display
theme.yaml                 Defines logo, css
help/                      Markdown or html help
public/                    Contains images used in the app
stacks/
    {stack_name}/
        stack.yaml         Stack and slice definitions.
        templates.html     Custom templates used by this stack.
        dataservice.py     Dynamic data services for this stack.
        fixtures/
        help/              Stack specific help and tour definition files.

Version 4

With version 4, “stacks” have been renamed to “stories”. The file structure has been simplified to allow visual theming reuse and to consolidate all data service code in a single place.

app.yaml                  App details and list of stories to display
help.md or help.html      Application help
theme/
    theme.yaml            Theme logo and parentage
    variables.scss        Theme variables
    styles.scss           Custom css to apply to slices
    img/                  Image assets to use as slice backgorunds
    templates/            Custom html templates
stories/
    {story_name}.yaml     Story and slice definitions.
public/                   Additional public assets that the app may rely
                          on. For instance, custom javascript code.
data_services/            Dynamic data service code for all stories

Converting from version 3 to version 4

A conversion script will allow version 3 apps to be rewritten as version 4 apps. This conversion script will be available in spring 2019.

Theme

• variables.scss are moved from theme.yaml and placed in their own file for easier editing.
• All templates are moved from templates.html in stacks to individual files named after each template.
• Slice extra_css is converted to a class that can be applied to any slice in the entire app. It’s now possible to re-use theming code across slices.
• Images that were used as slice or story backgrounds are now stored with the theme rather than in public/
• Application footer content is now part of the theme.yaml.

Stories

• Stack.yaml is now renamed as {story_name}.yaml
• Tours are moved from individual yaml files in stack/{stack_name}/help/{tour_name}.yaml to story.yaml.

Help

• Stack level help doesn’t exist. All help is in a markdown or html file at the top level of the app.