Skip to content

The Manifest File

Jump to bottom
Spatchy edited this page Mar 16, 2023 · 4 revisions

⯇Previous: Winsert Structure Overview | Next: Injectable Content Overview⯈

Manifest File Overview

To start building a Winsert, create a new folder with your new Winsert's name and inside that folder create a file called manifest.json. The manifest file is arguably the most important file in the source. It contains the data that turns a collection of files into a usable Winsert. The manifest file is a JSON (JavaScript Object Notation) file that stores data in specific fields that Winside understands. These fields are explained in detail in this section of the guide.

Basic Metadata

The Manifest file contains some basic metadata about your Winsert that you should fill out first. These are as follows:

  • displayName - The name of your Winsert the user will see.
  • version - The version number of your Winsert. It is recommended to start at 0.1 for Winserts in development then bump this to 1.0 if you publish it.
  • developerName - The name or online alias of the person creating the Winsert.
  • description - A brief description of your Winsert and what it does. It is recommended to be no longer than about 15 words long.

example so far:

{
  "displayName": "Your Winsert Name",
  "version": "0.1",
  "developerName": "Your Name Here",
  "description": "This is a short description of this Winsert"
}

mainURL

The mainURL field is the URL of the website that Winside will display and modify with your Winsert's injectable content. This field is always required, even if you are creating a standalone Winsert which doesn't rely on an existing web page (in this scenario set the mainURL field to "about:blank").

example so far:

{
  "displayName": "Your Winsert Name",
  "version": "0.1",
  "developerName": "Your Name Here",
  "description": "This is a short description of this Winsert",
  "mainURL": "https://example.com/"
}

sidebar

The sidebar field is an object containing two other fields:

  • color - The hex color (including the leading #) of the edge of the sidebar (the part containing the exit button).
  • size - The size of the sidebar in twelfths of the user's screen. This supports any number between 1 and 11 (Defaults to 3 if missing).

example so far:

{
  "displayName": "Your Winsert Name",
  "version": "0.1",
  "developerName": "Your Name Here",
  "description": "This is a short description of this Winsert",
  "mainURL": "https://example.com/",
  "sidebar": {
    "color": "#9900ff",
    "size": 3
  }
}

inject

The inject field is an object containing the file names for injectable content, such as an HTML document, JavaScript payloads and CSS stylesheets. Make sure the file names are correctly referencing files included in your Winsert folder. These fields should be formatted as follows:

  • document [OPTIONAL] - The name of your HTML document if you are building a standalone Winsert. This will override the mainURL field.
  • script - A comma-separated array of file names (formatted in [square brackets]) of JavaScript files to inject.
  • style - A comma-separated array of file names (formatted in [square brackets]) of CSS files to inject.

Note: The script and style fields must still be provided, even if you are not injecting anything. In this case, simply use an empty array (script: [] or style: [])

example so far:

{
  "displayName": "Your Winsert Name",
  "version": "0.1",
  "developerName": "Your Name Here",
  "description": "This is a short description of this Winsert",
  "mainURL": "https://example.com/",
  "sidebar": {
    "color": "#9900ff",
    "size": 3
  },
  "inject": {
    "document": "index.html",
    "script": [
      "payload.js"
    ],
    "style": [
      "style.css",
      "more_styles.css"
    ]
  }
}

userAgent Introduced 2023.02

Note: This field is optional, feel free to omit it if you don't need it.

The userAgent field takes a string that represents a browser's user agent. This string will be passed to the web server when making a request from the rendered Winsert. This can be useful to force a website to display the mobile version of a page, which is friendlier to the sidebar's layout. see here for more information on user agents

example so far:

{
  "displayName": "Your Winsert Name",
  "version": "0.1",
  "developerName": "Your Name Here",
  "description": "This is a short description of this Winsert",
  "mainURL": "https://example.com/",
  "sidebar": {
    "color": "#9900ff",
    "size": 3
  },
  "inject": {
    "document": "index.html",
    "script": [
      "payload.js"
    ],
    "style": [
      "style.css",
      "more_styles.css"
    ]
  }
  "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion"
}

**

exposeAddons

The exposeAddons field takes an array of special options that will cause certain special data to be exposed on the window.Winside.addons object and in some cases, certain styles and scripts to run automatically. In most cases, you will likely not need this data, in which case you should use an empty array: exposeAddons: [].

Currently the only other acceptable option to put in this array is "winsideAssets". See the exposeAddons reference for more information about this option and how to use it.

Note: Using an exposeAddons option without fully understanding it may cause your Winsert to exhibit unexpected behaviour.

complete example:

{
  "displayName": "Your Winsert Name",
  "version": "0.1",
  "developerName": "Your Name Here",
  "description": "This is a short description of this Winsert",
  "mainURL": "https://example.com/",
  "sidebar": {
    "color": "#9900ff",
    "size": 3
  },
  "inject": {
    "document": "index.html",
    "script": [
      "payload.js"
    ],
    "style": [
      "style.css",
      "more_styles.css"
    ]
  },
  "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
  "exposeAddons": []
}

⯇Previous: Winsert Structure Overview | Next: Injectable Content Overview⯈

Previous Versions of This Page

2023.01

Clone this wiki locally