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
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
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
stringappendSetClause()
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