mirror of
https://github.com/rabbibotton/clog.git
synced 2025-12-15 15:00:24 -08:00
301 lines
10 KiB
Markdown
Vendored
301 lines
10 KiB
Markdown
Vendored
# CLOG - The Common Lisp Omnificent GUI
|
|
|
|
## David Botton <david@botton.com>
|
|
|
|
### License BSD 3-Clause License
|
|
|
|
- [Learn to program Common Lisp and CLOG here - LEARN.md](LEARN.md)
|
|
|
|
- [Video of CLOG Builder in action](https://youtu.be/CgTJMxsz3EY)
|
|
|
|
---
|
|
|
|
|
|
|
|
The Common Lisp Omnificent GUI, CLOG for short, uses web technology to
|
|
produce graphical user interfaces for applications locally or remotely.
|
|
CLOG can take the place, or work alongside, most cross-platform GUI
|
|
frameworks and website frameworks. The CLOG package starts up the
|
|
connectivity to the browser or other websocket client (often a browser
|
|
embedded in a native application.)
|
|
|
|
- [CLOG - Reference Manual](https://rabbibotton.github.io/clog/clog-manual.html)
|
|
|
|
STATUS: CLOG and CLOG Builder 2.0 released.
|
|
|
|
CLOG is actually based on GNOGA, a framework I wrote for Ada in 2013
|
|
and used in commercial production code for the last 10+ years. CLOG
|
|
itself is already used in commerical products, corporate websites,
|
|
and other opensource projects.
|
|
|
|
CLOG is being actively extended, however the core API is stable and proven,
|
|
the CLOG Builder is rich in features. Check the github discussion boards for
|
|
the latest on the project.
|
|
|
|
Consider sponsoring work on CLOG at https://github.com/sponsors/rabbibotton
|
|
|
|
Some potential applications for CLOG:
|
|
|
|
* Cross-platform GUIs and Reports
|
|
* Secure websites and complex interactive web applications
|
|
* Desktop buisiness software (CLOG Runs native on Windows, Mac and Linux)
|
|
* Mobile software (CLOG Runs native on Android and iOS)
|
|
* Massive multiplayer online games
|
|
* Monitoring software for embedded systems
|
|
* A fun way to teach programming and advanced multi-tasking
|
|
parallel programming techniques. (CLOG is a parallel GUI)
|
|
* And the list goes on
|
|
|
|
The key to CLOG is the relationship it forms with a browser window
|
|
or browser control compiled to native code. CLOG uses websockets
|
|
for communications and the browser to render a GUI that maintains
|
|
an active soft realtime connection. For most CLOG applications all
|
|
programming logic, events and decisions are done on the server
|
|
which can be local, or remote over the web.
|
|
|
|
CLOG is developed with ECL, CCL and SBCL, it is tested fairly
|
|
regulary on Linux, Windows, Android, Rasperry Pi, and Mac. It
|
|
is also know to work with the commercial Common Lisps as well.
|
|
|
|
To install CLOG - install Common Lisp:
|
|
|
|
* [Install Common-Lisp for MacOS](MACOS.md)
|
|
* [Install Common-Lisp for Linux](https://lisp-lang.org/learn/getting-started/)
|
|
* [Install Common-Lisp For Android (Termux)](ANDROID-TERMUX.md)
|
|
* [Install Common-Lisp for Win64](WINDOWS.md)
|
|
|
|
For **Windows** users there is an easy install for full CL and CLOG -
|
|
https://github.com/rabbibotton/clog/releases/download/v2.0/clog2.0-win64.zip
|
|
Unzip, double click make.bat and then drag the resulting builder.exe to your
|
|
application bar or double click. Update regularly by running update.bat
|
|
If you change directories you need to run make.bat or update.bat
|
|
|
|
CLOG is in QuickLisp (ql:quickload :clog), however one should
|
|
add the UltraLisp distribution as QuickLisp is updated very
|
|
infrequenty (see below).
|
|
|
|
However for the bleeding edge version and bug fixes clone
|
|
CLOG into ~/common-lisp or a findable source directory, i.e.
|
|
[ ``(push #P"path/to/dir/of/projects" ql:*local-project-directories*)`` ]
|
|
|
|
For git (you also need the clog builder plugins clog-ace and clog-terminal
|
|
for the builder):
|
|
|
|
```
|
|
cd ~/common-lisp
|
|
git clone https://github.com/rabbibotton/clog.git
|
|
git clone https://github.com/rabbibotton/clog-ace.git
|
|
git clone https://github.com/rabbibotton/clog-terminal.git
|
|
```
|
|
For now you should also clone my branch of fast-websockets as the maintainers
|
|
version is broken for larger files so even if using UltraLisp:
|
|
|
|
```
|
|
git clone https://github.com/rabbibotton/fast-websocket.git
|
|
```
|
|
|
|
Update git clones with:
|
|
|
|
```
|
|
git pull
|
|
```
|
|
|
|
To add UltraLisp to QuickLisp:
|
|
|
|
```
|
|
(ql-dist:install-dist "http://dist.ultralisp.org/"
|
|
:prompt nil)
|
|
```
|
|
|
|
You still need to often update the UltraLisp and QuickLisp distros with:
|
|
|
|
```
|
|
(ql:update-all-dists)
|
|
```
|
|
|
|
To get started load CLOG and then can load and run the builder:
|
|
|
|
```
|
|
(ql:quickload :clog)
|
|
(ql:quickload :clog/tools)
|
|
(clog-tools:clog-builder)
|
|
|
|
```
|
|
|
|
A list of plugins for CLOG are available at -
|
|
https://ultralisp.org/tags/clog-plugin/
|
|
|
|
1. Start emacs then M-x slime (or just run sbcl at the command line or use the
|
|
CLOG Buider REPL Tools -> CLOG Builder Repl)
|
|
2. In the REPL, run:
|
|
|
|
```
|
|
CL-USER> (ql:quickload :clog) ; if not already loaded
|
|
CL-USER> (clog:run-tutorial 1)
|
|
```
|
|
|
|
Tip for Windows WSL linux user. Install "sudo apt install xdg-utils" to
|
|
install xdg-open so that run-tutorial uses the windows browser.
|
|
|
|
To see where the source, tutorial and demo files are:
|
|
|
|
```
|
|
CL-USER> (clog:clog-install-dir)
|
|
```
|
|
|
|
You can the run the demos with:
|
|
|
|
```
|
|
CL-USER> (clog:run-demo 1)
|
|
```
|
|
|
|
The CLOG Builder tool can be run with:
|
|
|
|
```
|
|
CL-USER> (ql:quickload :clog/tools)
|
|
CL-USER> (clog-tools:clog-builder)
|
|
```
|
|
|
|
You can also open a "clog-repl" browser window to play
|
|
from the common-lisp repl:
|
|
|
|
```
|
|
CL-USER> (in-package clog-user)
|
|
CLOG-USER> (clog-repl)
|
|
CLOG-USER> (setf (background-color *body*) "beige")
|
|
CLOG-USER> (create-div *body* :content "Hello World!")
|
|
```
|
|
|
|
The clog-repl URL is http://127.0.0.1:8080/repl ``*body*`` will always refer
|
|
to the last access of that URL.
|
|
|
|
To open a browser with the CLOG manual (or in the builder it is under Help):
|
|
|
|
```
|
|
CL-USER> (clog:open-manual)
|
|
```
|
|
|
|
Work your way through the tutorials. You will see how quick and easy it is
|
|
to be a CLOGer.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Here is a very simple sample CLOG app (from Tutorial 1):
|
|
|
|
```lisp
|
|
(defpackage #:clog-user ; Setup a package for our work to exist in
|
|
(:use #:cl #:clog) ; Use the Common Lisp language and CLOG
|
|
(:export start-tutorial)) ; Export as public the start-tutorial function
|
|
|
|
(in-package :clog-user) ; Tell the "reader" we are in the clog-user package
|
|
|
|
|
|
;; Define our CLOG application
|
|
(defun on-new-window (body) ; Define the function called on-new-window
|
|
"On-new-window handler." ; Optional docstring to describe function
|
|
|
|
(let ((hello-element ; hello-element is a local variable that
|
|
; will be bound to our new CLOG-Element
|
|
|
|
;; This application simply creates a CLOG-Element as a child to the
|
|
;; CLOG-body object in the browser window.
|
|
|
|
;; A CLOG-Element represents a block of HTML (we will later see ways to
|
|
;; directly create buttons and all sorts of HTML elements in more
|
|
;; lisp-like ways with no knowledge of HTML or JavaScript.
|
|
(create-child body "<h1>Hello World! (click me!)</h1>")))
|
|
|
|
(set-on-click hello-element ; Now we set a function to handle clicks
|
|
(lambda (obj) ; In this case we use an anonymous function
|
|
(setf (color hello-element) "green"))))))
|
|
|
|
;; To see all the events one can set and the many properties and styles that
|
|
;; exist, refer to the CLOG manual or the file clog-element.lisp
|
|
|
|
|
|
(defun start-tutorial () ; Define the function called start-tutorial
|
|
"Start tutorial." ; Optional docstring to describe function
|
|
|
|
;; Initialize the CLOG system
|
|
(initialize #'on-new-window)
|
|
;; Set the function on-new-window to execute
|
|
;; every time a browser connection to our app.
|
|
;; #' tells Common Lisp to pass the function
|
|
;; to intialize and not to execute it.
|
|
|
|
|
|
;; Open a browser to http://12.0.0.1:8080 - the default for CLOG apps
|
|
(open-browser))
|
|
```
|
|
|
|
Other samples of CLOG on the web:
|
|
|
|
- [CLOG + cl-collider](https://github.com/byulparan/clog-collider-experience)
|
|
- [CLOG on iOS and Android](https://www.reddit.com/r/lisp/comments/tl46of/would_it_be_cool_to_run_a_clog_app_on_mobile_you/)
|
|
- [Learn CLOG Dashboard](https://gist.github.com/mmontone/3a5a8a57675750e99ffb7fa64f40bc39#file-clog-learn-lisp)
|
|
- [CLOGPower.com](http://clogpower.com)
|
|
|
|
Get started learning CLOG and the CLOG Builder with
|
|
* [Learn CLOG](LEARN.md)
|
|
|
|
Tool Summary
|
|
|
|
- clog-builder - Rapid visual interactive development for Web and GUIs
|
|
- clog-db-admin - SQLite3 admin tool
|
|
|
|
High Order Extensions to CLOG
|
|
|
|
- clog-gui - Desktop over the web
|
|
- Menus
|
|
- Windowing system
|
|
- Modal windows, Keep-on-top windows
|
|
- File Load / Save dialogs
|
|
- Alert, Input and Confirmation dialogs
|
|
- Form dialogs
|
|
|
|
- clog-web - Webpage creation
|
|
- Auto column layouts
|
|
- 12 Point Grid System layouts
|
|
- Content containers
|
|
- Panels
|
|
- Sidebar menus
|
|
- Compositor containers
|
|
- Menus
|
|
- Alerts
|
|
|
|
- clog-web-site - Instant themed websites with plugins:
|
|
- clog-web-page - create a theme based page
|
|
- clog-web-dbi - database driven websites (uses clog-auth)
|
|
- clog-web-forms - Instant web forms
|
|
- clog-web-themes - basic themes for clog based websites
|
|
- clog-web-content - database driven content,tags, comments (in progress)
|
|
- clog-web-blog - instant blogs (in progress)
|
|
- clog-web-cart - instant shopping carts (future)
|
|
|
|
- clog-panels - Quick application layouts
|
|
|
|
- clog-presentations - bi-directional linking of Lisp Objects and CLOG
|
|
Objects
|
|
|
|
- clog-jquery - DOM queries
|
|
|
|
- clog-data - Move data to and from groups of controls
|
|
- SQL writer helpers for basic SQL
|
|
- CLOG-Database - Database control for CLOG Builder
|
|
- CLOG-One-Row - One row at a time table access auto
|
|
binds to controls in CLOG Builder
|
|
- CLOG-Lookup - Version of the select control (dropdown and listbox)
|
|
that are database connected
|
|
- CLOG-DB-Table - Version of html table that are database connected
|
|
|
|
- clog-auth - Authentication and authorization framework
|
|
|
|
- clog-plugin - Custom Control Plug-in template for Builder and CLOG
|