_Element#

class domsync.core._Element(document, id, tag)#

domsync.core._Element is analogous to the Javascript Element which represents an individual HTML element. The name of the class starts with an underscore, expressing the fact that this class should not be instantiated by the user, instead all instances of this class are created by domsync.Document.createElement().

Parameters

document (domsync.Document) – document to create the element within
id (str) – unique id of the element
tagName (str) – tag name of the element

Class attributes

innerText - sets and gets the element’s innerText, analogous to Javascript element.innerText. When used as a setter, generates the following Javascript code:
__domsync__["{self.id}"].innerText = `{innerText}`;
value - sets and gets the element’s value, analogous to Javascript element.value. When used as a setter, generates the following Javascript code:
__domsync__["{self.id}"].value = `{value}`;
tagName - gets the element’s tagName, analogous to Javascript element.tagName
children - gets the element’s list of child elements, analogous to Javascript element.children
firstElementChild - gets the element’s first child element, analogous to Javascript element.firstElementChild
lastElementChild - gets the element’s last child element, analogous to Javascript element.lastElementChild
attributes - gets the element’s dictionary of attributes
id - gets the element’s id

addEventListener(event, callback, js_value_getter=None)#

adds an event listener to the element

Parameters

event (str) – name of the event to listen to, see https://www.w3schools.com/jsref/dom_obj_event.asp for a list of valid events
callback (Callable(dict)) –

the callback function to be called when the event happens. the function must take one argument which is a dict containing the details of the message:

’event’: name of the event, one of https://www.w3schools.com/jsref/dom_obj_event.asp

’id’: id of the element that the event happened on

’doc’: domsync.Document instance

’value’: value returned as a result of evaluating js_value_getter (see below)
js_value_getter (str) –

a javascript expression that is executed in the context of the event and the return value of which is retrned in the ‘value’ field of the event message.

A good example is 'this.value' in case of the ‘input’ event of an <input type=’text’> element, this will retun the current changed value of the input.

Another example would be 'this.options[this.selectedIndex].value' in case of the ‘input’ event of a <select> element, this will retun the current changed value of the selection.

In case of a ‘click’ event of a <button> there is no need to specify a js_value_getter because the click event doesn’t carry any relevant value (apart form the fact that the event happened).

Returns

None

analogous to Javascript addEventListener, generates the following Javascript code:

__domsync__["{self.id}"].addEventListener("{event}",function(){ws_send({"event":"{event}","id":"{self.id}","value":{js_value_getter}})});

appendChild(el_child)#

append a chld element to self

Parameters: el_child (domsync.core._Element) – child element to append
Returns: None

analogous to Javascript Element.appendChild, generates the following Javascript code:

__domsync__["{self.id}"].appendChild(__domsync__["{el_child.id}"]);

getAttribute(attrib, default=None)#

gets an attribute of an element

Parameters

attrib (str) – name of the attribute to return
default – Optional, value to return in case the attribute is not available

Returns

str, the value of the attribute if the attribute exists, otherwise the value of the default argument

analogous to Javascript Element.getAttribute, doesn’t generate Javascript code.

getDocument()#

Returns: the Document instance in which the Element lives
Return type: domsync.Document

insertBefore(el_child_to_insert, el_child_before)#

inserts an element as a child before an existing child element

Returns: None

analogous to Javascript Element.insertBefore, generates the following Javascript code:

__domsync__["{self.id}"].insertBefore(__domsync__["{el_child_to_insert.id}"], __domsync__["{el_child_before.id}"]);

remove()#

removes the element and all it’s child elements recursively.

Returns: None

analogous to Javascript Element.remove, generates the following Javascript code:

__domsync__["{self.id}"].remove();

removeAttribute(attrib)#

removes the given attribute

Parameters: attrib (str) – name of the attribute to remove
Returns: None

analogous to Javascript Element.removeAttribute, generates the following Javascript code:

__domsync__["{self.id}"].removeAttribute("{attrib}");

setAttribute(attrib, value)#

sets the attribute of an element. Note: domsync gives an id attribute to all elements in domsync.Document.createElement() which is used to find elements, therefore attempting set the id attribute of an existig element results in an exception.

Parameters

attrib (str) – name of the attribute to set.
value (str) – value of the attribute to set

Returns

None

analogous to Javascript Element.setAttribute, generates the following Javascript code:

__domsync__["{self.id}"].setAttribute("{attrib}","{value}");

Document#

class domsync.Document(root_id)#

domsync.Document is analogous to the Javascriot DOM document which contains a tree of domsync.core._Element objects. Every manipulation to the document generates Javascript code that when sent to the Browser client and evaluated results in the same DOM changes on the client side that happened in the domsync.Document.

Parameters: root_id (str) – id of the element in the client-side HTML where domsync should render

on initialisation generates the following Javascript code:

var __domsync__ = [];
__domsync__["{root_id}"] = document.getElementById("{root_id}");

createElement(tagName, id=None, innerText=None, value=None, attributes=None)#

Creates a new element in the domsync.Document but doesn’t add it as a child to any existing elements, that needs to be done separately using appendChild.

This is the only way to create a new element because each element needs to be registered with the domsync.Document. This is the reason why the name of domsync.core._Element starts with an underscore character signalling that it’s a private class that is not meant to be instantiated by the user.

Parameters

tagName (str) – tag name of the element to be created
id (str) – Optional, unique id of the new element. if not provided, an automatically generated unique id will be used. Note that this is a difference between domsync and Javascript: in domsync every element has a unique id while in Javascript not necessarily.
innerText (str) – Optional, if provided this will be set as the innerText of the newly created element. equivalent to later setting the .innerText attribute of the element.
value (str) – Optional, if provided this will be set as the value attribute of the newly created element. Typically only used in case of <input type=’text’> elements. equivalent to later setting the .value attribute of the element.
attributes (dict) – Optional, if provided these attributes will be set on the element. equivalent to later using the setAttribute method on the element.

Returns

the newly created element

Return type

domsync.core._Element

analogous to Javascript document.createElement, generates the following Javascript code:

__domsync__["{id}"] = document.createElement("{tagName}");
__domsync__["{id}"].setAttribute("id","{id}"); // uses auto generated id if id was not provided

// if innerText was provided:
__domsync__["{id}"].innerText = `{innerText}`;

// if value was provided:
__domsync__["{id}"].value = `{value}`;

// if attributes was provided, for each attribute:
__domsync__["{id}"].setAttribute("{attrib0}","{value0}");
__domsync__["{id}"].setAttribute("{attrib1}","{value1}");
// ...

getElementById(id, strict=True)#

Returns the element of the given ID

Parameters

id (str) – id of the element
strict (bool) – optional, if True (default), then an exception is thrown if the provided id doesn’t exist. if False, then None is returned if the id doesn’t exist

Returns

the element of the provided id or None if the element doesn’t exist and strict is False

Return type

domsync.core._Element

analogous to Javascript document.getElementById, doesn’t generate Javascript code.

getElementsByClassName(className)#

Returns a list of elements with the specified class name

Parameters: className (str) – class name of the element
Returns: the elements of the given class name
Return type: list of domsync.core._Element

analogous to Javascript document.getElementsByClassName, doesn’t generate Javascript code

getElementsByTagName(tagName)#

Returns a list of elements with the specified tag name

Parameters: tagName (str) – tag name of the element
Returns: the elements of the given tag
Return type: list of domsync.core._Element

analogous to Javascript document.getElementsByTagName, doesn’t generate Javascript code

getRootElement()#

Returns the root element of the Document (that was passed on initialisation).

Returns: the root element
Return type: domsync.core._Element

handle_event(msg)#

The way event listeners work with domsync is that we set the event listener of an element using domsync.core._Element.addEventListener() which on the client side causes the ws_send Javascript function to be executed which sends back a message to the server containing the details of the event. When that message arrives to the server, this method needs to be called with the message as an argument which eventually triggers the callback function to be executed that was added using the domsync.core._Element.addEventListener() method.

You only need to deal with this if you are using your own server. If you use domsync.domsync_server.DomsyncServer, this is called automatically behind the scenes.

Parameters

msg (dict) –

is an event message generated on the client side containing:
’id’ of the element that generated the event
’event’ name of the HTML event that happened (see https://www.w3schools.com/jsref/dom_obj_event.asp for the list of events)
’value’ associated with the event as defined when the event was added using the js_value_getter argument of domsync.core._Element.addEventListener()

Returns

whatever the callback function returns that was added using domsync.core._Element.addEventListener()

render_js_full()#

Returns a full snapshot of Javascript code that represents the current state of the domsync.Document from scratch, not just the updates since the last time. It is useful when you have one domsync.Document instance in your memory and want to show the same instance to every users, like for example a read-only dashboard. In that case you can update your domsync.Document and send updates to already connected clients using the render_js_updates method, but whenever a new client connects you can use this method to send an initial full snapshot of the current state of the doc. Again, this only needs to be used if you decide to keep one domsync.Document instance for all users, as opposed to one domsync.Document for each user. If you use domsync.domsync_server.DomsyncServer, you don’t need to deal with this method because the server maintains one domsync.Document for each client and send updates behind the scenes automatically anyways. You only need to deal with this method if you decide to use your own server.

Returns: Javascript code containnig the full current state of the document.
Return type: str

render_js_updates()#

Returns the Javascript code changes that accummulated in the internal buffer of the domsync.Document due to any manipulations since the last call to this function. This is the method for generating the Javascript code updates that can be sent to the client. domsync.domsync_server.DomsyncServer uses this behind the scenes, so you only need to deal with this function if you want to use your own server.

Returns: the Javascript code generated since the last call to this function.
Return type: str