Bash tutorial
Bash can be used to build standalone web apps and dashboards or add web UI to existing scripts, jobs.
Requirements:
- Bash, Zsh on Linux or macOS. Windows is not supported.
pglet.sh
#
Installing pglet.sh
script contains Bash functions to work with Pglet and could be dot-sourced in your scripts using Pglet.
To download pglet.sh
run the following command:
During the first run of pglet.sh
Pglet binary will be downloaded to $HOME/.pglet/bin
directory.
If you want to install Pglet binary into a custom directory you can define PGLET_INSTALL_DIR
environment variable. For example to install Pglet binary to /usr/local/bin
directory run:
note
Custom installation directory must be in $PATH
.
#
Creating a pagePglet allows you creating shared and app pages.
Shared page is like a singleton: many programs can connect and author the same page and all web users connecting to a page see and interact with the same content. Shared pages are useful for developing local tools, web dashboards, progress reports, distributed processes visualization, etc.
App page creates for each web user a new session with its own content. In your program you define a "handler" method which is invoked for every new session. App pages are used for creating multi-user web apps.
OK, this is a minimal "Hello world" Pglet page running in a local mode:
When you run this script a new browser window should popup with the greeting:

pglet_page
function creates a page, if it doesn't exist, with hello
name and opens connection. An opened connection ID is stored in a PGLET_CONNECTION_ID
variable.
pglet_send
cmdlet sends commands to open Pglet connection. You use add, set, get, clean and remove commands to update and query page contents.
An app won't wait for any input and should exit. Now, if you run the same hello.sh
script for the second time another "Hello, world!" message will be added to the page. This is because the page is stateful. Its contents can be updated at any time by any number of scripts, multiple scripts can connect and update the same page simultanously.
If you need a clean page on every start of the program use clean
command:
#
Getting user inputPglet provides a number of controls for building forms: Textbox, Checkbox, Dropdown, Button.
Let's ask a user for a name:
#
Handling eventsWhen you click "Say hello" button on the form above nothing will happen in our program though Button
control itself emits "click" event each time it's pressed/clicked. The event is just not handled.
In Bash you use event loop to handle control events.
#
Event loopOnce the form is rendered use pglet_wait_event
function in a loop to receive all page events triggered by a user:
Notice how IDs of the added textbox and button are saved, so we can refer to these controls later.
pglet_wait_event
stores event details into PGLET_EVENT_TARGET
, PGLET_EVENT_NAME
and PGLET_EVENT_DATA
variables. We are interested in click
events coming from the button (PGLET_EVENT_TARGET
is control's ID). Next, we use get
command to read value
property of textbox control, clean
the page, output greeting and leave the program.
#
Multi-user appsIn multi-user Pglet apps every user has a unique session with its own page contents. To start an app page you use pglet_app
function which takes a reference to a session handling function. The handler function is called in a new sub-shell for every new user connected. The program stays blocked on pglet_app
while constantly waiting for new user connections.
Below is a minimal Pglet multi-user app in Bash:
Now, a multi-user version of greeter app could look like the following:
#
Getting apps and pages to the WebUp until this moment you've been running all tutotial samples on your computer with a local Pglet server instance running in the background.
With literarily no changes to the code Pglet allows to make your program accessible from the web. This could be an admin app for managing backend services, or a dashboard with server metrics, or an application prototype you are sharing with your colleagues or clients.
In contrast to a classic deployment you are not packaging your program and it's not going anywhere. It continues to run on the same computer where it was built or cloned while UI is "streamed" to Pglet service and available via https://app.pglet.io/public/{your-app-name}
URL.
So, to make your greeter app available on the web add PGLET_WEB=true
variable before either 'pglet_pageor
pglet_app` call:
As it's going to a public service the page name must be unique. One way is to prepend page name with "account" or "namespace", for example:
or just omit page name, so it will be randomly generated. Look at this article to understand how page naming works.
#
Escaping command parametersPglet command must be written in a single line, therefore new line symbols (CR
) must be replaced with \n
. If a command argument value contains spaces it must be surrounded with single or double quotes.
For example, you want to add a new text
control with the following contents having new lines, single and double quotes:
Command should look like:
Notice, new lines {CR}
are replaced with \n
, double quotes "
replaced with \"
.
The value in double quotes can have unescaped single quotes inside and vice versa, for example:
or
pglet.sh
includes helper functions to help you with strings escaping:
escape_sq_str()
- takes string in$1
argument and escapes new lines and single quotes.escape_dq_str()
- takes string in$1
argument and escapes new lines and double quotes.escape_sq_cmd()
- takes command with arguments, runs it and escapes new lines and single quotes in command result.escape_dq_cmd()
- takes command with arguments, runs it and escapes new lines and double quotes in command result.
Example 1:
Example 2:
pglet.sh
reference#
pglet_page
#
Creates a shared page if not exists and opens a new connection.
Parameters:
$1
(optional) - the name of Pglet page. Random name will be generated if this parameter left blank.
Variables:
PGLET_WEB=true
- makes the app available as public at pglet.io service or a self-hosted Pglet server.PGLET_SERVER=<url>
- connects to the app on a self-hosted Pglet server.PGLET_TOKEN=<token>
- authentication token for pglet.io service or a self-hosted Pglet server.PGLET_NO_WINDOW=true
- do not open browser window.
pglet_app
#
Creates an application page if not exists and opens a new connection.
Parameters:
$1
(optional) - the name of Pglet page. Random name will be generated if this parameter left blank.$2
- session handler function.
Variables:
PGLET_WEB=true
- makes the app available as public at pglet.io service or a self-hosted Pglet server.PGLET_SERVER=<url>
- connects to the app on a self-hosted Pglet server.PGLET_TOKEN=<token>
- authentication token for pglet.io service or a self-hosted Pglet server.PGLET_NO_WINDOW=true
- do not open browser window.
pglet_send
#
Sends commands to a Pglet connection.
Parameters:
$1
- command text or connection ID.$2
(optional) - command text (if connection ID is specified in$1
).
For example, setting page title:
pglet_wait_event
#
Blocks until a user generated event is received.
Stores event details into the following variables:
PGLET_EVENT_TARGET
- ID of control triggered event.PGLET_EVENT_NAME
- event name, for example "click".PGLET_EVENT_DATA
- additional data attached to the event. Button control hasdata
property which supplies additional event data.
pglet_add
#
Shortcut for add
command, for example:
pglet_set
#
Shortcut for set
command, for example:
pglet_set_value
#
Updates value
property of a control, for example:
pglet_get_value
#
Reads value
property of a control, for example:
pglet_show
#
Sets visible
property of a control to true
, for example:
pglet_hide
#
Sets visible
property of a control to false
, for example:
pglet_enable
#
Sets disabled
property of a control to false
, for example:
pglet_disable
#
Sets disabled
property of a control to true
, for example:
pglet_clean
#
Cleans children collection of a control, but leaves control itself.
For example, to clean the contents of the entire page:
pglet_remove
#
Removes a control and all its children, for example:
escape_sq_str
#
Takes string in $1
argument and escapes new lines and single quotes.
For example, running the following script:
will output:
escape_dq_str
#
Takes string in $1
argument and escapes new lines and double quotes.
For example, running the following script:
will output:
escape_sq_cmd
#
Executes command $@
and then escapes new lines and single quotes in the command result.
For example, running the following script:
will output:
escape_dq_cmd
#
Executes command $@
and then escapes new lines and double quotes in the command result.
For example, running the following script:
will output: