Dev: Preferences

Preferences are saved in only two JavaScript Objects (JSON). They are:

• policy
• blackwhitelist

Both include a tree structure when dealing with web addresses. Any rule must be merged inside this tree. The basic idea of the tree is:

• domain
  • sub-domain
    • page

If the rules is for a top level, the childs can be ommited, but a child must have its parents. So if you want to apply a rule to example.com you can create a single object, but if you want to create a rule for play.example.com/index.php then you must save it as:

• example.com
  • play
    • index.php

Below you can see the full explanation of the structure for each object.

policy

The policy object holds the main preferences. In root level it contains the following keys:

• rule (required)
  • Type: integer
  • Description: Defines the global policy rule
• private (required)
  • Type: integer
  • Description: Defines the global policy rule in Private/Incognito browsing
• domains (required)
  • Type: array of JSON objects
  • Description: Contains domain rules

domains

Inside domains you have:

• name (required)
  • Type: string
  • Description: Main domain name, up to 3 levels
  • Examples: "example.com", "example.co.uk"
• rule (optional)
  • Type: integer
  • Description: Defines a policy rule for that top domain
• rules (optional)
  • Type: blackwhitelist object
  • Description: Blackwhitelist only for that top domain
• sites (optional)
  • Type: array of JSON objects
  • Description: Contains sub-domain information

At least one of the optional keys must be defined.

sites

Inside sites you have:

• name (required)
  • Type: string
  • Description: Sub domain name, any number of levels
  • Examples: "maps", "play.apis", "www"
• rule (optional)
  • Type: integer
  • Description: Defines a policy rule for that sub domain
• rules (optional)
  • Type: blackwhitelist object
  • Description: Blackwhitelist only for that sub domain
• pages (optional)
  • Type: array of JSON objects
  • Description: Contains pages information

At least one of the optional keys must be defined.

pages

Inside pages you have:

• name (required)
  • Type: string
  • Description: Webpage name, directory + file name - query
  • Examples: "/maps", "/sports/index.html", "/"
• rule (optional)
  • Type: integer
  • Description: Defines a policy rule for that webpage
• rules (optional)
  • Type: blackwhitelist object
  • Description: Blackwhitelist only for that webpage

At least one of the optional keys must be defined.

blackwhitelist

This objects holds a blacklist merged with a whitelist, one rule key defines if it's whitelisted or blacklisted.

The root key is called domains and holds an array of other objects.

domains

The keys for each of the child objects of the domains array are:

• name (required)
  • Type: string
  • Description: Main domain name, up to 3 levels
  • Examples: "example.com", "example.co.uk"
• rule (optional)
  • Type: boolean
  • Description: true to blacklist, false to whitelist this top domain
• sites (optional)
  • Type: array of JSON objects
  • Description: Contains sub-domain information
  • Examples: See sites bellow

Even though the rule and sites keys are optional, at least one must be declared.

sites

The keys for each of the child objects of sites are:

• name (required)
  • Type: string
  • Description: Sub domain name, any number of levels
  • Examples: "maps", "play.apis", "www"
• rule (required)
  • Type: boolean
  • Description: true to blacklist, false to whitelist this sub domain

Examples

blackwhitelist = {
	domains: [{
		name: "localhost",
		rule: false
	},{
		name: "google.com",
		sites: [{
			name: "maps",
			rule: false
		},{
			name: "apis", // +1 stuff
			rule: true
		}]
	},{
		name: "example.com",
		rule: true,
		sites: [{
			name: "api",
			rule: false
		}]
	}]
}

The first child is whitelisting any script or frame coming from localhost

The second whitelists maps.google.com, but blacklists apis.google.com

The third blacklists example.com, but whitelists if they come from api.example.com