Skip to content

design.md

Latest commit

 

History

History
116 lines (88 loc) · 4.86 KB

design.md

File metadata and controls

116 lines (88 loc) · 4.86 KB

Design development

The visual design is defined in the src/design directory, where templates and partials are defined in the handlebars formalism. We use tailwind for defining the CSS codes.

The author app works with Python implementations of Tailwind and Handlebars to generate pages. Page generation can be done from within the app: it happens when people publish editions or when admins regenerate all pages.

It can also be done from outside the app, as a shell command, and it does not need a running pure3d deployment.

At the top-level of a clone of the repo, run this command on your local computer:

./pages-generate.sh

This generates all published pages of for mode prod.

If your need to work with different runmodes (test, custom, pilot) just add the mode as first argument:

./pages-generate.sh custom

If you only want to generate a specific project/edition, add the project-edition numbers:

./pages-generate.sh 3 2

You can view the generated pages in a local browser by starting a http server:

./pages-serve.sh prod

Explanation

The information needed for page generation comes from the following sources:

  • src/design: templates, partials, css, javascript, icons, images

  • data/viewers: versions of the Voyager 3D viewer, as copied from github. The published pages offer controls to view models in all of these Voyager versions.

  • published/prod (or instead of prod: test, custom, pilot): content of projects and editions. It contains:

    • file db.json: the content of the site record of the database; here is all the boilerplate text, the site title, the about text, etc. Whenever a piece of boilerplate is absent, a static default will be provided, which comes from the config file src/yaml/datamodel.yml.

    • directory project: contains the published projects by their number. Each project directory has:

      • file db.json: the content of the project record of the database; here the metadata of the project is stored.

      • file icon.png: a thumbnail for the project.

      • directory edition: contains the published editions of this project by their number. Each edition directory has:

        • file db.json: the content of the edition record of the database; here the metadata of the edition and some edition settings are stored.
        • file icon.png: a thumbnail for the project.
        • one or more .glb or .gltf files: the 3D models of the edition.
        • file scene.scx.json: the scene file that steers the Voyager viewer through the 3D models, and contains the annotations to those models
        • directory articles: the articles, and within that the referred media that belong to the edition, mostly written by the editor using the Voyager Story interface. Articles are linked to the models by annotations in the scen.svx.json file.

The information generated is put into the published/prod directory, next to the material that is already present. New generation runs overwrite earlier generated material.

  • published/prod

    • css/style.css: generated by Tailwind.
    • images: copied from under src/design.
    • js: copied from under src/design.
    • favicon.ico: copied from under src/design.
    • json: the variables by which the templates are filled; generated from the db.json files for site, projects, editions.
    • viewers: copied from data/viewers.
    • index.html: the home page of the published pages.
    • about.html: the about page, coming from the dc.description field in the site record, editable on the home page of the author app.
    • editions.html: the page that gives access to all published editions.
    • projects.html: the page that gives access to all visible projects.

  • published/prod/project/pp

    • index.html: the landing page of the project with number pp.

  • published/prod/project/pp/edition/ee

    • index.html: the landing page of the edition with number ee within the project with number pp. It has a Voyager viewer open on the 3D model as steered by the scene.svx.json file, in the default version of the Voyager.
    • index-voyager-v.v.v.html: as index.html, but now version v.v.v of the Voyager is used.
    • scen.svx.yaml: the scen file converted to yaml for better readability by human users.
    • toc.html: table of contents of all edition files and the scene file, with color indications where hyperlinks are dangling or which files are not referenced.
⚡