CLOG (Common Lisp Omnificent GUI)

The CLOG tutorial series covers a wide range of topics from basic 'Hello World' to advanced web and graphics integration. Key learning areas include:

• Basics: Closures, parallel events, event targets, and tasking.
• UI Components: Containers, tabs, panels, forms, menus, and drag-and-drop.
• Graphics: Canvas, 2D WebGL, and 3D WebGL.
• Web Integration: Routing, Bootstrap 4, W3.CSS, and using existing HTML.
• Advanced Web: CLOG WEB (local web apps, forms, and routing), database-driven websites (clog-web-dbi, clog-auth, clog-web-content), and instant websites (clog-web-site).
• Extensibility: Creating new plugins from JavaScript components or in Common Lisp.
• Data & State: Local/Session client-side storage and linking Lisp objects to CLOG objects via Presentations.
• Syntax: Using with-clog-create for declarative GUI syntax.

CLOG Builder uses a specific directory structure to provide templates for starting new application projects. When creating a new project, the builder utilizes files from the following locations:

• www/*: Contains static-file directories common to all projects.
• projects/*: Contains specific CLOG Builder templates.
• common/*: Contains general build scripts and files used for initializing new projects.

While CLOG is designed to be robust by leveraging web technologies, developers must design for potential failures.

Connectivity Behavior:

• CLOG can automatically re-establish moderate connectivity interrupts.
• On a single machine, the connection can survive system sleep or suspension.
• Full disconnects are not automatically recovered by the framework; your application design must account for them.

State Management:

• UI State: A snapshot of the current UI state can be taken easily.
• Server State: The persistence of server-side state is dependent on your specific application design.

To build a reliable application, ensure you have a strategy for handling full disconnections and managing state transitions during recovery.

CLOG operates on a client/server architecture using a two-stage communication process:

1. Bootstrap: An initial connection is established via HTTP using an HTML boot page and a JavaScript script.
2. Continuous Communication: Once bootstrapped, the application switches to WebSockets. All subsequent messages between the server and client are transmitted as JavaScript over WebSockets (JS over WS).

This model allows for transparent UI changes, event communication, and DOM fragment updates. It enables CLOG to function as a highly responsive 'push UI', providing real-time information delivery that is not possible with standard stateless web requests.

To use the hello-builder minimalist project, move the directory to your ~/common-lisp folder (or another directory in your QuickLisp search path). You can then load and run the application using QuickLisp and the provided entry point.

1. Load the system via QuickLisp: (ql:quickload :hello-builder)
2. Start the application: (hello-builder:start-app)

After installing CLOG via OCICL, you must enter your SBCL (Steel Bank Common Lisp) environment using the specific initialization file created during setup. Use the --userinit flag pointing to the init file to ensure the environment is correctly configured.

Once inside SBCL, load the CLOG tools system and start the CLOG builder using the following commands:

1. Load the tools: (asdf:load-system :clog/tools)
2. Start the builder: (clog-tools:clog-builder)

sbcl --userinit init

* (asdf:load-system :clog/tools)
* (clog-tools:clog-builder)

To build the CLOGFrame executables on macOS, ensure you have the necessary OS build requirements installed, then run the following commands in the clogframe directory:

./make-mac
./make-snake
./make-builder

To use jslists, include the minified script in your HTML file using a standard <script> tag.

<script src="jsLists.min.js"></script>

You can start CLOG and the CLOG Builder directly from your terminal using SBCL. This is the fastest way to get into the development environment.

Run the following command in your shell:

sbcl --eval "(ql:quickload :clog/tools)" --eval "(clog-tools:clog-builder)"

If you are using Emacs with SLIME, you can run these commands within your SLIME/SLY REPL:

To run the built-in tutorials, you must first ensure CLOG is loaded in your REPL. Depending on your environment, follow the appropriate steps below.

If using the CLOG Builder

Open a CLOG Builder REPL and execute:

(clog:run-tutorial 1)

If using another REPL

First, load CLOG using Quicklisp:

(ql:quickload :clog)

Then, run the tutorial:

(clog:run-tutorial 1)

Upon running, the Hunchentoot server will start (typically listening on 0.0.0.0:8080). Most demos will attempt to start a browser automatically. If they do not, navigate to http://127.0.0.1:8080 in your web browser.

If you are using plugins or dependencies located in non-standard directories, you can add the project's location to the ASDF central registry. This should be done via a --eval to your Lisp implementation (SBCL, ECL, etc.) before loading your project or the builder.

(pushnew #P"/path/to/a/project" asdf:*central-registry* :test #'equalp)