Components
Widgets
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.
A generic-function 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
URI
.
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.
Actions
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.
When Javascript is available actions will be called via AJAX
, otherwise
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
an 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.
Servers
To make everything work, you need to start one or more webservers on some TCP
ports.
When you are starting a server, usually you specify an interface and port to listen on and a list os Reblocks apps to serve.
You might define your own server class and inherit it from reblocks/server:server
class.
This will allow to customize a list of HTTP
middlewares.