@ewizardjs/structure-api

STRUCTURE API

Structure api is a set of methods that will allow you to simplify your work with slides, chapters, storyboard, structure.json and the structure of the eDetailer as a whole. It also can be used in content from ewizardjs module.

Install structure-api with npm

  npm i @ewizardjs/structure-api

Usage/Examples

In your ".ts"/".js" files:

import {
  getSlides,  
  getSlidesAsync,  
  getFlatSlides,  
  getVisibleSlides,  
  getFlatVisibleSlides,  
  getHiddenSlides,  
  getFlatHiddenSlides,  
  getArchivedSlides,  
  getSlide,  
  getFlatSlide,  
  getChapters,  
  getHiddenChapters,  
  getVisibleChapters,  
  getChapter,  
  getChapterSlides,  
  getFlatChapterSlides,  
  getSlideSubslides,  
  getStartSlide,  
  getStoryboard,  
  getStructureFileVersion,  
  convertToStructureV2,  
  makeStructure,  
  supportsStructureV2,  
} from '@ewizardjs/structure-api';  
  
const structure = readJson('./structure.json');  
  
const visibleSlides = getSlides(structure, { visible: true });  
const storyboard = getStoryboard(structure);  
const onlyVisisbleSlidesStructure = makeStructure(visibleSlides);  

In your ".vue" files:

  this.$structure.someMethod()

Data-structures

Name	Fields
NestedSlideData	id, name, chapter , type , thumbnail, template, custom, subslides
FlatSlideData	id, name, chapter , type , thumbnail, template, custom, subslides, isSubslide ,parentSlide
ChapterData	id, name, type, custom
StartSlide	slide, chapter
NestedChapterData	id, name, type, slides

Available Interfaces / Types / etc

Name	Description
StructureApi	Namespace under which all api methods are available, as well as data structures and their types
iStructureJSON	Union for structure.json format version 1 or 2
StructureV1	Namespace under which the json structure format of the first version, the slide and chapter interface are available
StructureV2	Namespace under which the json structure format of the second version, the slide and chapter interface are available as well as the Storyboard element
iStart	Start slide interface

API Reference

Method	Arguments	Execution result	Description
getSlide	structureJson, slideId[, systemSettings]	Object of type NestedSlideData or undefined	To retrieve information about a single, specific slide, use this method
getSlides	structureJson[, slideTypes [, systemSettings]]	Array of objects of type NestedSlideData	Use this method to get information about all slides
getSlidesAsync	structureJson[, slideTypes[, systemSettings[, callback]]]	Array of objects of type NestedSlideData or any other Object	To get custom slide data objects or modify slide fields, use this method. The callback code will be called for all slides, including their subslides.
getFlatSlides	structureJson[, slideTypes[, systemSettings]]	Array of objects of type FlatSlideData	Similar to getSlides, but will return a set of slide objects without the "subslides" field - subslides will be returned along with the slides. Use isSubslide to distinguish between a slide and a subslide
getVisibleSlides	structureJson[, systemSettings]	Array of objects of type NestedSlideData	Similar to the getSlides method , but will only return slides of the "visible" type
getFlatVisibleSlides	structureJson[, systemSettings]	Array of objects of type FlatSlideData	Similar to the getFlatSlides method , but will only return slides of the "visible" type
getHiddenSlides	structureJson[, systemSettings]	Array of objects of type NestedSlideData	Similar to the getSlides method , but will only return slides of the "hidden" type
getFlatHiddenSlides	structureJson[, systemSettings]	Array of objects of type FlatSlideData	Similar to the getFlatSlides method , but will only return slides of the "visible" type
getArchivedSlides	structureJson[, systemSettings]	Array of objects of type NestedSlideData	Similar to the getSlides method , but will only return slides of the "archived" type
getFlatSlide	structureJson, slideId[, systemSettings]	Object of type FlatSlideData	To retrieve slide data (without the "subslides" field) or to check if a given slide is a subslide or to retrieve a parent slide, use this method.
getChapters	structureJson[, chapterTypes]	Array of objects of type ChapterData	Use this method to get a list of chapters and define their types. The order is determined by the order in the "chapters" field
getHiddenChapters	structureJson	Array of objects of type ChapterData	Similar to the "getChapters" method, but it will only return "hidden" chapters
getVisibleChapters	structureJson	Array of objects of type ChapterData	Similar to the "getChapters" method, but it will only return "visible" chapters
getChapter	structureJson, chapterId	Object of type ChapterData or undefined	Use this method to get a chapter data or check if it exists
getChapterSlides	structureJson, chapterId[, slideTypes[, systemSettings]]	Array of objects of type NestedSlideData	Similar to the getSlides method , but will only return slides of the passed chapter
getFlatChapterSlides	structureJson, chapterId[, slideTypes[, systemSettings]]	Array of objects of type FlatSlideData	Similar to the getFlatSlides method , but will only return slides of the passed chapter
getSlideSubslides	structureJson, slideId[, slideTypes[, systemSettings]]	Array of objects of type SlideData	Use this method to get a subslide of a particular slide
getStartSlide	structureJson[, systemSettings]	Object of type StartSlide or undefined	Use to get a starting slide. If not specified explicitly in structure.json - it will return the first "visible" slide
getStoryboard	structureJson[, chapterTypes[, systemSettings]]	Array of objects of type NestedChapterData	Returns the list of chapters and slides in them, based on their order in the "storyboard" and "content" fields, respectively
getStructureFileVersion	structureJson	number	Returns the file format number of the structure.json file
convertToStructureV2	structureJson	JSON of type StructureV2.iStructureJSON	Use when you want to convert structure.json content to version 2
makeStructure	nestedSlidesData, targetStructureVersion	JSON of type iStructureJSON	Accepts nestedSlidesData objects as input and builds structure.json content based on them
supportsStructureV2	ewizardjsVersion	boolean	Use if necessary to check if the version of "ewizardjs" transferred supports the structure of the second version. (Incompatible structure.json and content versions cause navigation problems, etc.)

Arguments of the methods

Name	Description	Example
structureJson	structure.json file content	--
slideTypes	The filters object for the slide type	{ visible?: true, hidden?: false, archived?: false }
systemSettings	Fragment of the default paths object. Necessary to form a thumbnail path in slide-type structures. Can be obtained from module "@ewizardjs/system-settings". If not passed - field "thumbnail" will be empty for all slides and subslides	{ path: { slides: string, slide: { thumbnail: string }}}
chapterTypes	The filters object for the chapters type	{ visible?: true, hidden?: false }
slideId	String that represents target slide id	'custom'
chapterId	String that represents target chapter id	'home'
targetStructureVersion	structure.json format version. Default is 1	2
ewizardjsVersion	The full version of the "ewizardjs" module. The version must be valid for the "semver" module	'5.23.0'

How does type detection works?

Structure-api methods work in 2 steps.
On the first stage the JSON version of the structure is checked.
If it is the first version, it converts to the second one.
On the second stage, they work directly with JSON of the second version.
The following describes the logic of determining the types of slides and chappers at each stage:

Defining types of slides and chappers when converting the structure of the first version to the second version:

1. Archived slides: slides that start with "!" or do not have a chapter (missing in the chapters content).
2. Chapter cannot be "archived". If the chapter is not in the storyboard, or it is, but starts with "!" - "hidden"

Defining types of slides and chappers when working with the structure of version 2:

1. A chapter cannot be an archive at all. Chapter is "visible" if it is present in the storyboard and has { hidden: false }. In other cases, it is "hidden".
2. A slide can be "archived" only if it has no chapter , or if it is listed as archived in "archivedSlides" field.

How is the order of slides determined?

There are two main methods for getting slides: getSlides and getFlatSlides (the other methods overuse these). The order of the slides is determined by the order of the chapters in the "chapters" field of the structure.json file. Getting a list of all chapters from this field collects all slides from each chapter (from the "content" field). During this assembly, if a slide from the "content" field has sub-slides, they will go right after the parent slide. After that, this set is supplemented with slides that are in the "slides" field of structure.json file, but were not included in the previous stages. If the order of chapters and slides is important to you, use the getStoryboard method