Developer Documentation

Build instructions for 4chan X can be found at: https://github.com/ccd0/4chan-x/blob/master/CONTRIBUTING.md#development--contribution

The source code of 4chan X is located in the src/ directory. The source code files are named after the object they define, so if you want to find the file that defines Header, look for Header.coffee. Exceptions to this rule are a few global objects defined in src/globals/globals.js, and the files in src/meta/, which define fragments at the top and bottom of the compiled script, and/or compile to other files, such as the Greasemonkey metadata block checked on update and the Chrome extension's manifest file and event page.

Also in the src/ directory are HTML/CSS/JSON/image/sound/etc. files which are imported at compile time using the functions defined in tools/template.js. They are located in a subdirectory named after the source file that imports them, or if there is only one source file in a directory., in the same directory as the source file. For example, the file src/Monitoring/ThreadUpdater.coffee imports the sound file src/Monitoring/ThreadUpdater/beep.wav using the code <%= readBase64('beep.wav') %>.

For the most part, each file contains one feature of 4chan X, although some files define utility classes or objects. The Main object defined in src/main/Main.coffee is invoked by Main.init() at the very bottom of the script, and it is responsible for setting up all the features, which are enumerated in Main.features.

4chan X begins running before the page is loaded, although code should not depend on this since not all userscript engines implement this feature. This is specified in the userscript via the @run-at directive in src/meta/metadata.js and in the Chrome extension via the run_at option in src/meta/manifest.json.

The first thing Main.init does is read the user's configuration (defaults set in src/config/Config.coffee) and put it into the Conf object. It then calls the init member of each of the features in Main.features to do initial setup work and register callbacks to be run on posts/threads. It then waits for the DOMContentLoaded event indicating that the DOM has finished loading, at which point it parses the threads and posts (exception: if JSON Index is on, it doesn't parse anything on the index page, but lets the Index feature generate the threads and posts). Parsing of posts is done by src/classes/Post.coffee, which from each .postContainer node creates a Post object containing parsed post details in its info member and references to significant DOM nodes in the post in its nodes member. After the threads and posts are parsed, Main invokes the callbacks on each thread and post that were registered by the features in their init member. Other features that create posts, such as the thread updater, JSON index, and quote preview/inlining, also invoke these callbacks. There are also Post.Clone objects (a subclass of Post) created by previewing or inlining a post. There's always one original post, which can have many copies made of it.