@ewizardjs/structure-api v1.0.2
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-apiUsage/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