Skip to content

Tips for Developers

Jump to bottom
Jean J. de Jong edited this page Nov 16, 2023 · 14 revisions

Extensive use is made of autocompletion, in-place edition and generic ajax-filled modals. An effort is made to use native Javascript without librairies such as jQuery.

Autocompletion

Autocompletion fields are data-driven and based on jQuary-UI autocomplete. To use the provided autocompletion functionality, define the following attributes in your input field:

  • data-ac="autocompletion source URL", e.g. data-ac="/actor/autocomplete",
  • name="database column name to update", e.g. name="actor_id".

By default, the autocompletion source is configured to return:

{ key: <an index>, value: <a value> }.

Value is usually the "human readable" data displayed for selection, but often this data is not the data sent to the database. Systematically key is sent to the database.

So, in principle, as soon as you select a human readable item from your suggestions list, it will be replaced by key in the input field.

This is in fact not a problem for (correctly designed) in-place edited data, because the data is refreshed as soon as the item is selected, whereby the key is just flashed during the refresh time.

For static forms, such as creation forms, if you want to see the human readable value, and send key to the database you need to:

  • provide a hidden input field with the required name attribute,
  • insert the following attribute in the visible input field: data-actarget="database column name". Don't set the name attribute in the visible input field, nor an id with that name to avoid confusing the autocompletion functionality.

For example, to insert/change an actor from a visible input field:

  • <input type="hidden" name="actor_id">
  • <input type="text" data-ac="/actor/autocomplete" data-actarget="actor_id">

Moreover, data-actarget is used to identify the visible input field for displaying validation error messages linked to the name of the hidden field.

In-place Edition

Most of the data displayed in modals is in-place editable. The editable data is displayed in input fields that have no graphic attributes, so their content fits seamlessly with the other content. These input fields have the class .noformat. Such input fields are listened to for changes: as soon as you start typing in one, its background warns you, and the new content is sent to the server and refreshed as soon as you leave the input field (by clicking anywhere outside the field or closing the edition window).

To identify what resource to modify in the database, use the attribute data-resource="path of the resource" in the input element itself or any parent element. Use the parent element when it has multiple children input fields sharing the same resource. For instance, in a <tr> having multiple <td>s with different data to modify for a same task, use:

<td data-resource="/task/[task_id]">.

Generic Ajax-filled Modals

The top-level structure has an empty modal with id="ajaxModal" to which all the above functionality is attached. To implement that modal, use the following attributes in an <a> trigger element (buttons are usable the same way - see Bootstrap 4 documentation for further details):

  • data-target="#ajaxModal",
  • href="route generating the html to display in the modal", e.g. href="/matter/1/edit"

Lists with a side panel showing Ajax loaded item details

Example: the actor.index view with a side-panel receiving the actor.show view of a selected actor.

The app.blade.php file contains generic functions for handling these. The index view should have:

  • a column with a table for the list, and
  • a column for the panel.

The panel is a card having a card-body with id="ajaxPanel".

The first cell of each table row is an <a> element with attributes:

  • href="link of the show view" and
  • data-panel="ajaxPanel"
Clone this wiki locally