diff options
author | Vincent Sanders <vince@kyllikki.org> | 2019-05-02 11:13:09 +0100 |
---|---|---|
committer | Vincent Sanders <vince@kyllikki.org> | 2019-05-02 11:13:09 +0100 |
commit | 148639b70c3831693c08bb00d5ef372d59088840 (patch) | |
tree | 04958e37a53a78579927c6e786cd2a9b702f7186 /docs/jsbinding.md | |
parent | ccb499b80057a8241829a3ba11e5f87013739c8d (diff) | |
download | netsurf-148639b70c3831693c08bb00d5ef372d59088840.tar.gz netsurf-148639b70c3831693c08bb00d5ef372d59088840.tar.bz2 |
add initial javascript binding documentation
Diffstat (limited to 'docs/jsbinding.md')
-rw-r--r-- | docs/jsbinding.md | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/docs/jsbinding.md b/docs/jsbinding.md new file mode 100644 index 000000000..c258a678d --- /dev/null +++ b/docs/jsbinding.md @@ -0,0 +1,59 @@ +Javascript bindings +=================== + +In order for javascript programs to to interact with the page contents +it must use the Document Object Model (DOM) and Cascading Style Sheet +Object Model (CSSOM) API. + +These interfaces are described using web Interface Description +Language (IDL) within the relevant specifications +(e.g. https://dom.spec.whatwg.org/). + +Each interface described by the webIDL must be bound (connected) to +the browsers internal representation for the DOM or CSS, etc. These +bindings desciptions are processed together with the WebIDL by the +nsgenbind tool to generate source code. + +A list of [DOM and CSSOM methods](unimplemented.html) is available +outlining the remaining unimplemented API bindings. + +WebIDL +------ + +The WebIDL specification defines the interface description language used. + +These descriptions should be periodicaly updated to keep the browser +interfaces current. + +There is a content/handlers/javascript/WebIDL/Makefile which attempts +to automaticaly update the IDL files by scraping the web specs. + +This tool needs a great deal of hand holding, not least because many of the +source documents list the IDL fragments multiple times, some even have +appendicies with the entrire IDL repeated. + +Interface binding introduction +------------------------------ + +The binding files are processed by the nsgenbind tool to generate c +source code which implements the interfaces within the javascript +engine. + +The bindings are specific to a javascript engine, the DOM library, the +CSS library and the browser. In this case that is the tuple of +duktape, libdom, libcss and NetSurf. + +In principle other engines or libraries could be substituted +(historicaly NetSurf unsucessfully tried to use spidermonkey) but the +engineering to do so is formidable. + +The bindings are kept the sorce rpository within the duktape +javascript handler content/handlers/javascript/duktape/ + +The root binding which contains all the interfaces initroduced into +the javascript programs initial execution context is nesurf.bnd this +references all the WebIDL to be bound and includes all additional +binding definitions to implement the interfaces. + +The bindings are a Domain Specific Language (DSL) which allows +implementations to be added to each WebIDL method. |