The reblocks-navigation-widget Reference Manual

This is the reblocks-navigation-widget Reference Manual, version 0.9.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:27:23 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 reblocks-navigation-widget

A container widget which switches between children widgets when user changes an url.

Author

Alexander Artemenko <>

Home Page

https://40ants.com/reblocks-navigation-widget/

Source Control

(GIT https://github.com/40ants/reblocks-navigation-widget)

Bug Tracker

https://github.com/40ants/reblocks-navigation-widget/issues

License

Unlicense

Long Description

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-DOCS-2FINDEX-3A-40README-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

# Reblocks Navigation Widget

<a id="reblocks-navigation-widget-asdf-system-details"></a>

## REBLOCKS-NAVIGATION-WIDGET ASDF System Details

* Description: A container widget which switches between children widgets when user changes an url.
* Licence: Unlicense
* Author: Alexander Artemenko <svetlyak.40wt@gmail.com>
* Homepage: [https://40ants.com/reblocks-navigation-widget/][1f1d]
* Bug tracker: [https://github.com/40ants/reblocks-navigation-widget/issues][c83a]
* Source control: [GIT][a78a]
* Depends on: [log4cl][7f8b], [reblocks][184b], [str][ef7f]

[![](https://github-actions.40ants.com/40ants/reblocks-navigation-widget/matrix.svg?only=ci.run-tests)][7c86]

![](http://quickdocs.org/badge/reblocks-navigation-widget.svg)

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-DOCS-2FINDEX-3A-3A-40INSTALLATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## Installation

You can install this library from Quicklisp, but you want to receive updates quickly, then install it from Ultralisp.org:

“‘
(ql-dist:install-dist "http://dist.ultralisp.org/"
:prompt nil)
(ql:quickload :reblocks-navigation-widget)
“‘
<a id="x-28REBLOCKS-NAVIGATION-WIDGET-DOCS-2FINDEX-3A-3A-40USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## Usage

This addon for Reblocks frameworks allows you to define which widgets should be
shown to the user dependening on ‘URL‘’s path.

The main entry-point is [‘defroutes‘][5f0d] macro. Use it to define a subclass of
navigation widget and then return this widget from the session initialization
method of your Reblocks application.

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-DOCS-2FINDEX-3A-3A-40NESTED-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## Nested routes

Starting from version 0.9.0, the library supports nested routes.
This allows you to combine routes defined in separate systems.

For example, lets pretend we have a separate ‘ASDF‘ system for user management.
It defines it’s routes like this:

“‘lisp
(defroutes users
("/" (make-user-list))
("/add" (make-new-user-form)))
“‘
And now, if we want to incorporate this user management app into our app having
it’s own routing, we can do this by using a prefix rule:

“‘lisp
(defroutes main
;; a subroutes
((:prefix "/users") (make-users))
;; a usual widget
("/stats" (make-stats)))
“‘
In it’s turn, ‘MAIN‘ router could be used in app having it’s own ‘PREFIX‘ ‘/admin‘. Here is how
this nested setup will be processed by navigation widgets.

When user opens a page with ‘URI‘ ‘/admin/users/add‘, then ‘MAIN‘ widget will be rendered
first. It will see the app has ‘/admin‘ prefix and will cut it from the ‘URI‘. Then ‘MAIN‘ routes
widget will check ‘/users/add‘ against it’s rules and will create ‘USERS‘ widget. ‘RENDER‘ method
of ‘USERS‘ widget will be called with ‘*current-path*‘ set to ‘/admin/users‘. In it’s turn,
‘USERS‘ widget will cut ‘/admin/users‘ prefix from the whole ‘URI‘ ‘/admin/users/add‘ and will check
‘/add‘ against it’s rules to find out it need to create a ‘NEW-USER-FORM‘.

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-DOCS-2FINDEX-3A-3A-40API-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## API

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-3ADEFROUTES-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29"></a>

### [macro](db42) ‘reblocks-navigation-widget:defroutes‘ class-name &body rules

Defines a new class with name ‘CLASS-NAME‘, inherited from [‘navigation-widget‘][9fc2].

And a function ‘make-{class-name}‘ to make instances of this class.

Each entry in rules should be a list of two items. First item is a regex pattern to match ‘URL‘ path.
Second item is a form to create a widget. A new widget will be created only if ‘URL‘
was changed.

Here is an example of a widget with two rules:

“‘
(defroutes tasks-routes
("/tasks/d+" (make-task-page))
("/tasks/" (make-task-list "Make my first Reblocks app"
"Deploy it somewhere"
"Have a profit")))
“‘
With these rules, when user opens ‘URL‘ ‘/tasks/‘ a widget returned by ‘MAKE-TASK-LIST‘
will be set as [‘current-widget‘][2e97] and shown to the user. If user clicks on some task
and ‘URL‘ change to ‘/tasks/100500‘, then a widget for a task will be created by a call
to ‘MAKE-TASK-PAGE‘.

**Pay attention** that widget creation form is responsible for extraction of the parameters
from the ‘URL‘. In above case, ‘MAKE-TASK-PAGE‘ should call ‘REBLOCKS/REQUEST:GET-PATH‘ and
parse path to extract task’s id. Probably this will change in future defroutes will catch
matched path pieces.

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-WIDGET-20CLASS-29"></a>

### [class](04b6) ‘reblocks-navigation-widget:navigation-widget‘ (widget)

Base class for all navigation widgets.

When rendered it tracks if ‘URL‘ was changed and
creates a new child widget according to given navigation rules.

Usually you don’t want to inherit from this class manually,
but instead use [‘defroutes‘][5f0d] macro.

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-3ACURRENT-WIDGET-20-2840ANTS-DOC-2FLOCATIVES-3AREADER-20REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-WIDGET-29-29"></a>

### [reader](3698) ‘reblocks-navigation-widget:current-widget‘ (navigation-widget) (= nil)

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-3ACURRENT-PATH-20-2840ANTS-DOC-2FLOCATIVES-3AREADER-20REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-WIDGET-29-29"></a>

### [reader](4b8a) ‘reblocks-navigation-widget:current-path‘ (navigation-widget) (= nil)

A whole path including the app’s prefix.

<a id="x-28REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-RULES-20-2840ANTS-DOC-2FLOCATIVES-3AREADER-20REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-WIDGET-29-29"></a>

### [reader](402c) ‘reblocks-navigation-widget:navigation-rules‘ (navigation-widget) (:rules)

[1f1d]: https://40ants.com/reblocks-navigation-widget/
[2e97]: https://40ants.com/reblocks-navigation-widget/#x-28REBLOCKS-NAVIGATION-WIDGET-3ACURRENT-WIDGET-20-2840ANTS-DOC-2FLOCATIVES-3AREADER-20REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-WIDGET-29-29 [5f0d]: https://40ants.com/reblocks-navigation-widget/#x-28REBLOCKS-NAVIGATION-WIDGET-3ADEFROUTES-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29
[9fc2]: https://40ants.com/reblocks-navigation-widget/#x-28REBLOCKS-NAVIGATION-WIDGET-3ANAVIGATION-WIDGET-20CLASS-29
[a78a]: https://github.com/40ants/reblocks-navigation-widget
[7c86]: https://github.com/40ants/reblocks-navigation-widget/actions
[db42]: https://github.com/40ants/reblocks-navigation-widget/blob/ac2b8a50279b61e6c6c5eb9e6d3be4158dc80636/src/core.lisp#L106
[04b6]: https://github.com/40ants/reblocks-navigation-widget/blob/ac2b8a50279b61e6c6c5eb9e6d3be4158dc80636/src/core.lisp#L22
[3698]: https://github.com/40ants/reblocks-navigation-widget/blob/ac2b8a50279b61e6c6c5eb9e6d3be4158dc80636/src/core.lisp#L23
[4b8a]: https://github.com/40ants/reblocks-navigation-widget/blob/ac2b8a50279b61e6c6c5eb9e6d3be4158dc80636/src/core.lisp#L25
[402c]: https://github.com/40ants/reblocks-navigation-widget/blob/ac2b8a50279b61e6c6c5eb9e6d3be4158dc80636/src/core.lisp#L31
[c83a]: https://github.com/40ants/reblocks-navigation-widget/issues
[7f8b]: https://quickdocs.org/log4cl
[184b]: https://quickdocs.org/reblocks
[ef7f]: https://quickdocs.org/str

* * *
###### [generated by [40ANTS-DOC](https://40ants.com/doc/)]

Version

0.9.1

Defsystem Dependency

40ants-asdf-system (system).

Dependency

reblocks-navigation-widget/core (system).

Source

reblocks-navigation-widget.asd.


2.2 reblocks-navigation-widget/core

Author

Alexander Artemenko <>

Home Page

https://40ants.com/reblocks-navigation-widget/

Source Control

(GIT https://github.com/40ants/reblocks-navigation-widget)

Bug Tracker

https://github.com/40ants/reblocks-navigation-widget/issues

License

Unlicense

Dependencies
  • log4cl (system).
  • reblocks/request (system).
  • reblocks/widget (system).
  • reblocks/response (system).
  • str (system).
Source

reblocks-navigation-widget.asd.


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 reblocks-navigation-widget/reblocks-navigation-widget.asd

Source

reblocks-navigation-widget.asd.

Parent Component

reblocks-navigation-widget (system).

ASDF Systems

3.1.2 reblocks-navigation-widget/core/file-type.lisp

Source

reblocks-navigation-widget.asd.

Parent Component

reblocks-navigation-widget/core (system).

Packages

reblocks-navigation-widget.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 reblocks-navigation-widget

Source

file-type.lisp.

Nickname

reblocks-navigation-widget/core

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: defroutes (class-name &body rules)

Defines a new class with name CLASS-NAME, inherited from NAVIGATION-WIDGET.

And a function ‘make-{class-name}‘ to make instances of this class.

Each entry in rules should be a list of two items. First item is a regex pattern to match URL path. Second item is a form to create a widget. A new widget will be created only if URL
was changed.

Here is an example of a widget with two rules:

“‘
(defroutes tasks-routes
("/tasks/d+" (make-task-page))
("/tasks/" (make-task-list "Make my first Reblocks app"
"Deploy it somewhere"
"Have a profit")))
“‘

With these rules, when user opens URL ‘/tasks/‘ a widget returned by MAKE-TASK-LIST
will be set as CURRENT-WIDGET and shown to the user. If user clicks on some task
and URL change to ‘/tasks/100500‘, then a widget for a task will be created by a call
to MAKE-TASK-PAGE.

**Pay attention** that widget creation form is responsible for extraction of the parameters from the URL. In above case, MAKE-TASK-PAGE should call REBLOCKS/REQUEST:GET-PATH and
parse path to extract task’s id. Probably this will change in future defroutes will catch matched path pieces.

Package

reblocks-navigation-widget.

Source

file-type.lisp.


5.1.2 Generic functions

Generic Reader: current-path (object)
Package

reblocks-navigation-widget.

Methods
Reader Method: current-path ((navigation-widget navigation-widget))

A whole path including the app’s prefix.

Source

file-type.lisp.

Target Slot

current-path.

Generic Reader: current-widget (object)
Package

reblocks-navigation-widget.

Methods
Reader Method: current-widget ((navigation-widget navigation-widget))

automatically generated reader method

Source

file-type.lisp.

Target Slot

current-widget.

Generic Reader: navigation-rules (object)
Package

reblocks-navigation-widget.

Methods
Reader Method: navigation-rules ((navigation-widget navigation-widget))

automatically generated reader method

Source

file-type.lisp.

Target Slot

rules.


5.1.3 Standalone methods

Method: render ((widget navigation-widget))
Package

reblocks/widget.

Source

file-type.lisp.


5.1.4 Classes

Class: navigation-widget

Base class for all navigation widgets.

When rendered it tracks if URL was changed and
creates a new child widget according to given navigation rules.

Usually you don’t want to inherit from this class manually, but instead use DEFROUTES macro.

Package

reblocks-navigation-widget.

Source

file-type.lisp.

Direct superclasses

widget.

Direct methods
Direct slots
Slot: current-widget
Readers

current-widget.

Writers

This slot is read-only.

Slot: current-path

A whole path including the app’s prefix.

Readers

current-path.

Writers

This slot is read-only.

Slot: current-prefix

A whole prefix including the rule matched to the current-widget.

Readers

current-prefix.

Writers

This slot is read-only.

Slot: rules
Initargs

:rules

Readers

navigation-rules.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Special variables

Special Variable: *current-prefix*

This var will be set during the RENDER method execution and will be equal to the path
of currently active rule. This allows to process nested navigation widgets correctly.

Package

reblocks-navigation-widget.

Source

file-type.lisp.


5.2.2 Ordinary functions

Function: cut-prefix (path prefix)
Package

reblocks-navigation-widget.

Source

file-type.lisp.

Function: get-new-widget-constructor (widget path)
Package

reblocks-navigation-widget.

Source

file-type.lisp.

Function: join-prefix (prefix path)
Package

reblocks-navigation-widget.

Source

file-type.lisp.

Function: make-lambda-rules (rules)

Transforms a list of lists like that

’((("/"
"/s/.*")
(make-my-story-widget ...)
("/about" (make-about-page...)))

into a similar list, but wrapping tail of each sublist in (lambda () ...):

’(("/"
(lambda ()
(make-my-story-widget ...)))
("/s/.*"
(lambda ()
(make-my-story-widget ...)))
("/about"
(lambda ()
(make-about-page...)))

Package

reblocks-navigation-widget.

Source

file-type.lisp.

Function: search-rule (rules path)
Package

reblocks-navigation-widget.

Source

file-type.lisp.


5.2.3 Generic functions

Generic Reader: current-prefix (object)
Package

reblocks-navigation-widget.

Methods
Reader Method: current-prefix ((navigation-widget navigation-widget))

A whole prefix including the rule matched to the current-widget.

Source

file-type.lisp.

Target Slot

current-prefix.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   C   D   F   G   J   M   N   R   S  
Index Entry  Section

C
current-path: Public generic functions
current-path: Public generic functions
current-prefix: Private generic functions
current-prefix: Private generic functions
current-widget: Public generic functions
current-widget: Public generic functions
cut-prefix: Private ordinary functions

D
defroutes: Public macros

F
Function, cut-prefix: Private ordinary functions
Function, get-new-widget-constructor: Private ordinary functions
Function, join-prefix: Private ordinary functions
Function, make-lambda-rules: Private ordinary functions
Function, search-rule: Private ordinary functions

G
Generic Function, current-path: Public generic functions
Generic Function, current-prefix: Private generic functions
Generic Function, current-widget: Public generic functions
Generic Function, navigation-rules: Public generic functions
get-new-widget-constructor: Private ordinary functions

J
join-prefix: Private ordinary functions

M
Macro, defroutes: Public macros
make-lambda-rules: Private ordinary functions
Method, current-path: Public generic functions
Method, current-prefix: Private generic functions
Method, current-widget: Public generic functions
Method, navigation-rules: Public generic functions
Method, render: Public standalone methods

N
navigation-rules: Public generic functions
navigation-rules: Public generic functions

R
render: Public standalone methods

S
search-rule: Private ordinary functions