Metadata-Version: 2.4
Name: WFC
Version: 2.2.0
Summary: The Back-End Part of WebForms Core Technology
Author-email: Elanat <info@elanat.net>
License: MIT
Project-URL: Homepage, https://elanat.net/webforms-core
Project-URL: Repository, https://github.com/webforms-core/WebFormsClasses
Keywords: webforms,webforms-core,wfc,server-driven,server-side,server-oriented,dom,html,ui,web-development
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Description-Content-Type: text/markdown

# WebForms Core

## WFC for Python

**WFC** is the Python implementation of the **WebForms Core Commander**. It provides the `WebForms` class for generating WebForms Core commands from Python server-side applications.

## WebForms Core Architecture

WebForms Core consists of two main parts:

- **Commander** — WebForms classes implemented for different programming languages. Commanders generate WebForms Core commands that describe changes to the HTML document.
- **Executor** — **WebFormsJS**, the client-side JavaScript library that receives and executes those commands in the browser.

The Python `WFC` package provides the **Commander** implementation for Python, while WebFormsJS provides the common browser-side Executor.

The WebFormsJS Executor is loaded into the HTML document:

```xml
<script type="module" src="/static/script/web-forms.js"></script>
```

WebForms Core is a technology developed by [Elanat](https://elanat.net).

## Installation

### Installation via Package

PyPI package:

https://pypi.org/project/WFC/

Install using pip:

```bash
pip install WFC
```

### Download / Copy the File

The WebForms class implementation can also be copied directly into a Python project.

The latest WebFormsJS Executor is available from:

- WebFormsJS on Elanat: https://elanat.net/webforms-js
- WebFormsJS on GitHub: https://github.com/webforms-core/WebFormsJS

# How to Work with WebForms Core in Python

The following example demonstrates how to use WFC with the **Flask** framework.

```python
from flask import Flask, request, render_template_string
from WebForms import WebForms, InputPlace

app = Flask(__name__)

@app.route('/', methods=['GET', 'POST'])
def index():
    if request.method == 'POST' and 'btn_SetBodyValue' in request.form:
        name = request.form['txt_Name']
        background_color = request.form['txt_BackgroundColor']
        font_size = str(request.form['txt_FontSize'])

        form = WebForms()

        form.set_font_size(
            InputPlace.tag('form'),
            font_size + 'px'
        )

        form.set_background_color(
            InputPlace.tag('form'),
            background_color
        )

        form.set_disabled(
            InputPlace.name('btn_SetBodyValue'),
            True
        )

        form.add_tag(
            InputPlace.tag('form'),
            'h3'
        )

        form.set_text(
            InputPlace.tag('h3'),
            f"Welcome {name}!"
        )

        return form.response()

    return render_template_string('''
    <!DOCTYPE html>
    <html>
    <head>
        <title>Using WebForms Core</title>
        <script type="module" src="/static/script/web-forms.js"></script>
    </head>
    <body>
        <form method="post" action="/">
            <label for="txt_Name">Your Name</label>
            <input name="txt_Name" id="txt_Name" type="text">
            <br>

            <label for="txt_FontSize">Set Font Size</label>
            <input
                name="txt_FontSize"
                id="txt_FontSize"
                type="number"
                value="16"
                min="10"
                max="36"
            >
            <br>

            <label for="txt_BackgroundColor">
                Set Background Color
            </label>

            <input
                name="txt_BackgroundColor"
                id="txt_BackgroundColor"
                type="text"
            >
            <br>

            <input
                name="btn_SetBodyValue"
                type="submit"
                value="Click to send data"
            >
        </form>
    </body>
    </html>
    ''')

if __name__ == '__main__':
    app.run(debug=True)
```

## How the Flask Example Works

When the page is requested for the first time, Flask renders and returns the complete HTML page. The page includes the WebFormsJS Executor:

```xml
<script type="module" src="/static/script/web-forms.js"></script>
```

When the form is submitted, the Flask route receives the submitted form data.

If the submit button is included in the request, a `WebForms` instance is created:

```python
form = WebForms()
```

The application then generates WebForms Core commands:

```python
form.set_font_size(
    InputPlace.tag('form'),
    font_size + 'px'
)

form.set_background_color(
    InputPlace.tag('form'),
    background_color
)

form.set_disabled(
    InputPlace.name('btn_SetBodyValue'),
    True
)
```

Additional commands modify the HTML document:

```python
form.add_tag(
    InputPlace.tag('form'),
    'h3'
)

form.set_text(
    InputPlace.tag('h3'),
    f"Welcome {name}!"
)
```

Finally, the generated WebForms Core response is returned:

```python
return form.response()
```

WebFormsJS receives the response and executes the generated commands on the HTML DOM.

If the submit button is not included in the request, the application returns the initial HTML page normally.

This allows the Python server-side application to control the client-side HTML document through WebForms Core commands without requiring JavaScript code for each individual UI operation.

### Sending Commands with the Initial HTML

When WebForms Core commands need to be sent together with the initial HTML document, you can use `export_to_html_comment()` instead of `response()`.

`export_to_html_comment()` embeds the generated WebForms Core commands in an HTML comment. WebFormsJS detects these commands when the HTML document is loaded and executes them in the browser.

For example, a Flask application can generate WebForms Core commands during the initial page load:

```python
from flask import Flask, render_template_string
from WebForms import WebForms, InputPlace

app = Flask(__name__)

@app.route('/')
def index():
    form = WebForms()

    form.set_background_color(
        InputPlace.tag('body'),
        'lightblue'
    )

    return render_template_string(f'''
    <!DOCTYPE html>
    <html>
    <head>
        <title>WebForms Core</title>
        <script type="module" src="/static/script/web-forms.js"></script>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
    </html>
    ''' + form.export_to_html_comment())

if __name__ == '__main__':
    app.run(debug=True)
```

In this case, the generated commands are embedded in the HTML response itself. When WebFormsJS loads, it detects the commands in the HTML comment and executes them on the DOM.

Use `response()` when returning WebForms Core commands as a response to a request. Use `export_to_html_comment()` when the commands need to be included directly in the HTML document, such as during the initial page load.

## Commander and Executor

The `WebForms` class is the **Commander**. It generates WebForms Core commands that describe operations to be performed on the HTML document.

For example:

```python
form = WebForms()

form.add_tag(InputPlace.tag('form'), 'h3')
form.set_text(InputPlace.tag('h3'), 'Hello World!')
form.set_background_color(
    InputPlace.tag('form'),
    'lightblue'
)

return form.response()
```

The Commander does not directly manipulate the browser DOM. It generates the WebForms Core response that is sent to the client.

**WebFormsJS** is the **Executor**. It receives WebForms Core commands from the server and executes them in the browser.

```text
                    WebForms Core
                         │
              ┌──────────┴──────────┐
              │                     │
          Commander              Executor
              │                     │
         Python WFC             WebFormsJS
              │                web-forms.js
              │                     │
     Generates commands ──► Executes commands
                                    │
                                    ▼
                               Browser DOM
```

The **Commander describes what should happen**.

The **Executor performs those commands in the browser**.

WebForms Core uses a **command-driven flow** and a **stateless server architecture**. The same programming model can be used with different programming languages and server-side environments.

WebForms Core is available for programming languages used for web development.

## WebFormsJS

WebFormsJS is the client-side JavaScript **Executor** of WebForms Core.

The latest WebFormsJS Executor is available here:

- WebFormsJS on Elanat: https://elanat.net/webforms-js
- WebFormsJS on GitHub: https://github.com/webforms-core/WebFormsJS

The npm package is also available:

https://www.npmjs.com/package/webformsjs

Install using npm:

```bash
npm install webformsjs
```
