Winsert Structure Overview
⯇Previous: Winsert Development Guide Home | Next: The Manifest File⯈
A packed Winsert is a compressed file containing several other files. These files are the source code of the Winsert and each file performs a specific function. This section of the guide will provide an overview of each of these files and how they relate to each other.
The typical basic Winsert source may look something like this:
📁Winsert Directory
For many Winserts, these three files are enough to accomplish the desired result. However it is possible to have multiple of some of these files, and some Winserts may include other types of files for special purposes, read on if you wish to know about them.
Note: This file is required and must be named exactly
manifest.json.
The manifest file (manifest.json) is the core of a Winsert. This is the file that tells Winside how to interpret the other files in the Winsert and tells Winside what web page to show (if it should use one at all). It also contains important metadata like the name of the Winsert, the version number, and the name of the developer.
See the page The Manifest File for more detailed information about this file and how to create one.
Note: It is possible to have none or multiple of this type of file.
The JavaScript payload files are required if you want to enhance the functionality of a web page beyond what it was intended for or if you are making a standalone Winsert that doesn't use an existing web page. These payloads are standard JavaScript that can be used to interact with elements on the page, however, they also have special Winside APIs accessible via the window.WinsideAPI, window.Winside.addons and window.Winside.vars objects. These APIs allow you to do things external to the Winsert such as open a link in the user's browser and affect the behaviour of the sidebar.
Note: It is possible to have none or multiple of this type of file.
CSS Stylesheets are essential if the page you are using does not scale well to a thin, vertical view. Many modern pages are optimised for use on mobile devices, in which case the CSS required may be minimal. The CSS is injected and acts as if it is part of the page, allowing the adjustment of basically any element to fit nicely into the sidebar.
Hint: When combined with JavaScript, styles can become very powerful. Try using them together to hide unnecessary elements behind a menu system to create a sleeker sidebar interface.
Note: It is highly recommended to include this file. Any Winsert that doesn't include it from 2023.02 onwards will use the Winside icon on exported shortcuts.
A Winsert can include an icon that will be displayed on its exported shortcuts. An icon represents the Winsert visually to users and will be displayed in other locations in future releases. The icon file must be named icon.png and is not declared in the manifest file.
Note: It is possible to have none or exactly one of this type of file.
The HTML document option is designed for those who are creating standalone Winserts which do not rely on an existing webpage. The HTML document acts as the skeleton of the page and is enhanced with JavaScript payloads and CSS stylesheets as explained above. With this option, you can essentially create anything you want to display completely from scratch.
⯇Previous: Winsert Development Guide Home | Next: The Manifest File⯈