PyWebIO uses a server-client architecture, the server executes task code, and interacts with the client (that is, the user browser) through the network. This section introduce the protocol specification for the communication between PyWebIO server and client.
There are two communication methods between server and client: WebSocket and Http.
When using Tornado or aiohttp backend, the server and client communicate through WebSocket, when using Flask or Django backend, the server and client communicate through Http.
WebSocket communication
The server and the client send json-serialized message through WebSocket connection
Http communication
- The client polls the backend through Http GET requests, and the backend returns a list of PyWebIO messages serialized in json
- When the user submits the form or clicks the button, the client submits data to the backend through Http POST request
In the following, the data sent by the server to the client is called command, and the data sent by the client to the server is called event.
The following describes the format of command and event
Command is sent by the server to the client. The basic format of command is:
{
"command": ""
"task_id": ""
"spec": {}
}
Each fields are described as follows:
command
: command nametask_id
: Id of the task that send the commandspec
: the data of the command, which is different depending on the command name
Note that: the arguments shown above are merely the same with the parameters of corresponding PyWebIO functions, but there are some differences.
The following describes the spec
fields of different commands:
Show a form in user's browser.
fields ofspec
Field | Required | Type | Description |
---|---|---|---|
label | False | str | Title of the form |
inputs | True | list | Input items |
cancelable | False | bool | Whether the form can be cancelled。 If cancelable=True, a “Cancel” button will be displayed at the bottom of the form. A from_cancel event is triggered after the user clicks the cancel button. |
The inputs
field is a list of input items, each input item is a dict
, the fields of the item are as follows:
- label: Label of input field, required.
- type: Input type, required.
- name: Identifier of the input field, required.
- onchange: bool, whether to push input value when input change
- onbulr: bool, whether to push input value when input field onblur
- auto_focus: Set focus automatically. At most one item of
auto_focus
can be true in the input item list - help_text: Help text for the input
- Additional HTML attribute of the input element
- Other attributes of different input types
Currently supported type
are:
- text: Plain text input
- number: Number input
- password: Password input
- checkbox: Checkbox
- radio: Radio
- select: Drop-down selection
- textarea: Multi-line text input
- file: File uploading
- actions: Actions selection.
Correspondence between different input types and html input elements:
- text: input[type=text]
- number: input[type=number]
- float: input[type=text], and transform input value to float
- password: input[type=password]
- checkbox: input[type=checkbox]
- radio: input[type=radio]
- select: select https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select
- textarea: textarea https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/textarea
- file: input[type=file]
- actions: button[type=submit] https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/button
Unique attributes of different input types:
- text,number,password:
- action: Display a button on the right of the input field. The format of
action
is{label: button label, callback_id: button click callback id}
- action: Display a button on the right of the input field. The format of
- textarea:
- code: Codemirror options or boolean, same as
code
parameter ofpywebio.input.textarea
- code: Codemirror options or boolean, same as
- select:
- options:
{label:, value: , [selected:,] [disabled:]}
- options:
- checkbox:
- options:
{label:, value: , [selected:,] [disabled:]}
- inline
- options:
- radio:
- options:
{label:, value: , [selected:,] [disabled:]}
- inline
- options:
- actions
- buttons:
{label:, value:, [type: 'submit'/'reset'/'cancel'], [disabled:], [color:]}
.
- buttons:
file:
- multiple: Whether to allow upload multiple files.
- max_size: The maximum size of a single file, in bytes.
- max_total_size: The maximum size of all files, in bytes.
slider
- min_value: The minimum permitted value.
- max_value: The maximum permitted value.
- step: The stepping interval.
- float: If need return a float value
Update the input item, you can update the spec
of the input item of the currently displayed form
The spec
fields of update_input
commands:
- target_name: str The name of the target input item.
- target_value: str, optional. Used to filter item in checkbox, radio
- attributes: dist, fields need to be updated
- valid_status: When it is bool, it means setting the state of the input value, pass/fail; when it is 0, it means clear the valid_status flag
- value: Set the value of the item
- label
- placeholder
- invalid_feedback
- valid_feedback
- help_text
- options: only available in checkbox, radio and select type
- other fields of item's
spec
// not support theinline
field
Indicates that the server has closed the connection. spec
of the command is empty.
Send current session id to client, used to reconnect to server (Only available in websocket connection). spec
of the command is session id.
Destroy the current form. spec
of the command is empty.
Note: The form will not be automatically destroyed after it is submitted, it needs to be explicitly destroyed using this command
Output content
The spec
fields of output
commands:
- type: content type
- style: str, Additional css style
- container_selector: The css selector of output widget's content slot. If empty(default), use widget self as container
- container_dom_id: The dom id need to be set to output widget's content slot.
- scope: str, CSS selector of the output container. If multiple containers are matched, the content will be output to every matched container
- position: int, see
scope - User manual <scope_param>
- click_callback_id:
- Other attributes of different types
container_selector
and container_dom_id
is used to implement output context manager.
Unique attributes of different types:
- type: markdown
- content: str
- options: dict, marked.js options
- sanitize: bool, Whether to enable a XSS sanitizer for HTML
- type: html
- content: str
- sanitize: bool, Whether to enable a XSS sanitizer for HTML
- type: text
- content: str
- inline: bool, Use text as an inline element (no line break at the end of the text)
- type: buttons
- callback_id:
- buttons:[ {value:, label:, [color:], [disabled:]},...]
- small: bool, Whether to enable small button
- group: bool, Whether to group the buttons together
- link: bool, Whether to make button seem as link.
- outline: bool, Whether enable outline style.
- type: file
- name: File name when downloading
- content: File content with base64 encoded
- type: table
- data: Table data, which is a two-dimensional list, the first row is table header.
- span: cell span info. Format: {"[row id],[col id]": {"row":row span, "col":col span }}
- type: pin
- input: input spec, same as the item of
input_group.inputs
- input: input spec, same as the item of
- type: scope
- dom_id: the DOM id need to be set to this widget
- contents list: list of output spec
- type: scrollable
- contents:
- min_height:
- max_height:
- keep_bottom:
- border:
- type: tabs
- tabs:
- type: custom_widget
- template:
- data:
The spec
fields of pin_value
commands:
- name
The spec
fields of pin_update
commands:
- name
- attributes: dist, fields need to be updated
The spec
fields of pin_wait
commands:
- names: list,
- timeout: int,
set a callback which is invoked when the value of pin widget is changed
The spec
fields of pin_onchange
commands:
- name: string
- callback_id: string, if
None
, not set callback - clear: bool
Show popup
The spec
fields of popup
commands:
- title
- content
- size:
large
,normal
,small
- implicit_close
- closable
- dom_id: DOM id of popup container element
Show a notification message
The spec
fields of popup
commands:
- content
- duration
- position: 'left' / 'center' / 'right'
- color: hexadecimal color value starting with '#'
- callback_id
Close the current popup window.
spec
of the command is empty.
Config the environment of current session.
The spec
fields of set_env
commands:
- title (str)
- output_animation (bool)
- auto_scroll_bottom (bool)
- http_pull_interval (int)
- input_panel_fixed (bool)
- input_panel_min_height (int)
- input_panel_init_height (int)
- input_auto_focus (bool)
Output control
The spec
fields of output_ctl
commands:
set_scope: scope name
- container: Specify css selector to the parent scope of target scope.
- position: int, The index where this scope is created in the parent scope.
if_exist: What to do when the specified scope already exists:
- null: Do nothing
- `'remove'`: Remove the old scope first and then create a new one
- `'clear'`: Just clear the contents of the old scope, but don’t create a new scope
- clear: css selector of the scope need to clear
- clear_before
- clear_after
- clear_range:[,]
- scroll_to
- position: top/middle/bottom, Where to place the scope in the visible area of the page
- remove: Remove the specified scope
run javascript code in user's browser
The spec
fields of run_script
commands:
- code: str, code
- args: dict, Local variables passed to js code
- eval: bool, whether to submit the return value of javascript code
Send file to user
The spec
fields of download
commands:
- name: str, File name when downloading
- content: str, File content in base64 encoding.
Event is sent by the client to the server. The basic format of event is:
{
event: event name
task_id: ""
data: object/str
}
The data
field is the data carried by the event, and its content varies according to the event. The data
field of different events is as follows:
Triggered when the form changes
- event_name: Current available value is
'blur'
, which indicates that the input item loses focus - name: name of input item
- value: value of input item
note: checkbox and radio do not generate blur events
Triggered when the user clicks the button in the page
In the callback
event, task_id
is the callback_id
field of the button
; The data
of the event is the value
of the button that was clicked
Triggered when the user submits the form
The data
of the event is a dict, whose key is the name of the input item, and whose value is the value of the input item.
Cancel input form
The data
of the event is None
submit data from js. It's a common event to submit data to backend.
The data
of the event is the data need to submit