Python Classes and Extensions of WDOM
=====================================

Generating new elements by `document.createElement` every time is quite mess.
So WDOM's `wdom.tag` module provides simple tag classes usually used.

By using tag classes, the previous example can be written as:

.. literalinclude:: samples/wdom1.py

Instead of using `document.createElement`, in the above example is using
`H1` class and `Input` class to generate h1 element and input element.
Furthermore, `MyElement` class inherits `Div` class. Its instance is
rendered as `div` element, or `<div>` tag on a browser. These instances are
same as instances generated by `document.createElement` method.

Names of pre-defined classes on `wdom.tag` module are same as related tag
names, starting with upper-case and followed by lower-case.
For example, `<button>` tag is `Button` class, `<br>` tag is `Br` class,
and `<textarea>` tag is `Textarea`.

Actual HTML strings can be obtained by `html` property of each elements.
For example, `print(MyElement().html)` shows

```html
<div rimo_id="..."><input rimo_id="..."><h1 rimo_id="...">Hello, WDOM</h1></div>
```

`rimo_id` attribute is used internally.
If you want to omit it for tests, use `html_noid` property instead

```python
print(MyElement().html_noid)
# -> <div><input><h1>Hello, WDOM</h1></div>
```

Append to Parent Node
---------------------

By using `parent` argument of constructor, newly generated elements will be
automatically appended to the parent node.
Using this, the above example can be written as:

.. literalinclude:: samples/wdom2.py

At the line `self.h1 = H1(parent=self)`, new `h1` element is automatically
appended to `self` as its child node.

Append Child Nodes
------------------

In the other way, child nodes can be appended on generation.

.. literalinclude:: samples/wdom3.py

At the `self.h1 = H1('Hello, WDOM', parent=self)`, the first argument is
converted to Text Node and appended to the newly generated `h1` element.
With multiple arguments, more than one child node can be appended, like
`H1(H2(), P(), ...)`.

Initialization with Attributes
------------------------------

Attributes are also able to be defined with keyword arguments on the
constructor.

.. literalinclude:: samples/wdom4.py

`class` is a python's keyword, so use `class_` (trailing underscore) instead.

.. literalinclude:: samples/wdom5.py

Default Class Attribute
-----------------------

User-defined class can have default class attributes.

.. literalinclude:: samples/wdom6.py

`class_` class-variable is added to the instance. This attribute cannot be
removed at its instance and it is inherited to the subclasses. If you don't want
to inherit parent's class attributes, add `inherit_class = False` as a class
variable.

Shortcut of Class Definition
----------------------------

Defining lots of similar classes by `class` statement is quite mess.
WDOM provides `wdom.tag.NewTagClass` function to make new user-defined
classes.

`MyButton` class and `DefaultButton` class defined in the above example can
be defined simply by using `NewTagClass` function as below:

.. literalinclude:: samples/wdom7.py

The first argument is a name of new class, the second is a tag name, the third
is a base class, and the firth and other keyword arguments are class-variables
of the new class.
To inherit multiple classes, use tuple at the third argument.

These features are not DOM standard and specially defined for WDOM.

Execute JavaScript on Browser
-----------------------------

(to be written)