Screen package format

A screen package carries pages, symbols, popups and layouts from outside into a YTCC project. This page describes the format for anyone who produces packages, by hand or with a tool. How a package is imported is described in Import a screen package.

Before it adds anything, YTCC checks the package and reports errors and warnings. A package with an error cannot be imported. A package with warnings can, after the user confirms them with Import anyway. Deliver packages with no errors and no warnings.

Folder structure

<package>/
  manifest.json
  pages/<name>.json      one file per page
  symbols/<name>.json    one file per symbol
  modals/<name>.json     one file per popup
  layouts/<name>.json    one file per layout
  assets/<file>          images used by the package

• The package is a zip file or a folder. manifest.json lies at the top level or inside one single top folder.
• Leave out folders you do not use.
• File names are free; YTCC reads the identity of an item from its id, not from the file name. Keep file names to letters, digits, -, _ and .. In a zip file, names with other characters are read correctly only if the zip marks them as UTF-8; otherwise they are read in the old DOS code page and a path in the manifest may not be found.
• Each JSON file is UTF-8 and contains one JSON object, not an array.
• __MACOSX/, .DS_Store, Thumbs.db and desktop.ini are ignored.
• A package holds at most 20,000 files. The size limits and the accepted zip formats are listed under Limits.

manifest.json

{
  "format": "ytcc-ekran-paketi",
  "version": 1,
  "name": "Boiler House Screens",
  "description": "Boiler house overview and pump faceplate",
  "pages":   ["pages/boiler-house.json", "pages/pump-detail.json"],
  "symbols": ["symbols/pump.json"],
  "modals":  ["modals/pump-command.json"],
  "layouts": [],
  "startPage": "page_boiler"
}

Field	Rule	If wrong
format	Exactly ytcc-ekran-paketi	Error
version	1	Error
name	Name of the package, shown in the import window	Warning if empty
description	Free text
pages, symbols, modals, layouts	Arrays of paths of the form <folder>/<name>.json, in that folder. The order is the order in the project. A missing array counts as empty.	Error for a path in another form or a missing file
startPage	Optional. The id of a page of the package. The page becomes the start page of the project if the project has none.	Error if it is not a string or not a page of the package

A JSON file in one of the four folders that the manifest does not list is not imported, and the check warns about it.

Item files

Item	Required fields	Also checked
Page	id, name, widgets	background if present; the canvas is canvasWidth × canvasHeight, 1920 × 1080 when not set
Symbol	id, name, params, width, height, widgets	width and height positive; params an array of strings; paramTypes
Popup	id, name, width, height, background, widgets	width and height positive; params; paramTypes
Layout	id, name, widgets	Objects outside the canvas are not checked

• name must not be empty. widgets is an array of objects.
• background is an object with type (solid, linear or radial) and a valid color.
• paramTypes maps a parameter to tag, string, number or color.
• A field that the item type does not know gives a warning. shapeOps is allowed in pages, symbols and popups (see Shape operations).
• folderId is not imported: the items arrive at the top level of their list. The page fields widgetCount and widgetTypes are dropped as well.

Inside a symbol or a layout, the x and y of the objects count from its top-left corner; inside a popup from the popup's top-left corner. Units are pixels, y grows downwards, rotate is in degrees around originX / originY (0.5 / 0.5 by default).

Identifiers

• An id matches ^[A-Za-z0-9_-]{1,120}$. Prefixes such as page_, sym_, modal_, layout_ and w_ for objects keep packages readable.
• The id of a page, symbol, popup or layout is unique in the whole package. An object id is unique in its file.
• Popups are referenced by their name, all other items by their id.

If the project already has an item with the same id or name, the import gives the new item another one and updates the references inside the package (see Import a screen package).

Objects

Every object has type, id, name, x and y. type is one of the object types listed in Object properties; the field names there are the field names of the package.

Check	Level
Unknown type	Error
A required field of the type is missing and has no default	Error
A required field is missing but has a default (other than width, height, radius, points, pts, x2, y2 and symbolId)	Warning; the default is filled in
A field the type does not know	Warning
x, y not a number (a binding or a #parameter# is allowed)	Error
width, height, radius not positive	Error
points / pts with fewer than 2 points (3 for a polygon), or points that are not {"x": …, "y": …}	Error
x, y of a point object not the smallest x and y of its points	Warning
x2, y2 of a line not a number	Error
The object reaches outside the canvas (pages, symbols and popups)	Warning

Property values are checked against the property type:

Property type	Accepted value
List of choices	One of the choices
Color	#rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), rgba(), hsl(), hsla() or a color name such as white, transparent, none
Number	A number. A number written as text ("12") gives a warning.
Yes / no	true or false
Text, signal	A string
Font	One of system, arial, helvetica, calibri, segoe-ui, tahoma, verdana, times, georgia, cambria, courier, consolas, sans-serif, serif, monospace, or empty
Lists (options, series, images, element styles, areas, patterns, priorities)	An array

A #parameter# placeholder (a symbol or popup parameter) is accepted for positions, sizes, colors and numbers.

Signal bindings

A property marked Bindable in the object properties takes {"$bind": "<signal>"} instead of a fixed value:

• $bind is a signal name and must not be empty.
• map is optional. map.mode is direct, bit, value, range, string or expr; bit needs on and off; value, range and string need a cases array.
• Other keys than $bind, map and rules give a warning.
• A binding on a property that cannot be bound is an error.

Signals are referenced by name. Names that the project does not have are listed in the import window; they do not block the import and are bound later in the editor. Names that contain a #parameter# are not checked.

References

Reference	Must point to
symbolId of a symbol instance	A symbol of the package
symbolId as a binding (symbol chosen by state)	Every symbol of the mapping, including fallback and unavailable, is in the package; at least one symbol
params of a symbol instance	The parameters of the symbol. A missing or an extra parameter gives a warning; a color or number parameter with a wrong value is an error.
openModalOnClick, openModalOnMiddleClick, openModalOnRightClick, closeModalOn…	The name of a popup of the package
events	Only onClick, onMiddleClick and onRightClick, each with actions
Action openPopup	params.modalName is the name of a popup of the package
Action navigate	params.pageId is a page of the package
Action confirm	The actions in params.onConfirm are checked the same way
startBind, endBind	An object of the same file
eventScripts	event is a known event: onClick, onMiddleClick, onRightClick, onDblClick, onMouseEnter, onMouseLeave, onMouseDown, onMouseUp, onValueChange, onKeyDown, onKeyUp, onFocus, onBlur

The actions are writeTag, toggleTag, confirm, console, navigate, openPopup, closePopup, mapView, signalDetail, driverControl, systemStop and openTrend; they are described in Action types.

Images

Images are separate files in assets/. Any string value of an object refers to one with asset:<file name>, for example "src": "asset:pump-icon.png" or "svgSrc": "asset:valve.svg". At the import, YTCC uploads each referenced image to the project and replaces the reference with the image's address in the project. An image that the project already has with the same content is not stored twice.

Check	Level
A referenced image is not in assets/	Error
A file type other than png, jpg, jpeg, gif, webp, bmp, svg, ico	Error
A file larger than 25 MB	Error
An image name with other characters than letters, digits, ., _, -	Error
A data: address (an image embedded in the JSON)	Error
A /media/ address (an image of another project)	Warning
An image in assets/ that nothing refers to	Warning; it is not uploaded

BMP images are stored as PNG without loss.

Shape operations

A page, symbol or popup file can carry shapeOps: a list of commands that the import runs in order, with the same operations as Shape Operations in the editor (see Combine and cut shapes).

"shapeOps": [
  { "op": "union",    "inputs": ["w_hall", "w_annex"],   "result": "w_building" },
  { "op": "subtract", "inputs": ["w_building", "w_yard"], "result": "w_plan" },
  { "op": "offset",   "inputs": ["w_plan"], "distance": 12, "result": "w_fence" }
]

Rule	Level
op is union, combine, fragment, intersect, subtract, join, trim or offset	Error
inputs is a non-empty array of object ids of the same file, or results of earlier commands, each named once	Error
Inputs are top-level objects of type rectangle, circle, pentagon, hexagon, polygon, path, polyline, pencil or arrow; not objects in a group	Error
union, combine, fragment, intersect and subtract need at least one closed shape	Error
union, combine, intersect, subtract, fragment and join need two inputs; fragment and join also work on one path	Error
An input used by an earlier command is gone (except after offset, which keeps its source)	Error
Results of fragment, trim and offset have several parts and cannot be inputs	Error
result is a valid id that the file does not have yet	Error
offset needs a positive distance in pixels; distance on another operation	Error / warning
Another key than op, inputs, result, distance	Warning

The first input is the primary one: the result takes its style and, for the operations with one result, its name, events and popup links. The check does not compute geometry. Shapes that do not overlap, or a subtraction that leaves nothing, stop the import with an error at that point, before any image is uploaded.

Style warnings

These warnings point to designs that break the screen style of YTCC. They do not block the import.

• A gradient page or popup background, or a gradient fillStyle, backgroundFillStyle or pipeFillStyle.
• A dark page background.
• An image larger than half the canvas: build the screen from objects, not from one picture.
• blink set to true without a signal.
• A fixed alarm color (#e22028, #ec8629, #f5e11b, #916aad) as fill, color, background or line of an object whose visibility is not bound to a signal.