Frequently Asked Questions

Q: Where should I put my Witchcraft scripts?

A: You must put them in the same folder being served by Web Server Chrome app. Read full instructions here.

Q: How to add jQuery to my scripts?

A: Use the @include directive as described in "Including other scripts" here. jQuery must be downloaded and added to your scripts folder so the directive can find it. However, if you allow me to give you a suggestion, stop using jQuery unless you really need to. Most things nowadays can be easily done in pure Javascript. jQuery did its part years ago to help and save Javascript, but now it's time for its well-deserved retirement.

Q: Why do I need to install Web Server Chrome app?

A: Witchcraft will look for scripts in http://127.0.0.1:5743 (e.g., http://127.0.0.1:5743/github.com.js). It doesn't have its own web server, that's why it depends on Web Server Chrome app. You don't need to use Web Server Chrome app if you don't want to, as long as you replace it with another local web server listening on port 5743 and serving static files from your Witchcraft scripts folder. For a comprehensive list of local server options, check this gist.

Q: When exactly my script gets loaded?

A: It's loaded at document_start. This is after any css files, but before any other DOM is constructed or any other script is run. If you need, you can wait for DOMContentLoaded or the window load event.

Q: My script seems to be loading multiple times. What is wrong?

A: Your page probably has frames/iframes in it. By design, Witchcraft loads itself into every window it can find. If you want to run your script in only one of the windows, you need to add that condition to your script. For instance, you most likely only want to run your code in the topmost window. If that's your case, just check if window.self === window.top. More details here.

Q: How to load Witchcraft only in the topmost window?

A: Check the question above.

Q: I'm unable to read custom properties from or change the window object in any way. What is wrong?

A: Scripts can't directly access the window object. They share the DOM tree, but they live in isolated worlds. This is a restriction imposed by the Chrome extension API. You can, however, work around it easily.

Q: How do I inject scripts into my localhost web server page?

Q: But couldn't Witchcraft spawn its own local web server?

A: No. It is a Chrome extension. Chrome extensions don't have permission to access your file system. You need a Chrome app for that, but it turns out Chrome apps are no longer being supported by Google. This means you can't publish any new Chrome apps. However, existing Chrome apps (like the Web Server Chrome app) are still being supported, so it's ok to rely on them.

Q: Can I install Witchcraft from sources instead?

A: Yes, you can install Witchcraft directly from sources instead of downloading it from the Chrome store. Look for the extension source under the folder `/chrome-extension` and manually load it as an unpacked extension. If you don't know how to load unpacked extensions in Chrome, just google it; it's very easy.

Q: Is Google Analytics being used? Why?

A: Yes. It is being used to track actions performed inside the Witchcraft pop-up window (.e.g: "user clicked the report issue button") and to collect general statistics (e.g.: how many times was a JS include directive triggered). Code is carefully tailored to make sure no user-identifiable information is sent to GA. For instance, URLs being accessed and script names are not sent to GA in any way. People are encouraged to verify the code themselves and also load the extension right from the sources if they don't trust the Chrome Web Store package. The intent of Witchcraft is to be a free and helpful tool.

Q: How can I load other resources in my scripts, like images?

A: There are three proposed ways to do it here.