The Readable Programming Language - Handbook

User Interface

Pages and Widgets

The user interface of a Lisilogic application is made up of (web)pages and widgets that can be included in these pages.

A page is identified by its title: the "Edit Profile" page.
A widget has a name, which is an identifier (see Basic Syntax: Identifiers): the address_editor.

A page or widget is defined by at least one "can" sentence.
At the top of the "Edit Profile" page, the user can... On the address_editor, the user can...
See also Roles.

Several sentences may add elements to the same page or widget.

It is possible to add an element to all pages at once:
In the header of any page, the user can see the text "Hello {his username}!".
It is not possible to add an element to all widgets at once.

"Home" page

The "Home" page is predefined, corresponding to the page that gets displayed when no other one is required specifically (index.html, index.php etc.).

If the caller isn't logged in (he is a visitor, see Roles), the "Home" page will display a login form, in addition to whatever UI elements have been added on it for the visitor role.

Locations

The layout of a page is organized in several regions as follows:
Page title   In the header
In the menu At the top
On
At the bottom
In the footer

A widget has only the top, middle ("on") and bottom regions.
At the top
On
At the bottom

Several sentences may add elements to the same region of a page or widget. Inside a region, the elements will appear in the same order as the sentences in the code.

In the future, Lisilogic may support different layouts and their locations.

Styling

For now, it is not possible to provide styling information in Lisilogic.

It is a challenging research topic to find a way to replace CSS (or a meaningful subset of their possibilities) with descriptions readable and understandable by non-specialists.
The style information must not obfuscate the code, neither by requiring more text than reasonable, nor by requiring to be placed away from the definition of the ui elements it decorates, nor by allowing manipulations that have an influence on the application logic (like hiding UI elements) or that lead to comprehension difficulties (like CSS float:right that lets elements defined left to right in the code appear right to left in the user interface).
Research partners wanted! Write to info@lisilogic.com.

Syntax of a "can" sentence

A "can" sentence starts with the location on the page where UI elements are to be added:
In the header of the "Home" page, ... At the bottom of the address_editor, ...

One or several "can" clauses follow. Each "can" clause may be preceded by a condition and defines UI elements for a role:
... the admin can... ... if his birthday is null, the user can...

See Basic Syntax: Lists about lists and lists in lists (e.g. list of UI elements in a list of "can" clauses).

Each UI element may be preceded by a condition too and is either a displayer (see, read, download), an editor (edit, upload), or a button (click).

Conditions

A condition is introduced by if, else if or otherwise, the word "if" followed by an expression that must result in a boolean (see Expressions).
On the "Edit Profile" page, the user can: - if his birthdate is null, edit his birthdate, - else if his age is smaller than 18 years, see the text "You are too young for adult pictures", - otherwise, see all adult_pictures.

The special there are expressions test if notifications (errors, warnings, messages, or any of these) have been issued and will be displayed on the page:
At the bottom of any page: - if there are no errors, the user can see the text "OK", - if there are notifications, the user can see the text "Pay attention to the notifications".
Notifications issued from a procedure (see Procedures: issue) are present in the whole next page to be shown. Notifications issued in the page itself (see Displayers: Text) are only present after they've been displayed.

Buttons

A button has a text, may ask for a confirmation, and triggers an action.

In the menu of any page, the user can click on "Logout" to logout.

On the "Edit Profile" page, the user can click on "Delete Profile" and confirm "Delete profile, sure?" to: - issue the message "Profile {his username} deleted!", - delete himself, - logout.

If present, the confirmation must contain a text to be displayed or a value to check introduced by the word with, or both. If a check is whished, the user will be provided with a password field in the confirm dialog. The value he types in will be compared with the value to check and the action will be executed only if they are identical. The value to check doesn't have to be a password, but the check will fail if it can't be compared to the text entered by the user.

On the "Add Comment" page, the submitter can click on "Add Comment" and confirm "Please type in the word \"human\" to prove that you're not a robot" with the text "human" to save.

On the "Submit Project" page, the submitter can click on "Send Submission" and confirm with his signature to submit his project.

The possibility to provide buttons with an image or a calculated text is in development.

An action can be a simple action, a navigation action, a procedure call or an anonymous procedure (definition and call in one).

Simple Actions

logout
terminates the eventual current procedure (see Procedures), terminates the session and logs out the user (he becomes a visitor, see Roles).

save
sends the contents of the editors displayed on the current page to the server and displays the current page again.
The current procedure (if any) remains at the same step.

For now, a "save" button placed in a widget saves all editors on the page. In the future, if whished so during pioneer projects, it might save only the editors of the widget.

skip
lets the current procedure go on one step (see Procedures) without saving the contents of the editors presently displayed.

continue
sends the contents of the editors displayed on the current page to the server and lets the current procedure go on one step (see Procedures).

cancel
interrupts the current procedure (see Procedures) without saving the contents of the editors presently displayed.

Navigation Actions

A navigation action is introduced by the verb go to and must indicate the page of the application to navigate to; it may provide a value for the parameter of the page (the variable "the given ..." in its definition) introduced by for. See Expressions: Contextual Constants.

In the menu of any page, the user can click "Edit Profile" to go to the "Edit User Profile" page for himself.

Navigating to a page of the application terminates the current procedure if there's one (see Procedures).

Opening External Pages

Opening an external page is introduced by the verb open and must indicate its URL; it may provide a HTML target (a new tab or a new window corresponding to HTML "_blank", the "..." tab/window etc.). If no target is precised, the page will be opened in a new tab/window ("_blank").

On the profile_viewer, the user can, if the given profile's external_page is not null, click on "Open external page" to open the given profile's external_page in a new window.

Procedure Calls

A procedure call indicates the name of the procedure to be started and may provide a value for its parameter (the variable "the given ..." in the procedure definition). See Expressions: Contextual Constants.

At the bottom of the "Proposal Editor" page, the user can: - click on "Clear" to clean_up, - click on "Review" to review his proposal.

If a value is given, the procedure with the given name whose parameter type exactly matches the type of the given value gets started. There's no automatic conversion. Be aware that the given value might be null, in which case the procedure defined with null as a parameter type gets started. An error will be issued if no procedure definition matches the given value.

Parameters are passed by value, not by reference, but if the passed value is a structure, the procedure may modify its attributes.
This is very comparable to Java, except for lists (in Java, the Collections are Objects whose content can be modified by a method; in Lisilogic, a procedure that receives a list as a parameter can't add or remove values from it).

Starting a procedure terminates the eventual current one.

See also Procedures.

Anonymous Procedures

An anonymous procedure is defined directly in the button that starts it: On the "Edit Profile" page, the user can click on "Delete Profile" and confirm "Delete profile, sure?" to: - issue the message "Profile {his username} deleted!", - delete himself, - logout.

See Procedures on how to write the definition.

Starting an anonymous procedure terminates the eventual current procedure.

Inside an anonymous procedure, the "given" and "current" variables as well as all pronouns (himself, his, it, its, them, their, etc.) have the same meaning as in the page or widget where it is defined. See Expressions: Contextual Constants.

Editors

edit

To include an editor in a page or a widget, you indicate:

  • An eventual condition,
  • The verb edit,
  • The path to the attribute to be edited,
  • If whished, the editor widget to include, introduced by using,
  • An eventual label, title or header, introduced by under.


On the address_editor, the user can: - edit the given address's street, - edit its house_number under the label "Nr.", - click "Save" to save. On the "Edit Profile" page, the user can: - if his address is null, click on "Create address" to create his address, - otherwise, edit his address using an address_editor under the header "Address".

If no label is specified, Lisilogic will use the name of the attribute to edit.

See Structures: Basic Types for informations about the kind of editor used for each attribute type.
Structures and structure lists don't have a default editor, except files and images, that can be uploaded (see below). This is a normal use case for a widget include, a list or a table viewer (see below).

Remember to add a "save" or "continue" button to any page with editors!
Widgets will be saved along with the page that includes them.
For now, a "save" button placed in a widget saves all editors on the page. In the future, if whished so during pioneer projects, it might save only the editors of the widget.

upload

File and image attributes (see Structures: Predefined Structures) may be edited using the verb upload.

The normal editor also displays the files or images to be edited, the upload editor only shows a file input. You'll use this variant when the files or images are already displayed otherwise, for instance in a table.

Further Editors

A "choose ... from ..." editor is in development.

In the future, Lisilogic might allow alternative editors for basic types, for instance radio buttons instead of a dropdown-menu to edit single value enumerated attributes.

Displayers

Each displayer may be preceded by a condition, see Conditions.

Text

A text displayer

  • is introduced by the verb see or read,
  • followed by the word the and the display style: title, text, header, notification, error, warning or success notification,
  • the string constant to display, with eventual calculated parts in braces ({}),
  • and an eventual title, label or header, introduced by the word under.

In the header of any page, the user can see the text "Hello {his username}!".

On the "Summary" page, the user can: - if his submission's complete is true, see the success notification "Submission complete!", - otherwise, see the warning "There are still missing parts.", - read the text "from the {his submission's begin} to the {his submission's end}" under the label "Project duration".

Notifications (plain notification, error, warning, success notification) can be tested in conditions using a there are expression, see Conditions.

Default Displayer

Nearly any value (see Expressions) can be displayed with a default viewer depending on its type, see Structures.

The default displayer of a structure is made up of the default displayers of its attributes, except those that are structures themselves.

A default displayer can be provided with a title, label or header, introduced by the word under. If none is provided, Lisilogic will try to find an appropriate label, for instance the name of the attribute if the expression to display is an attribute.

On the "View User Profile" page, the user can see: - the given user's username, - the given user's last_login under the label "last logged in", - the given user's address.

Downloads

Files and images can be viewed with the verb download instead of see. Like the default displayer, it will show a download link, under the filename for files and the thumbnail for images. Unlike their default displayer, but like the default displayer for other structures, it will also display their other attributes.

To have a precise control over which attributes are displayed, define and use a widget.

Widget Include

Any value (see Expressions) can be displayed by including a widget introduced by the word using.
On the "View User Profile" page, the user can see the given user's address using an address_viewer.

In the definition of the widget, the passed value corresponds to the expressions "the given ...", see Expressions: Contextual Constants.

For now, there is no difference between including a widget with the verb edit or with the verb see.
The possibility to use disabled editors as displayers is in development: the editors contained in a widget will then be disabled if it is included with see.

List

A list displayer is defined using:

  • an eventual condition (see Conditions),
  • the value list to display preceded by the list of or followed by as a list,
  • an eventual label, title or header for the whole list, introduced by the word under,
  • either a widget to include for each element of the list, introduced by using,
  • or the word where followed by one or several "can" clauses (see Syntax of a "can" sentence).


On the "Friends" page, the user can see the list of his friends under the title "My Friends" using a profile_viewer.

On the "Customers" page, the salesperson can see his customers as a list where he can - see their name, - see their address, - see their bonus_points, - click on "Add bonus" to add 10 points to their bonus, - click on "Edit" to open the customer_editor for them.

The definition of the list viewer will be repeated for each element of the list.
The current element corresponds to the variables "the current ...", "them" and "their", see Expressions: Contextual Constants.
When including a widget repeatedly in a list viewer, the current element will be passed as a parameter, so it should be accessed using "the given ..." in the definition of the widget (and not "the current ...").

See also Basic Syntax: Lists on how to write "can" clauses inside a "can" clause.

Table

A table displayer is defined using:

  • an eventual condition (see Conditions),
  • the row list to display preceded by the table of or followed by as a table,
  • an eventual label, title or header for the whole table, introduced by the word under,
  • the word showing followed by one or several column definitions.

A column definition indicates:

  • the word a,
  • eventual vertical and/or horizontal alignments among top, middle, bottom, left, center and right followed by the word aligned,
  • an eventual header for the column, between quotes (""),
  • the word column,
  • either the word containing followed by the value to display for each row (see Expressions),
  • or the word where followed by one or several "can" clauses.

On the "Sales" page, the salesperson can: * see his orders under the title "My Sales" as a table showing: - a top-left aligned "Nr." column containing their order_number, - a column containing their order_date, - a "Paid" column where he can edit their payment_date, - a "Delivery" column containing the text "{their planned_delivery_from} - {their planned_delivery_to}"; * click "Save" to save.

The definition of each column will be repeated for each row of the table.
The current row corresponds to the variables "the current ...", "them" and "their", see Expressions: Contextual Constants.

If no header is provided for a column, Lisilogic will try to calculate a reasonable default, like the name of the attribute if an attribute is displayed in the column.

If no alignment is provided for a column, Lisilogic will use the default vertical alignment of the browser for table cells (middle) and the default horizontal alignment corresponding to the type of its content: right aligned for numbers, centered for booleans, left aligned for other values.

Values introduced by the word containing are displayed using their default displayer, see above.
Exception: the unit of numbers won't be repeated in each cell; it is recommended to define the column with an explicit header indicating it.

See also Basic Syntax: Lists on how to write a list of column definitions inside a "can" sentence.