Content creation rules with the Platform API

Content creation rules is an option for windows and views. Using this option changes how views are created under the hood.

Set as contentCreation.rules in options.

const options = {
  name: 'name',
  url: 'url',
  contentCreation: {
    rules: [
      {
        match: ['<all_urls>'],
        behavior: 'window',
        options: {
          frame: false
        }
      }
    ]
  }
}

📘

Note

These rules apply only to content creations coming from window.open or user interaction (that is, links). They do not impact the creation of contents through the fin API.

Rule shape

• rule.match is an array of match patterns, which are used to match the URL being created.

• rule.behavior specifies how the URL is to be opened.

• rule.options is an optional property for window and view creations. It is a set of options that are applied in addition to the default options.

Each rule has the following shape:

interface ContentCreationRule {
  behavior: 'view' | 'window' | 'browser' | 'block';
  match: string[];
  options? Partial<ViewOptions> | Partial<WindowOptions>
}

Rule precedence

The matching engine iterates over the rules in the order they are defined and stops at the first rule that matches the URL being opened.
If no matches are found, the default behavior of opening a window is used.
To change the default behavior, make sure the last rule in the rules array contains the following match pattern:

{match:['<all_urls>']}

Rule inheritance

Views and windows inherit rules from their parents. If no match is found in a view or window’s rules, the engine checks the entity’s parent’s rules.

To prevent this inheritance, set a rule matching <all_urls> at the end of the rules array.

Example

The following highly contrived example shows the precedence of rules:

const contentCreationOptions = {
  rules: [
    {
      behavior: 'window',
      match: [
        '*://*.stackoverflow.com/*'
      ],
      options: {
        'frame': false,
        'alwaysOnTop': true,
        'defaultWidth': 800,
        'defaultHeight': 600
      }
    },
    {
      behavior: 'browser',
      match: [
        '*://*.gitlab.com/*'
      ]
    },
    {
      behavior: 'view',
      match: [
        '*://*.reddit.com/r/javascript'
      ],
      options: {
        'title': '...loading'
      }
    },
    {
      behavior: 'block',
      match: [
        '*://*.reddit.com/*'
      ]
    },
    {
      behavior: 'window',
      match: [
        '*://*/*?window=true'
      ]
    },
    {
      behavior: 'view',
      match: [
        '<all_urls>'
      ]
    }
  ]
}

In the preceding example, the rule order is as follows:

1. Any URL containing stackoverflow.com opens in a frameless alwaysOnTop window.

2. Any URL containing gitlab.com opens in the browser.

3. Any URL matching Reddit’s javascript subreddit opens in a view with a custom title (while it’s loading).

4. All other URLs on Reddit are blocked.

5. Any URL that has ?window=true query parameters opens in a window.

6. By default. all URLs that do not match anything else open in a view.

📘

Note

By using rules, you can create child views. By setting the contentCreation option, views created through the fin.View.create method are also children. Just like a window, they can have a window.opener (if it is on the same origin and in the same processAffinity). However unlike windows, the lifecycle of views is not tied to that of their parent. They maintain the regular view lifecycle of closing when their target is destroyed.