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.
You might define your own server class and inherit it from
This will allow to customize a list of
Here is the list of functions useful when working with Reblocks servers:
Base class for all Reblocks servers. Redefine it if you want to add additional
HTTP midlewares, etc.
Starts reblocks framework hooked into Clack server.
DEBUG to 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 t in their definition
APPS argument is provided.
Sometimes you might want your app respond on /some-uri and / return 404.
In this case it is useful to set
DISABLE-WELCOME-APP argument to T.
Stops Reblocks servers matching given
This function deactivates all applications bound to the server and stopps a Clack server.
Returns stopped server objects.
Adds a route to serve given object by static
Returns a new stack of layers inserting
LAYER before or after a layer with given name.
You should not give both
AFTER arguments. If given layer not found,
the function will signal error.
LAYERS is not modified.
Returns an alist where keys are keywords and values are Lack middlewares or apps.
Default primary method returns alist with two keys
:SESSION is a middleware and
:APP is the main application.
To modify middlewares list, define method for a server subclass
insert-middleware function on the results of
Here is an example, how this generic-function can be used to run
URLs with path starting from /api/:
(defmethod reblocks/server:make-middlewares ((server ultralisp-server) &rest rest) (declare (ignore rest)) (flet ((test-app (env) (declare (ignore env)) '(200 (:content-type "text/plain") ("Hello, World")))) (reblocks/server:insert-middleware (call-next-method) (cons :some-api (lambda (app) (funcall (lack.util:find-middleware :mount) app "/api/" #'test-app))) :before :app)))