-
-
Notifications
You must be signed in to change notification settings - Fork 18
Home
Witchcraft consists of three parts: the background script, the content script and the HTTP server.
The background script is loaded only once per browser session. It starts running as soon as the extension is enabled and stays quiet, patiently waiting, listening for content scripts messages.
The content script, on the other hand, runs once per frame loaded in your browser. This means that, when your browser starts loading a new page, a new content script instance starts running. This is guaranteed by the matches property in manifest.json:
"matches": ["http://*/*", "https://*/*"],
The exact moment the content script runs is dictated by the manifest.json property run_at:
"run_at": "document_start"
From the Chrome extension developer docs, document_start means:
Scripts are injected after any files from css, but before any other DOM is constructed or any other script is run.
This is as early as any extension can get a chance to execute in any given page, so that's why it was chosen for Witchcraft, giving its users full control of the page and getting a chance to act even before the page starts being constructed. It also means that, if you need the page to be fully constructed before running your Witchcraft script, you need to wait for the load event, like this:
window.addEventListener("load", yourScriptsMainFunction);A content script is created not once per page, but once per frame. Usually, simple pages have just one frame, called the top frame. Check this example of Witchcraft running in google.com's top frame:
It is not uncommon, however, for pages to have sub-frames. When that is the case, Witchcraft needs to have a way to run inside of them as well, since the instance running in the top frame does not have access to sub-frames. The way this is done is by using the following property in manifest.json:
"all_frames": true