This app is in development. The description is NOT STABLE.

The Unknowns Soda application enables users with appropriate permissions to create and edit view unknowns.

Data Formats

HTML

When a page containing an Unknowns block is loaded, the HTML has the start and end of a block that contains an Unknowns view that displays the unknowns. If the user can re-order the unknowns, the start and end might for example be:

<div class="sodarows" sodaviewid="-1_-9223372036846876753" sodaplugin="Unknowns" sodawritelevel="88_-9223372036854775807" sodawritelevelname="away:admin" sodaviewpath="sys/views/view-unknowns">
<div class="sodaviewflex sodacards sodamovables ui-sortable" key_unknown="Unknown" rank_unknown="Rank">

  .  .

</div>
</div>

There is an HTML div in the content for each unknown. If the user has sufficient access permissions the div has the sodamovable class, and includes an Edit and Delete buttons and a Drag handle. For example:

<div class="sodasegment sodacard sodacardfixedwidth sodamovable" id="I88_-9223372036847887775KGrade" title="Grade">
<h3>Grade</h3>
<div class="sodasegmentactions">
  <button sodaaction="view_prepare_edit" sodasegmentid="I88_-9223372036847887775KGrade" class="sodasegmentbutton sodarowevent" type="button"><svg class="sodaicon<" width="100%" height="100%" draggable="false" style="fill: currentColor;"><use href="#edit.svg" x="0" y="0"></use></svg></button>
  <button sodaaction="view_delete" sodasegmentid="I88_-9223372036847887775KGrade" sodadescription="unknown" class="sodasegmentbutton sodarowevent" type="button"><svg class="sodaicon<" width="100%" height="100%" draggable="false" style="fill: currentColor;"><use href="#remove.svg" x="0" y="0"></use></svg></button>
  <div class="sodamovehandle ui-sortable-handle" draggable="true"><svg class="sodaicon<" width="100%" height="100%" draggable="false" style="fill: currentColor;"><use href="#move.svg" x="0" y="0"></use></svg></div>
</div>

If the user has sufficient access permissions, there is also a div containing an Add button. This might for example be:

<div class="sodasegmentactions">
  <button sodaaction="view_prepare_add" sodasegmentid="" class="sodasegmentbutton sodarowevent" type="button"><svg class="sodaicon<" width="100%" height="100%" draggable="false" style="fill: currentColor;"><use href="#add.svg" x="0" y="0"></use></svg></button>
</div>

User Actions

When the user clicks an Add or Edit button, an API view_prepare_add or view_prepare_edit method is invoked to retrieve a form from the server. The form is displayed in a fixed position on the page, on top of the page content. The form has Proceed and Cancel buttons. When the user clicks the Proceed button, the view_add or view_edit method is invoked to submit the form. If the request succeeds then it returns HTML text which is displayed in an additional div (for an add) or in place of the original div (for an edit) and the form is removed. If the request fails, then an error alert is displayed and the form is re-displayed not removed, with the returned error message. When the user clicks the Cancel button, the form is removed.

The request may succeed but produce a result that leaves the view whose unknowns are being defdined in an inconsistent or dangerous state. For example, an unknown that is the subject or verb of a constraint might not have an item type. In such a case, the request to define the unknown with a non-item type succeeds, but an error or warning message is displayed. Such a message might be displayed in the Unknowns, Constraints, Actions or Columns section of the view definition page, depending on the nature of the error or warning.

When the user clicks a Delete button, a confirmation dialog is displayed. If the user confirms the action, the API view_delete method is invoked. If it succeeds, the Unknown div containing the delete button is removed.

The user can use the drag handles to re-order the unknowns. The API move-row method is invoked when an unknown is dropped.

Form Fields

The forms to add and edit unknowns have the following fields.

Name - text input

Display Type - select

Description - textarea

Priority - number input

Editable - checkbox

Reverse Sort Order - checkbox

Rank - number input

(The Priority, Reverse Sort Order and Rank fields should be removed, as their values are set automatically. A Required field should be added.)

Server Responses

If an API view_prepare_add or view_prepare_edit method succeds, the server returns the HTML of a form to be displayed.

If an API view_add or view_edit method succeeds, the server returns a JSON object that may contain the following fields:

view - the HTML for the view
unknown messages - the HTML for a message to be displayed in the Unknowns section of the view definition page
constraint messages - the HTML for a message to be displayed in the Constraints section of the view definition page
action messages - the HTML for a message to be displayed in the Actions section of the view definition page
column messages - the HTML for a message to be displayed in the Columns section of the view definition page

The unknown field will always be present. None of the other fields need be included.