z-shell / zui

⚙️ The Rapid Application Development textual user interface library for Zsh.

❮ ZI ❯ - ⬢ ZUI

ZUI – CGI+DHTML-like User Interface Library for Zsh / ZCurses

This is a RAD (Rapid Application Development) textual user interface library for Zsh. It in many aspects resembles typical CGI+(D)HTML setup. There are:

• generators ran on "server" side (basic Zshell-code that is just generating text!),
• event loop that turns the generated text into document with active elements (buttons, anchors, toggle buttons, text fields, list boxes),
• mechanism to regenerate document parts from the original generators.

So, a Zshell code generates text. It is then turned into document with hyperlinks. DHTML-like calls are possible that will regenerate document parts on the fly. Page can be also reloaded with input data, just like an HTML page.

A voiced video tutorial shows how to create an application – Nmap network scanner frontend.

See also ZSTYLES

Hello World

# Started from Zle or from command line

-zui_std_cleanup deserialize:"zui-demo-hello-world"
-zui_std_init app:"zui-demo-hello-world" app_name:"ZUI Hello World"
emulate -LR zsh -o extendedglob -o typesetsilent -o warncreateglobal
-zui_std_init2 # after emulate -LR

-zui_std_store_default_app_config b:border 1

demo_generator_A() {
    local mod="$1" ice="$2"
    # Content, no hyper-links
    reply=( "Hello World from ${ZUI[YELLOW]}ZUI${ZUI[FMT_END]}! Module $mod, instance $ice." )
    # Non-selectable lines   Hops to jump with [ and ]   Local anchors
    reply2=( )               reply3=( 1 )                reply4=( )
}

## Start application ##
zui-event-loop 1:demo_generator_A

-zui_std_cleanup serialize

Other example which uses list-box: zui-demo-list-box

The API is described at the wiki.

Installation

The plugin is "standalone", which means that only sourcing it is needed. To install, unpack zui somewhere and add to zshrc:

source {where-zui-is}/zui.plugin.zsh

If using a plugin manager, then ZI is recommended, but you can use any other too, and also install with Oh My Zsh (by copying directory to ~/.oh-my-zsh/custom/plugins).

ZI

Add zi load z-shell/zui to your .zshrc file. ZI will handle the rest automatically the next time you start zsh. To update (i.e. to pull from origin) issue zi update z-shell/zui.

Antigen

Add antigen bundle z-shell/zui to your .zshrc file. Antigen will handle cloning the plugin for you automatically the next time you start zsh.

Oh-My-Zsh

1. cd ~/.oh-my-zsh/custom/plugins
2. git clone [email protected]:z-shell/zui.git
3. Add zui to your plugin list

Zgen

Add zgen load z-shell/zui to your .zshrc file in the same place you're doing your other zgen load calls in.

zui's Issues

on-the-fly regeneration ignores reply5

# TODO: on-the-fly regeneration ignores reply5

zui/lib/stdlib.lzui

Line 952 in fae4237

#

TaskBoard

TaskBoard

• Requires update to zsh plugin standard.
• Map Output.

[bug]: ZUI Functions are not added to `$fpath` when used with Oh My Zsh (OMZ)

Environment

Ubuntu 24.04 on Windows 10 WSL using zsh 5.9 with Oh My Zsh plus ZBrowse and ZUI plugins

Reproduction steps

1. Install ZBrowse to the OMZ custom plugins directory per the ZBrowse installation isntructions for OMZ
2. Install ZUI to the OMZ custom plugins directory according to the ZUI installation isntructions for OMZ
3. Add zbrowse and zui to OMZ's plugins array in .zshrc
4. Reload the shell or run omz reload
5. Press crtl+b to launch ZBrowse

Note: I tested this with AND without other OMZ plugins being loaded and the behaviour was the same.

Expected behavior

1. pressing ctrl+b will launch ZBrowse

Current behavior

Pressing ctrl+b to launch ZBrowse results in the following error:

zbrowse:482: zui-event-loop: function definition file not found

Code snippet

From .zshrc

# Which plugins would you like to load?
# Standard plugins can be found in $ZSH/plugins/
# Custom plugins may be added to $ZSH_CUSTOM/plugins/
# Example format: plugins=(rails git textmate ruby lighthouse)
# Add wisely, as too many plugins slow down shell startup.
plugins=(
    zui
    zbrowse
)

Additional information

First of all, I realize this may very well be an issue with Oh My Zsh. If that is the case, please let me know and I will go there for resolution. I am not a zsh expert and my experience is limited to using it as my shell with OMZ.

Workaround:

A workaround for this issue is to load ZUI directly, per the Standalone installation instuctions. Placing

source {where-zui-is}/zui.plugin.zsh

in my .zshrc file yields a successful result.

Details:

When loading ZUI as a plugin via OMZ, ZUI's functions directory ($ZUI_REPO_DIR/functions) is not added to the fpath array.
The failure appears to happen due to the following code block (zui.plugin.zsh lines 26-31):

# Update FPATH if:
# 1. Not loading with ZI
# 2. Not having fpath already updated (that would equal: using other plugin manager)
if [[ -z "$ZI_CUR_PLUGIN" && "${fpath[(r)$ZUI_REPO_DIR]}" != $ZUI_REPO_DIR ]]; then
    fpath+=( "$ZUI_REPO_DIR/functions" )
fi

It appears that OMZ is adding $ZUI_REPO_DIR to fpath before it actually loads the plugin. This subsequently causes test no. 2,

"${fpath[(r)$ZUI_REPO_DIR]}" != $ZUI_REPO_DIR`

to fail, and $ZUI_REPO_DIR/functions does not get added to fpath.

This theory is borne out by the fact that bypassing OMZ's plugin loading, by sourcing ZUI directly in .zshrc, solves the problem.

Resolution:

It seems that OMZ automatically adds each plugin directory to fpath before the plugin is actually loaded. This, of
course, clashes with ZUI's method of determining if its function path should be added to fpath for non-ZI plugin managers.

I notice that ZBrowse does not use the same method to test if its functions directory should be added to fpath. Perhaps ZUI could be modified to use the same method, or include a check specifically based on the way Oh My Zsh's deals with plugin directories being added to fpath.

FYI:

The Code of Conduct link is dead

Self-service

• I'd be willing to address this documentation request myself.

Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines.

Are you familiar with the Contributor Covenant Code of Conduct?

• I have read the Contributor Covenant Code of Conduct.

Contact Details

No response