Package dom provides Go bindings for the JavaScript DOM APIs.
This package is an in progress effort of providing idiomatic Go
bindings for the DOM, wrapping the JavaScript DOM APIs. The API is
neither complete nor frozen yet, but a great amount of the DOM is
already usable.
While the package tries to be idiomatic Go, it also tries to stick
closely to the JavaScript APIs, so that one does not need to learn
a new set of APIs if one is already familiar with it.
One decision that hasn't been made yet is what parts exactly should
be part of this package. It is, for example, possible that the
canvas APIs will live in a separate package. On the other hand,
types such as StorageEvent (the event that gets fired when the
HTML5 storage area changes) will be part of this package, simply
due to how the DOM is structured – even if the actual storage APIs
might live in a separate package. This might require special care
to avoid circular dependencies.
The documentation for some of the identifiers is based on the
MDN Web Docs by Mozilla Contributors (https://developer.mozilla.org/en-US/docs/Web/API),
licensed under CC-BY-SA 2.5 (https://creativecommons.org/licenses/by-sa/2.5/).
The usual entry point of using the dom package is by using the
GetWindow() function which will return a Window, from which you can
get things such as the current Document.
The DOM has a big amount of different element and event types, but
they all follow three interfaces. All functions that work on or
return generic elements/events will return one of the three
interfaces Element, HTMLElement or Event. In these interface values
there will be concrete implementations, such as
HTMLParagraphElement or FocusEvent. It's also not unusual that
values of type Element also implement HTMLElement. In all cases,
type assertions can be used.
Example:
Several functions in the JavaScript DOM return "live"
collections of elements, that is collections that will be
automatically updated when elements get removed or added to the
DOM. Our bindings, however, return static slices of elements that,
once created, will not automatically reflect updates to the DOM.
This is primarily done so that slices can actually be used, as
opposed to a form of iterator, but also because we think that
magically changing data isn't Go's nature and that snapshots of
state are a lot easier to reason about.
This does not, however, mean that all objects are snapshots.
Elements, events and generally objects that aren't slices or maps
are simple wrappers around JavaScript objects, and as such
attributes as well as method calls will always return the most
current data. To reflect this behavior, these bindings use
pointers to make the semantics clear. Consider the following
example:
The above example will print `true`.
Some objects in the JS API have two versions of attributes, one
that returns a string and one that returns a DOMTokenList to ease
manipulation of string-delimited lists. Some other objects only
provide DOMTokenList, sometimes DOMSettableTokenList. To simplify
these bindings, only the DOMTokenList variant will be made
available, by the type TokenList. In cases where the string
attribute was the only way to completely replace the value, our
TokenList will provide Set([]string) and SetString(string) methods,
which will be able to accomplish the same. Additionally, our
TokenList will provide methods to convert it to strings and slices.
This package has a relatively stable API. However, there will be
backwards incompatible changes from time to time. This is because
the package isn't complete yet, as well as because the DOM is a
moving target, and APIs do change sometimes.
While an attempt is made to reduce changing function signatures to
a minimum, it can't always be guaranteed. Sometimes mistakes in the
bindings are found that require changing arguments or return
values.
Interfaces defined in this package may also change on a
semi-regular basis, as new methods are added to them. This happens
because the bindings aren't complete and can never really be, as
new features are added to the DOM.