datarecord_class
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
datarecord_class [2020/11/10 19:08] – [fieldtype] sahl | datarecord_class [2024/02/14 15:51] (current) – [References between Datarecords and save deletes] sahl | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Datarecord class ====== | ====== Datarecord class ====== | ||
- | The Datarecord class is one of the core classes of Platform, as it provides a highly flexible | + | The Datarecord class is one of the core classes of Platform, as it allows you to create |
You can look for the Templateclass class which provides a blueprint for your own Datarecord class and can easily be altered to your own purpose. The Templateclass is meant as an example file, so you shouldn' | You can look for the Templateclass class which provides a blueprint for your own Datarecord class and can easily be altered to your own purpose. The Templateclass is meant as an example file, so you shouldn' | ||
Line 7: | Line 7: | ||
===== Quick start ===== | ===== Quick start ===== | ||
- | There's three steps to get a new Datarecord class up and running. | + | The most basic Datarecord class looks like this: |
+ | <code php> | ||
+ | class Templateclass extends Datarecord { | ||
+ | |||
+ | protected static $database_table = 'DATABASE TABLE'; | ||
+ | protected static $delete_strategy = self:: | ||
+ | protected static $location = self:: | ||
+ | |||
+ | protected static $depending_classes = [ ]; | ||
+ | protected static $referring_classes = [ ]; | ||
+ | |||
+ | protected static $structure = false; | ||
+ | protected static $key_field = false; | ||
+ | protected static $title_field = false; | ||
+ | |||
+ | protected static function buildStructure() { | ||
+ | static:: | ||
+ | parent:: | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | From here there is three steps to get it up and running. | ||
==== 1. Database table ==== | ==== 1. Database table ==== | ||
+ | |||
+ | We must decide for the database table name, which is done by overwriting the '' | ||
<code php> | <code php> | ||
- | protected static $database_table = 'DATABASE TABLE'; | + | protected static $database_table = 'my_database_table'; |
</ | </ | ||
- | |||
- | Alter the line above to select which table you want to store objects of this type into. (Don't create the table). | ||
==== 2. Object definition ==== | ==== 2. Object definition ==== | ||
- | Overwrite the buildStructure method to define which fields | + | Now we must define which fields |
- | ==== 3. Build table ==== | + | <code php> |
+ | protected static function buildStructure() { | ||
+ | static:: | ||
+ | new KeyType(' | ||
+ | new TextType(' | ||
+ | new TextType(' | ||
+ | new EmailType(' | ||
+ | ]); | ||
+ | parent:: | ||
+ | } | ||
+ | </ | ||
- | Ensure to add the '' | + | The first parameter is the desired database field, the next is the human readable field name and the last are specific options for the selected type. |
- | Now your object is ready to use. | + | ==== 3. Build table ==== |
- | ===== Object | + | To ensure the table is build in the database and ready for use, we need to call the '' |
- | You design the object by adding a structure | + | The natural place to call this function is in the '' |
- | Each element in the outer array represents a field and is hashed by the field name, while the inner array contains the field definition. The field definition contains the following fields: | + | After this, your object is ready to use. |
- | ==== label ==== | + | ===== Basic object usage (read / write) ===== |
- | The label is the human readable name of the field. | + | A Datarecord is created just like a regular |
- | + | ||
- | ==== fieldtype ==== | + | |
- | + | ||
- | The fieldtype defines the possible content of the field and should refer to one of the following constants: | + | |
- | + | ||
- | ^FIELDTYPE_KEY | + | |
- | ^FIELDTYPE_ARRAY | + | |
- | ^FIELDTYPE_BIGTEXT | + | |
- | ^FIELDTYPE_BOOLEAN | + | |
- | ^FIELDTYPE_CURRENCY | + | |
- | ^FIELDTYPE_DATE | + | |
- | ^FIELDTYPE_DATETIME | + | |
- | ^FIELDTYPE_EMAIL | + | |
- | ^FIELDTYPE_ENUMERATION | + | |
- | ^FIELDTYPE_ENUMERATION_MULTI | An array of enumerations. You need the enumeration property.| | + | |
- | ^FIELDTYPE_FILE | + | |
- | ^FIELDTYPE_FLOAT | + | |
- | ^FIELDTYPE_HTMLTEXT | + | |
- | ^FIELDTYPE_IMAGE | + | |
- | ^FIELDTYPE_INTEGER | + | |
- | ^FIELDTYPE_OBJECT | + | |
- | ^FIELDTYPE_PASSWORD | + | |
- | ^FIELDTYPE_REFERENCE_SINGLE | + | |
- | ^FIELDTYPE_REFERENCE_MULTIPLE| A reference to several other Datarecord objects. A reference to another Datarecord object. You need to specify the class in the foreignclass property.| | + | |
- | ^FIELDTYPE_REFERENCE_HYPER | + | |
- | ^FIELDTYPE_TEXT | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== Additional properties ==== | + | |
- | + | ||
- | Each field can have the following additional properties | + | |
- | + | ||
- | ^enumeration|If the field is an enumeration, | + | |
- | ^folder|If the field is a file field, this should specify which folder we store these files into.| | + | |
- | ^foreign_class|If the field is a reference to another class, this property should be the name of this class.| | + | |
- | ^form_size|Provides a hint to the form generator about the size of this field| | + | |
- | ^calculations|Determine what calculations should be performed on a remote | + | |
- | ^default_value|The default value of this field.| | + | |
- | ^invisible|A field of this type is invisible and cannot be viewed or edited by the user.| | + | |
- | ^is_title|If this is true, then this field is considered the title for the object.| | + | |
- | ^key|Indicates if this field should have a database key for improved performace. See below.| | + | |
- | ^required|The field is required, meaning that a form field representing this field will be mandatory.| | + | |
- | ^readonly|This field is readonly, which means it doesn' | + | |
- | ^searchable|Indicates if this field is searchable. See below. Only work on text-based fields.| | + | |
- | ^store_in_database|Indicate if the field should be stored in the database. Defaults to true. See below.| | + | |
- | ^store_in_metadata|Each object contains a metadata field which is an array stored in a single database field (as json). If you specify this property, then the field will be saved into the metadata instead of having its own database field. This is useful for limiting the number of database fields, but makes the field unsuitable for searching or other high-performance operations.| | + | |
- | ^table|This field defines how the field is shown in tables. See constants below.| | + | |
- | ^tablegroup|If true tables will group by this field.| | + | |
- | ==== table constants ==== | + | |
- | + | ||
- | ^COLUMN_VISIBLE | Show the column (but allow the user to hide it). This is the default setting if no value is passed.| | + | |
- | ^COLUMN_HIDDEN| The column is hidden by default, but the user can select to show it.| | + | |
- | ^COLUMN_INVISIBLE| The column is hidden and cannot be selected to show.| | + | |
- | + | ||
- | ==== store_in_database ==== | + | |
- | + | ||
- | If this is set to false, the field will not be read or written to the database, but still be available. This can be used for calculated fields, where you then have to overwrite the getValue method in order to display data. Example: If you have two fields first_name and last_name, and also want a field full_name, you can implement full_name as a field not stored in the database. | + | |
<code php> | <code php> | ||
- | protected static function buildStructure() { | + | $contact |
- | | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ), | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ), | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ), | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ), | + | |
- | ); | + | |
- | self:: | + | |
- | parent:: | + | |
- | } | + | |
- | + | ||
- | // We override this to make a special handling of the full_name field. | + | |
- | // For all other fields we just call the parent function. | + | |
- | public function getRawValue($field) { | + | |
- | switch ($field) { | + | |
- | case ' | + | |
- | return $this-> | + | |
- | default: | + | |
- | return parent:: | + | |
- | } | + | |
- | } | + | |
</ | </ | ||
- | **Pro tip:** Only use this for very light calculations with information already available on the object. It shouldn' | + | The following two are equivalent and are used to assign |
- | + | ||
- | ===== Basic object usage ===== | + | |
- | + | ||
- | The object is created just like a regular object. | + | |
- | + | ||
- | <code php> | + | |
- | $user = new User(); | + | |
- | </ | + | |
- | + | ||
- | To set a field use one of the following, which is equivalent: | + | |
<code php> | <code php> | ||
- | $user-> | + | $contact-> |
- | $user->username | + | $contact->full_name |
</ | </ | ||
- | To read a value use one of these: | + | These fields can be read back using one of the following (where both are equivalent): |
<code php> | <code php> | ||
- | $username | + | $full_name |
- | $username | + | $full_name |
</ | </ | ||
- | There are more ways to read values from an object. This will be covered further down. | + | Up until now we have only had the object |
- | + | ||
- | To save an object to the database: | + | |
<code php> | <code php> | ||
- | $user-> | + | $contact-> |
</ | </ | ||
- | This will automatically fill in the object | + | This will save the object in the database (assuming we have built the corresponding table using the '' |
- | To load an object from the database, using an ID, use one of the following: | + | We can retrieve |
<code php> | <code php> | ||
- | $user->loadForRead($id); | + | echo $contact->contact_id; |
- | $user-> | + | |
</ | </ | ||
- | Loading an object for read, doesn' | + | If we need to retrieve |
<code php> | <code php> | ||
- | $user-> | + | $contact = new Contact(); |
- | </code> | + | $contact->loadForRead($id); |
- | If an object is opened for writing, but one decides not to save it, it can be unlocked like this: | + | // OR |
- | <code php> | + | $contact = new Contact(); |
- | $user->unlock(); | + | $contact->loadForWrite($id); |
</ | </ | ||
- | ...which also will switch it to read mode. | + | When loading objects from the database we can both load them in a read context and a write context. |
- | An object | + | Loading an object |
+ | |||
+ | Loading an object for write will lock the object, so no other process can change it, before we are finished with it. This is to ensure that two processes doesn' | ||
+ | |||
+ | All objects locked this can be unlocked in one of three ways: | ||
+ | |||
+ | - By saving it. The object will be switched back into read mode afterwards. | ||
+ | - By calling | ||
+ | - At the end of script execution. | ||
+ | |||
+ | ===== Deleting objects ===== | ||
+ | |||
+ | An object which have been saved to the database | ||
<code php> | <code php> | ||
- | if ($user-> | + | $contact-> |
</ | </ | ||
===== More about values ===== | ===== More about values ===== | ||
- | Values in the datarecord object | + | Values in the Datarecord objects |
- | ^Mode^Function^Explanation^ | + | <code html> |
- | |RENDER_RAW|getRawValue()|This is the "raw" | + | <a href="tel: |
- | |RENDER_FULL|getFullValue()|This is the display value, meaning the value to show to the end user. This is typically styled with html.| | + | </ |
- | |RENDER_TEXT|getTextValue()|This is the display value, but suited for a text-only context, meaning that it isn't styled with html.| | + | |
- | |RENDER_FORM|getFormValue()|This is the value as suited to pass into a proper form field.| | + | |
- | The basic functions to get and set values are '' | + | Or maybe we would use it in a text email, where html wasn't allowed but we would still like the nice spacing such as: |
- | <code php> | + | +1 555 1234567 |
- | $user-> | + | |
- | // is equal to: | + | |
- | $user-> | + | |
- | $name = $user-> | + | Datarecord provides for all of this by calling the correct function |
- | // is equal to: | + | |
- | $name = $user-> | + | |
- | </ | + | |
- | Pr. default getValue return raw values, but this behaviour can be modified by calling | + | ^function^result^example^ |
+ | |getRawValue()|Get the technical value used when programming|+15551234567| | ||
+ | |getFullValue()|Get the value for display in a browser. May include HTML.|<a href=" | ||
+ | |getTextValue()|Get the value for display in a text where HTML isn't allowed.|+1 555 1234567| | ||
+ | |getFormValue()|Get the value compatible with a fitting form field.|| | ||
+ | |getTableValue()|Get the value for displaying in a table.|| | ||
+ | |getLogValue()|Get the value for displaying in a log file.|| | ||
===== Object title ===== | ===== Object title ===== | ||
- | A datarecord | + | A Datarecord |
===== Convenience functions ===== | ===== Convenience functions ===== | ||
==== Getting a form ==== | ==== Getting a form ==== | ||
- | With a properly formed field definition, one can get a form for editing the object by just calling '' | + | One can get a form for editing the object by calling '' |
- | + | ||
- | The form will contain all editable fields in the same order that they are defined in the '' | + | |
- | To place fields | + | The form will contain all editable |
If one needs javascript to get the form to behave, then set the '' | If one needs javascript to get the form to behave, then set the '' | ||
Line 234: | Line 171: | ||
==== Complete edit interface ==== | ==== Complete edit interface ==== | ||
- | Calling the '' | + | Calling the '' |
- | Also see [[DatarecordEditComplex | + | Also see [[EditComplex |
- | ===== References between Datarecords ===== | + | ===== References between Datarecords |
- | It is easy to relate Datarecords to each other. To link a Datarecord | + | Some field types allows the linkage |
+ | |||
+ | If you extended | ||
+ | |||
+ | This could be an example of such... | ||
+ | |||
+ | CONTINUE FROM HERE | ||
You will also need to go to the foreign datarecord class and add the class name of this datarecord class to either the '' | You will also need to go to the foreign datarecord class and add the class name of this datarecord class to either the '' | ||
Line 247: | Line 190: | ||
It is possible to use references with non-datarecord classes, as long as these classes implements the '' | It is possible to use references with non-datarecord classes, as long as these classes implements the '' | ||
+ | |||
==== Deleting data and references ==== | ==== Deleting data and references ==== | ||
- | When deleting data, a system | + | Platform has a system in place to handle |
+ | |||
+ | In order for this system to work, one need to indicate | ||
+ | |||
+ | Adding it to '' | ||
+ | |||
+ | Adding | ||
- | In order for the delete system to function correctly, it is important that all classes that refers this class is mentioned in either the '' | + | This logic is nested, so deleting an object can initialize a chain reaction of other deletions and references being removed, keeping your data without dangling references. |
- | Classes in the '' | + | === Delete strategies === |
- | In opposition, the '' | + | Sometimes you don't want to delete an object |
- | And now to the strategies: | + | There are three possible delete |
<code php> | <code php> | ||
Line 263: | Line 213: | ||
</ | </ | ||
- | This is the default strategy and this will prevent deletion of a datarecord | + | This is the default strategy and this will prevent deletion of a Datarecord, |
+ | It is possible | ||
<code php> | <code php> | ||
Line 272: | Line 223: | ||
When using this strategy, a call to '' | When using this strategy, a call to '' | ||
+ | |||
+ | <code php> | ||
+ | self:: | ||
+ | </ | ||
+ | |||
+ | This strategy will delete the current object, but will not affect any referring or depending objects. This can only be used, when working with //soft deletion//. See below. | ||
+ | |||
+ | ==== Soft deleting objects ==== | ||
+ | |||
+ | Sometimes it can make sense to keep the database record after deleting an object, for example if you are synchronising | ||
+ | |||
+ | To add soft deletion to an object override the '' | ||
+ | |||
+ | <code php> | ||
+ | protected static $delete_mode = Datarecord:: | ||
+ | </ | ||
+ | |||
+ | This will add a field // | ||
+ | |||
+ | <code php> | ||
+ | protected static $delete_mode = Datarecord:: | ||
+ | </ | ||
+ | |||
+ | This will do exactly the same as above, except that no fields are emptied, so when deleting the object, it will remain in the database, but have the // | ||
+ | |||
+ | |||
+ | Remember to '' | ||
===== Copying objects ===== | ===== Copying objects ===== | ||
Line 357: | Line 335: | ||
Datarecords supports database keys for improved performance. To add a key to a field simply set the // | Datarecords supports database keys for improved performance. To add a key to a field simply set the // | ||
- | To make a key spanning more than one field, instead set the // | + | To make a key spanning more than one field, instead set the // |
A call to '' | A call to '' | ||
Line 398: | Line 376: | ||
Class:: | Class:: | ||
- | // Check if we are allowed to copy the object. | + | // Check if we are allowed to copy objects of this class (in general). |
- | Class:: | + | Class::isCopyAllowed(); |
+ | |||
+ | // Check if we are allowed to copy this object. | ||
+ | $object-> | ||
// Check if we are allowed to edit this object. | // Check if we are allowed to edit this object. |
datarecord_class.1605035295.txt.gz · Last modified: 2020/11/10 19:08 by sahl