Tsugi

CrudForm
in package

This is a class that supports the creation of simple CRUD forms.

This code generates HTML pages and makes SQL queries to automate the creation of simple CRUD forms by passing in values, table names, and strings. Here is a code example from admin/keys/key-add.php:

$from_location = "keys.php";
$fields = array("key_key", "key_sha256", "secret", "created_at", "updated_at");
CrudForm::insertForm($fields, $from_location);

This will output the HTML for a form that the user can fill in and submit. The $from_location is used under the "Cancel" button.

The file admin/key/key-add.php is a good example of how to do an insert form and the file admin/key/key-detail.php is a good example of the update case - which is significantly more complex.

Tags
TODO

This code needs to be able to translate and override the labels on the form.

Table of Contents

Constants

CRUD_FAIL  : mixed = 1
Indicates that CRUD operation failed (likely an SQL problem)
CRUD_NONE  : mixed = 2
Indicates that a CRUD operation could not be done because it was missing data.
CRUD_SUCCESS  : mixed = 0
Indicates that CRUD operation was successful

Methods

fieldToTitle()  : mixed
Maps a field name to a presentable title.
handleInsert()  : array<string|int, mixed>|int
Insert data from a $_POST of one of our generated forms insert form into the database.
handleUpdate()  : int
Apply the results of an update form to the database
insertForm()  : mixed
Generate the HTML for an insert form.
selectSql()  : mixed
Produce the SELECT statement for a table, set of fields and where clause.
updateForm()  : mixed
Generate the HTML for an update form.
valueToField()  : string
Maps a default value to a field.
appendSetClause()  : mixed
Append one clause to an UPDATE SET list, inserting a comma when needed.
echoCheckbox()  : mixed
Hidden 0 plus a checkbox so an unchecked box still posts a value.
echoSensitiveInput()  : mixed
Render a masked credential input that resists browser password-manager autofill.
isCheckbox()  : mixed
Whether a form field holds a secret / credential value.
isSensitiveField()  : mixed

Constants

CRUD_FAIL

Indicates that CRUD operation failed (likely an SQL problem)

public mixed CRUD_FAIL = 1

CRUD_NONE

Indicates that a CRUD operation could not be done because it was missing data.

public mixed CRUD_NONE = 2

CRUD_SUCCESS

Indicates that CRUD operation was successful

public mixed CRUD_SUCCESS = 0

Methods

fieldToTitle()

Maps a field name to a presentable title.

public static fieldToTitle(mixed $name[, mixed $titles = false ]) : mixed
Parameters
$name : mixed
$titles : mixed = false
Tags
todo

Make this translatable and pretty

handleInsert()

Insert data from a $_POST of one of our generated forms insert form into the database.

public static handleInsert(mixed $tablename, mixed $fields[, array<string, string> $binaryHex = array() ]) : array<string|int, mixed>|int

Here is a sample call:

$tablename = "tsugi_lti_key"; $fields = array("key_key", "key_sha256", "secret", "created_at", "updated_at"); CrudForm::handleInsert($tablename, $fields);

Parameters
$tablename : mixed
$fields : mixed

An array of fields to be inserted. These items must be in the $_POST data as well.

$binaryHex : array<string, string> = array()

Column name => 32 lowercase hex, stored with UNHEX.

Return values
array<string|int, mixed>|int —

Returns the fetched row array or the constant for SUCCESS, FAIL, or NONE

handleUpdate()

Apply the results of an update form to the database

public static handleUpdate(mixed $tablename, mixed $fields[, mixed $where_clause = false ][, mixed $query_parms = array() ][, mixed $allow_edit = false ][, mixed $allow_delete = false ]) : int

Here is a sample call:

$tablename = "tsugi_lti_key";
$fields = array("key_id", "key_key", "secret", "created_at", "updated_at");
$where_clause .= "user_id = :UID";
$query_fields = array(":UID" => ReqScope::loggedInUserIdLegacy()); // lib/include/lms_lib.php (via config.php)
$row =  CrudForm::handleUpdate($tablename, $fields, $where_clause, $query_fields, true, true);

This code very much depends on the $_POST data being generated from the form that this class created. For example it decides to delete or update based on a $_POST field from the button that was pushed. Also the primary key comes from the $_POST data, so this routine checks for consistency and provides a WHERE clause capability to make sure folks can only update data that belongs to them.

Also this code depends on database column naming conventions - in particular it knows that key_id is a primary key. In the above example, the ultimate WHERE clause will effectively be as follows:

UPDATE ... WHERE key_id = $_POST['key_id'] AND user_id = :UID
(with :UID bound to ReqScope::loggedInUserIdLegacy() from lms_lib.php)

This way, even if the user forges the key_id data to be one that does not belong to them, the AND clause will stop the UPDATE from happening. If this is an administrator that can update any record - simply set the $where_clause to an empty string and $query_fields to an empty array.

If we were editing some context-wide data as instructor, we might add ReqScope::currentContextIdLegacy() (see lms_lib.php) to the WHERE clause.

Parameters
$tablename : mixed
$fields : mixed

An array of fields to be updated. These items must be in the $_POST data as well. The primary key should be the first field in the list and end in "_id".

$where_clause : mixed = false

An optional (can be an empty string) WHERE clause limiting which primary keys can be updated.

$query_parms : mixed = array()

If there is a where clause, this is an associative array providing the values for the substitutable items in the WHERE clause.

$allow_edit : mixed = false

True/false as to whether editing is allowed

$allow_delete : mixed = false

True/false as to whether deleting is allowed

Return values
int —

Returns the constant for SUCCESS, FAIL, or NONE

insertForm()

Generate the HTML for an insert form.

public static insertForm(mixed $fields, mixed $from_location[, mixed $titles = false ][, mixed $fields_defaults = false ][, mixed $checkboxes = false ]) : mixed

Here is a sample call:

$from_location = "keys.php"; $fields = array("key_key", "key_sha256", "secret", "created_at", "updated_at"); CrudForm::insertForm($fields, $from_location);

Parameters
$fields : mixed

An array of fields to prompt for.

$from_location : mixed

A URL to jump to when the user presses 'Cancel'.

$titles : mixed = false

An array of fields->titles

$fields_defaults : mixed = false

An array of fields>default values

$checkboxes : mixed = false

selectSql()

Produce the SELECT statement for a table, set of fields and where clause.

public static selectSql(mixed $tablename, mixed $fields[, mixed $where_clause = false ]) : mixed
Parameters
$tablename : mixed
$fields : mixed

An array of field names to select.

$where_clause : mixed = false

This is the WHERE clause but should not include the WHERE keyword.

updateForm()

Generate the HTML for an update form.

public static updateForm(mixed $row, mixed $fields, mixed $current, mixed $from_location[, mixed $allow_edit = false ][, mixed $allow_delete = false ][, mixed $extra_buttons = false ][, mixed $titles = false ][, mixed $checkboxes = false ]) : mixed

Here is a sample call:

$from_location = "keys.php"; $fields = array("key_key", "key_sha256", "secret", "created_at", "updated_at"); $current = \Tsugi\Core\LTIX::curPageUrlNoQuery(); $retval = CrudForm::updateForm($row, $fields, $current, $from_location, true, true);

Parameters
$row : mixed

The existing data for the fields.

$fields : mixed

An array of fields to be shown.

$current : mixed

The URL of the current HTML page.

$from_location : mixed

A URL to jump to when the user presses 'Cancel'.

$allow_edit : mixed = false

True/false as to whether to show an Edit button

$allow_delete : mixed = false

True/false as to whether to show a Delete button

$extra_buttons : mixed = false

An array of additional buttons to show

$titles : mixed = false

An array of fields->titles

$checkboxes : mixed = false

valueToField()

Maps a default value to a field.

public static valueToField(mixed $name[, mixed $values = false ]) : string
Parameters
$name : mixed
$values : mixed = false
Return values
string

appendSetClause()

Append one clause to an UPDATE SET list, inserting a comma when needed.

private static appendSetClause(mixed &$set, mixed $clause) : mixed
Parameters
$set : mixed
$clause : mixed

echoCheckbox()

Hidden 0 plus a checkbox so an unchecked box still posts a value.

private static echoCheckbox(mixed $field, mixed $checked) : mixed
Parameters
$field : mixed
$checked : mixed

echoSensitiveInput()

Render a masked credential input that resists browser password-manager autofill.

private static echoSensitiveInput(string $field[, bool $preserve_on_empty = false ][, mixed $value = '' ]) : mixed

Uses type="text" (not "password") so empty fields are not treated as login forms. CSS bullet masking hides characters in WebKit/Blink; Firefox shows plain text while typing.

Parameters
$field : string

The input name/id.

$preserve_on_empty : bool = false

True on update forms (blank means keep existing value).

$value : mixed = ''

isCheckbox()

Whether a form field holds a secret / credential value.

private static isCheckbox(mixed $field, mixed $checkboxes) : mixed
Parameters
$field : mixed
$checkboxes : mixed

isSensitiveField()

private static isSensitiveField(mixed $field) : mixed
Parameters
$field : mixed

        
On this page

Search results