Widgets are the main building blocks of Reblocks (hence the name).
At the heart of Reblocks is a tree of widgets that is manipulated by the clients requests. When a client sends its first request to a Reblocks application then a new session is started for it and a widget tree is associated with this session.
This initial widget tree 1 is computed as defined by the application developer.
reblocks/session:init is called by Reblocks
to initialize a new session. This function should return a single widget which become
a root of a tree:
TODO> (defmethod reblocks/session:init ((app tasks)) (declare (ignorable app)) (make-task-list "Make my first Reblocks app" "Deploy it somewhere" "Have a profit"))
The initial content and structure of the widget tree may depend on arbitrary factors; it is conceivable (although probably not very sensible) to generate different widget trees depending on the time of day.
A client's request for a specific
URI modifies the widget tree: widgets
called dispatchers choose their one child based on the current request
Old version of Weblocks had a
MAKE-WIDGET function. You was able to use strings
and function designators 3 instead of widgets in this context.
Probably, we will return this functionality some day.
Apart from session initialization the widget tree may be modified by actions.
Actions are plain functions that are stored in a session hash table the keys of which are unique identifiers. This way they can be called by the browser.
a normal request will be initiated.
It is often useful to set up closures as actions.
Example of typical action usage:
(reblocks/widget:defwidget counter () ((count :accessor count-of :initform 0))) (defmethod reblocks/widget:render ((widget counter)) (with-html (:p (format nil "The counter is at ~D." (count-of widget))) (:p (:button :onclick (reblocks/actions:make-js-action (lambda (&rest args) ;; closes over WIDGET. (incf (count-of widget)))) "Count up!"))))
Navigations and dispatchers
Dispatchers are widgets that configure themselves and their children
(i.e. broadly speaking the widget tree) based on the
URI of the request.
Navigations are dispatchers that maintain a simple one-to-one association between
URI token 2 a widget.
Old versions of Weblocks supported such dispatchers out of the box,
but during refactoring this functionality was moved into a separate
REBLOCKS-NAVIGATION-WIDGET system. Read its documentation to learn more.
To make everything work, you need to start one or more webservers on some
When you are starting a server, usually you specify an interface and port to listen on and a list os Reblocks apps to serve.
Here is the list of functions useful when working with Reblocks servers:
&KEY (DEBUG T) (PORT 8080) (INTERFACE
"localhost") (SERVER-TYPE :HUNCHENTOOT) (SAMESITE-POLICY :LAX) APPS
Starts reblocks framework hooked into Clack server.
DEBUGto true in order for error messages and stack traces to be shown to the client (note: stack traces are temporarily not available due to changes in Hunchentoot 1.0.0).
Server will start all apps declared having
autostart tin their definition unless
APPSargument is provided.
&optional interface port
Stops Reblocks servers matching given
This function deactivates all applications bound to the server and stopps a Clack server.
Returns stopped server objects.
&optional interface port
Returns a list of Reblocks servers.
Returns T if server is running and
uri object &key content-type
Adds a route to serve given object by static
- [function] widget