Field Profile Description
Unlike the class profile, where settings apply to the class itself, here the behavior of each of its fields is configured individually. This includes, first, system settings necessary for the kernel’s operation (for example, information about the field type and, if the field is virtual (not physically located in this table), information about the connection with other tables or from which fields/rows to assemble it. And second, behavior settings for both the server side and client components.
In the description, virtual fields will be encountered, i.e., fields from other tables with their own key. For example, class (class_id). We will not emphasize that it is physically stored as the field
Fields
class_id. System field, link field to the class.
column_name. This is the system name of the field and it should not be changed after creation. This is how the field is named in tables.json and in the database.
name. This is the user-friendly name of the field. This label will be in tables and forms.
select_class. Necessary for client components for virtual fields (connected from other tables) so that dropdown lists know which table to target. Usually, you need to specify the same thing as in from_table. If nothing is specified, the kernel may use from_table, however, this option appeared recently and has not been fully tested, so if dropdown lists go to the wrong place, just specify the correct class in this field.
parent_key. See also the description of parent_key in the class profile. Allows specifying that data filtration in the table will be applied by this field if this table is located inside the form of a parent entity. For example, in an order form (No. 15), you can place a table with order items and specify for this table that the parent_key is “order_id”, then only the items of this (15th) order will be displayed.
primary_key. System. Always id.
foreign_disable (foreign_table, foreign_key_str). The kernel can automatically generate foreign keys for fields referring to other tables. This mechanism was introduced relatively recently, and it created foreign keys by default, but this could be disabled with the foreign_disable parameter. Later it became clear that it’s better not to create keys for everyone, but to do it selectively. Therefore, this parameter now defaults to true.
foreign_table, foreign_key_str - system fields where system-defined dependencies are written.
return_id, return_name, lov_return_to_column, select_search_columns. Fields for configuring the dropdown list editor.
The request is directed to select_class and takes id and name from there. However, this can be overridden.
return_id. You can specify that the requested table should return not id, but some other field. This can be useful if the query itself is overridden and, for example, performs grouping by some field, then it makes sense to take it as the id for the list.
return_name. This field is overridden more often than return_id, because even if the query goes to a classic reference book, name is not always what is needed from it. For example, from the d_cities directory, the name_full field might be required (the field, for example, contains the full address of the city, indicating the country and region).
lov_return_to_column. Determines which field to substitute the selected value into. If, for example, the “Dropdown List” editor is specified for the city field, the system by default will look at what keyword this field has, i.e., through which field the connection with the reference book is carried out, and realizing that it is city_id, it will set the selected value from the list exactly there. But sometimes this behavior needs to be overridden.
select_search_columns. Allows specifying fields separated by commas through which the search in the reference book will be carried out (in the dropdown list there is an input field for filtering values). By default, the search goes by the field specified in return_name.
select_autocomplete_columns. Used when working with an autocomplete list. Often, when filling out a reference book, it is not enough to just specify one field, but several need to be filled. In this case, the system needs to know what other fields need to be filled for the addition to be successful. You can list these fields separated by commas.
I’m not sure if this mechanism works in the current version of the kernel.
sort_no. An important parameter that determines the sequence of columns in the table. It can be changed through the context menu in the field settings of a class or client object “Set column position”.
There is an important feature to consider when sorting. Fields using another field as a connection key (refers to virtual fields that are pulled from other tables via JOIN, using the key specified in “keyword”) must be located after this key.
In addition, you may have fields that are connected via JOIN through several tables (they have the “join_table” parameter specified), such fields must be located after one of (any) virtual field using the table through which the connection is made. If the connection is made through several tables, then accordingly there will be several fields that should be located before.
I think in the future the kernel will be improved and the JOIN order will be determined automatically, but for now this limitation should be taken into account.
type, field_length. System fields defining the type and length of the field as required by the DBMS. They are filled in tables.json and are not edited through the interface.
If you created with the wrong type, the field should be removed from tables.json, synchronized, and created again.
lov_columns. Currently not used.
filter_type (filter_type_id). Allows choosing what type of filter this field should have. Filters appear in the table client component if there is at least one field with a filter type set. If no filter type is selected, there will be no filter for this field.
Filters are selected based on the field type. This can be a range of numbers, date, date and time, checkbox, text (exact match), textLike (partial match), dropdown list, and dropdown list with an empty value.
The dropdown list works based on existing data, i.e., there will be only those unique values that occur in the data of this table.
There is a desire to provide the possibility of switching the mode so that for fields related to reference books, for example Status, the request is exactly to the reference book, and not a data request with grouping by this field. Но это не редко нужно (But this is not infrequently needed).
In addition, in one project, back in the first version of the kernel, these filters were improved (will be moved as needed):
The list provides not only unique values but also a count of occurrences, for example, Status: Created(5), In Progress (8)
And also it is possible to specify a filter based on data in a separate table with a one-to-many relationship, for example, the virtual field Executors can refer to the OrderExecutors table and provide unique values from there.
Multiselect. Allows selecting several values.
type_of_editor (type_of_editor_id). Similar to the filter type, but determines which editor this field will have for editing/creation. Used in client components (forms, frames, tables). Can be text, wysiwyg, textarea, number, dropdown list if it’s a virtual field pulled from another table, checkbox, date, date and time, days of the week (not sure if it works correctly), image (allows selecting an image with preview), file (allows selecting a file), phone (not sure if it works correctly), icon (don’t know how it works).
It is possible to write new editors, and it is also possible at the level of a specific client object (its js file) to override the behavior and write something custom.
quick_search_field. The checkbox determines that this field will be searched when entering text in the quick search bar in the table client component or when calling the search method. By default, it is set for the id field.
visible. Determines the visibility of fields for client components. If visible=false, then this, firstly, will be reflected in the profile, and secondly, this field will not be returned by the get method.
It is important to understand that this does not affect add/modify operations; there are separate checkboxes for them.
required. Determines that this field is required to be filled when adding a record. This is checked on the backend, and also client components of forms, frames, and tables highlight these fields with an asterisk and when trying to save without filling.
editable. By default = true. Determines whether this field can be edited (specified during record creation or changed afterwards). Checked on the backend, and client components display them either with an editor or without.
The checkbox determines the prohibition (when editable=false) on editing for requests from the client, so you can change this field from other methods on the backend side. This is a common practice when a field cannot be changed directly, but there is a separate method (for example, with limited access) leading to its change, possibly with some checks or side effects.
To restrict editing, including on the backend side, there is a server_editable checkbox.
server_editable. As stated above (in the description of the “editable” field), restricts editing access (add/modify) for requests from backend methods, not from the client.
insertable. By default = false. The checkbox is similar to “editable”, but applies only to addition. To prohibit addition, both checkboxes must be false.
By analogy with “editable”, it applies to requests from the client.
server_insertable. As stated above (in the description of the “insertable” field), restricts addition access for requests from backend methods, not from the client.
updatable. By default = false. The checkbox is similar to “editable”, but applies only to change. To prohibit change, both checkboxes must be false.
By analogy with “editable”, it applies to requests from the client.
server_updatable. As stated above (in the description of the “updatable” field), restricts change access for requests from backend methods, not from the client.
queryable. Fields restricted by this parameter (queryable=false) are not returned in the getProfile request and are not returned to the client in the “get” method, however, they are returned in “get” in requests from other methods on the backend.
In practice, this is only used in the internal mechanism of dynamic fields.
whereable. Allows prohibiting the application of selection conditions for a specific field.
from_table, keyword, return_column. Used only for is_virtual=true fields. Allow specifying from which table, by which key, and which field to return for fields pulled from other tables. The query is formed by the kernel using JOIN. Filled in tables.json and should not be edited through the interface.
For connections through several tables, there is a “join_table” field, see below.
keyword with substitution. Seems not used now.
join_table. Allows making a connection through one or more tables. This field specifies which table to join through, while from_table, as in the usual case, specifies which table should be attached.
It is important that the table specified in join_table was previously connected in another field. That is, first you have a field without join_table, but simply with from_table/keyword/return_column, and only after that there can be a field with join_table/from_table/keyword/return_column, where join_table will be equal to from_table of the previous field.
If the connection goes through several tables, then each previous one must be previously also represented.
Let’s look at an example. An order table, it has a “user” field, from the user table, and the user has a “gender” field, from the gender table. We want all these fields to be in the order table:
We add user_id (physical field for connection)
We add the user_nickname field to see who it is. is_virtual=true; from_table=“user”; keyword=“user_id”; return_column=“nickname”.
We add the user_gender field. is_virtual=true; join_table=“user”; from_table=“gender”; keyword=“gender_id”; return_column=“name”.
The keyword field for a field connected through one or more tables is specified as a connection key in the second to last table, that is, in the one specified in join_table. In this example, we see that we are attaching the “gender” table from the “user” table, and in it exactly “gender_id” allows connecting to the “gender” table.
join_table_alias, join_table_by_alias. Used when an external table is connected more than once for two different fields. join_table_alias is used to specify an alias of the connected table (specified in from_table), and join_table_by_alias is specified for the next connected table, informing that for the connection exactly “that JOIN” whose alias is equal to the specified one should be used.
For example, in the order table there are two fields supplier_id and customer_id, and I want to also pull nickname and gender for each. I will have:
For supplier
supplier_id field, physical.
supplier_nickname field. is_virtual=true; from_table=“user”; keyword=“supplier_id”; return_column=“nickname”. Also let’s set an alias for it: join_table_alias=“user_supplier”.
supplier_gender field. is_virtual=true; join_table=“user”; from_table=“gender”; keyword=“gender_id”; return_column=“name”. Also let’s set for it exactly which connection (since there will be two “join user”) should be used to connect this table: join_table_by_alias=“user_supplier”.
Now the same for customer.
customer_id field, physical.
customer_nickname field. is_virtual=true; from_table=“user”; keyword=“customer_id”; return_column=“nickname”. Also let’s set an alias for it: join_table_alias=“user_customer”.
customer_gender field. is_virtual=true; join_table=“user”; from_table=“gender”; keyword=“gender_id”; return_column=“name”. Also let’s set for it exactly which connection (since we have two “join user”) should be used to connect this table: join_table_by_alias=“user_customer”.
table_alias. Do not use table_alias, it is a system field.
dynamic_field_id. System field used for dynamic fields.
modify_in_ext_tbl, modify_in_ext_tbl_key. Used for the dynamic fields mechanism. Allows implementing an editor for data stored in another table. The mechanism, in principle, can be used not only for dynamic fields, but only if it is needed and it will require delving into the implementation.
is_virtual. Always specified for fields that are pulled from other tables (see from_table/keyword/return_column), but can also be used for other types of virtual fields, such as CONCAT (see concat_fields).
concat_fields. Allows specifying separated by a comma or a space what needs to be concatenated. If the system detects at least one comma, it will assume that it needs to be separated by commas, if not, by a space. Better use commas.
Each element can be just a string or a field name. More precisely, if there is a field with such a name, it will be substituted, otherwise it will be substituted as is (of course with escaping). If a space needs to be specified, it must also be between commas. For example, fio:
"fio" : {"type": "varchar", "length": "255", "concat_fields": "lastname, ,firstname, ,midname", "is_virtual": true, "name": "Full Name"},
And, for example, for the password field we just display “*”:
"password": {"type": "varchar","length": "255", "concat_fields": "*", "name": "Password", "is_virtual": true},
extraSQL. In the concat_fields field, “extraSQL” can be specified. Then the system will allow substituting its sql into this field, however, it must be defined at the stage of the init method of the class. That is, it should be overridden for the class and extraSQL should be entered there in the “profile” of the corresponding field, and also specify which fields this sql depends on (dependCols) so that the system can collect the necessary joins and work correctly with the cache.
This is better seen in an example:
export default class Order_ extends CoreClass {
private initSuper: (params) => Promise<IError>
constructor(params: IObj) {
super(params)
this.initSuper = super.initPrototype
}
/**
* Overriding the init method.
* Here we define extraSQL for the "from_user" field to concat fio or nickname,
* RU:
* Переопределение метода init.
* Здесь мы определяем extraSQL для полей "to_user" для конкатенации fio или nickname,
* @param params
*/
async init(params): Promise<IAPIResponse> {
const res: IAPIResponse = await this.initSuper(params)
if (res.code) return res
const fromUserColProfile = this.class_fields_profile['from_user']
const toUserColProfile = this.class_fields_profile['to_user']
if (fromUserColProfile) {
fromUserColProfile.extraSQL =
`CASE
WHEN \`user2\`.\`use_nickname\` = 1 THEN \`user2\`.\`nickname\`
ELSE CONCAT_WS(' ', \`user2\`.\`lastname\`, \`user2\`.\`firstname\`, \`user2\`.\`midname\`)
END`
fromUserColProfile.dependCols = [
'from_user_id', 'use_nickname'
]
}
if (toUserColProfile) {
toUserColProfile.extraSQL =
`CASE
WHEN \`user1\`.\`use_nickname\` = 1 THEN \`user1\`.\`nickname\`
ELSE CONCAT_WS(' ', \`user1\`.\`lastname\`, \`user1\`.\`firstname\`, \`user1\`.\`midname\`)
END`
toUserColProfile.dependCols = [
'to_user', 'use_nickname'
]
}
return res
}
}
This mechanism allows working with this field as if it were stored in the database physically (well, or formed in a VIEW), both in the end components (tables/forms/frames) and when receiving and working with data in other methods on the backend side.
default_value. Allows specifying a default value for the field. That is, when creating a record, if no value is passed for the field, but it has a default_value specified, then the specified value will be substituted.
You can also use this field for virtual fields, for example, to specify a default value for a status (which is taken from the status reference book). Instead of specifying some number for the status_id field, you can specify a system name (in reference books like status, we always make a “sysname” field), that is, for the “status_sysname” virtual field, we can specify default_value=“CREATED”, then during creation, the system itself will refer to the status reference book (the one specified as from_table for the status_sysname field), get the ID of this status, and substitute it into the status_id field.
validation. String. Allows specifying the name of the function that will perform validation. Standard functions are available in the functions.ts file in the validation object (isDate, notNull, number, url, email). But you can define your own as a class method (this.myValidateFn) and specify “myValidateFn” in validation.
To see how to write it, look at existing examples. But besides the function itself, you should write an example and add it (without touching CoreClass) to this.validationFormats.
number: {
format: '<number>',
example: '10'
},
In the class itself, write this.validationFormats.myValidateFn = {format:‘AABBCC’, example:‘AABBCC’}.
This is required so that the validation error message is clear.
When a record does not pass validation (for one or more fields), the method (add/modify) will return an error with the object {message: ‘One or more fields has an incorrect format’, fields: not_valid}, where not_valid is an array of objects of the form {field: field, format: this.validationFormats[valFunc] || ‘’}.
get_formating, set_formating. Allows specifying a special function for formatting during retrieval and saving. It is important to note that such functions are applied by the system automatically depending on the field type (for example, a date is reformatted from the MySQL format to user-friendly and back), but standard processing can be replaced. Used rarely.
is_unique. The system ensures that the combination of fields marked with this checkbox is unique. You can also enable additional tracking at the DBMS level - see mysql_unique.
hint. Here you can specify hint text that will be shown when hovering over a field (column) in client components (tables/forms/frames). Can also be used in custom components.
min_value, max_value, value_step. Defines the limits and step for numeric fields, however, in the current version, it is not used anywhere (for some reason neither in tables, nor in forms/frames, nor on the backend). It will be improved if necessary.
min_datetime_value, max_datetime_value, default_datetime_value. Allows defining the minimum and maximum boundaries for date and date/time format fields, as well as specifying a default value. Implemented in the frame client component and allows using substitutions now (current date and time) or now_date (current date).
If necessary, other client components can be improved, as well as backend verification implemented.
calender_options. Allows specifying custom settings for the calendar (date and time picker component). Documentation here: https://flatpickr.js.org/options/ (version may be outdated).
is_inherit. Allows specifying that this field is inherited. This means that if there is no value of its own, then the value of the same field of the nearest parent that has this value can be returned to this field. This will work if for the class/client object the mode is enabled, see enableInheritValues.
is_class_field, is_co_field. System fields.
save_log, always_save_log. Mark fields for which it is necessary to keep a change history. See /docs/gocore-v2.0/kak-razrabatyvat/sushchestvuyushchie-klassy-i-ih-metody/bazovyy-klass/metody-bazovogo-klassa/history.
Fields additionally marked with the always_save_log checkbox will be saved not only when they change, but with any other tracked fields. It is not certain that this is needed in the current implementation (previously the date field was marked with such a feature, now the date is logged anyway).
For the mechanism to work, you need to create an additional table for the class. See the mechanism description.
depend_column, is_depend_where_func. Used for the frame client component. Allows specifying which field this field depends on (it will be unavailable until the source field is specified). You can also specify the name of the function that will allow forming the where that will be applied to the query to obtain the dropdown list of this field (based on the data set in the dependent field). An example of such functions is in frame_example.
frame_for_edit_values. System field, allows (for dynamic fields) to specify the frame that will be opened for editing the value.
Support in tables is implemented.
Perhaps, it can be used not only for dynamic fields, but also for others, if you want to make a custom field editor.