6. Rows identification
Different ways of unique identification of rows
Setting row id attribute
- See documentation for Setting row id attribute.
- This is the basic option. Set
id
attribute of every row to unique string. This string can contain all letters and '_' (a-zA-Z_).
- New row will get its id attribute generated also from these characters. The new generated id is always the highest id (by alphabet order) in the grid.
- Rows without the id attribute set and rows with duplicate id value will get automatically generated id as ARxxx, where xxx is auto incremented index starting from 1. The 'AR' can be changed by AutoIdPrefix attribute.
Group rows generated by grouping will get auto generated id as GRxxx. They can be more controlled by GroupIdValue and GroupIdPrefix attributes or by API OnCreateGroup.
- It is possible to show the row id in column named 'id', but this column must be set as CanEdit='0'.
- The row id must not be changed directly API.
To have editable/changeable id use unique editable column as described in the below example "3 - One editable column as unique id".
Generating id attribute for new rows
- See documentation for Setting row id attribute.
- You can set characters that will be used to generate id by <Cfg:
IdChars
attribute.
The characters will be used in the order they are stored in the string IdChars. The IdChars must not contain character '$'.
- If you want to generate number id, you can set <Cfg IdChars='0123456789'
NumberId
='1'/>.
- If you want to start new ids from some id value, you can set <Cfg>
LastId
attribute to the id value before the first generated new id (e.g. LastId='158', the new ids will be 159,160,161,...).
- You can also use LastId in server paging, because client TreeGrid does not know the highest id in the grid on server side.
- You can set prefix and postfix that are added to new id by <Cfg> IdPrefix and IdPostfix attributes.
If you set prefix and/or postfix, all your ids (and also LastId if used) must contain them too!
One editable column as unique id
- See documentation for Using one or more (editable) columns as row identity.
- You can identify your rows by any string and let user to set or change this unique identifier manually in some editable column.
TreeGrid ensures that all ids will be unique by appending generated postfix to changed ids in this column. Note, on start all the values in the source ids column must be unique.
- Set <Cfg IdNames='ColName' AppendId='1' IdChars='0123456789' NumberId='1'/>
IdNames
contains column name where your unique identifier is set, this column is usually used as primary key in your database table. IdNames must not contain 'id' column name.- When user adds new row or changes value in id column to not unique id, the value will be regenerated according to
AppendId
value.
If AppendId='1' to the existing or default value will be appended generated postfix.
If AppendId='0' the value will be overwritten by new generated id, but remember, in this case all the values must contain only characters from IdChars.
In the case the value is automatically changed there is called API event OnChangeId.
-
The row id attribute is not changed immediatelly after the editable unique column is changed. The row id is changed after the changes are sucessfully uploaded to server or AcceptChanges API method is called.
- You can set IdChars and NumberId to different values to generate other prefixes.
- You can set LastId to start from another index, for example LastId='1' starts from index '2'.
- You can set IdCompare='4' if your unique identifiers are case insensitive.
- Remember, if source ids column value contains '$', this character is converted to '_' in generated id, because id attribute cannot contain this character.
Row id in tree
- See documentation for Row id in tree.
- By default the row id attribute does not include any information about row position in tree, so it must be unique among all rows in grid, regardless on their level.
- You can set <Cfg>
FullId
='1'. Now all row ids contain parent's id attribute as prefix, separated by '$'.
In deep tree, row id contains all parent's ids, because row's parent also contains its parent id.
-
Initial row id attribute can contain the parent ids separated by $ or it can contain only the last part - so the initial id is unique only inside its parent.
After the grid is loaded, all the row id attributes are converted to the full id with parent ids. To server is uploaded always the full id.
-
The row id attribute is not changed immediatelly after the row is moved or editable unique column is changed. The row id is changed after the changes are sucessfully uploaded to server or AcceptChanges API method is called.
If you want to upload also the new id value that will be set to the row, set <bdo/<treegrid Upload_Flags='NewId' ... >. It will be uploaded in NewId attribute of the changed row.
- All other attributes can be used in the same way as in previous examples.
More (editable) columns as unique id
- See documentation for Using one or more (editable) columns as row identity.
- You can identify row by more row attributes. You can set their names as comma separated list to <Cfg>
IdNames
attribute.
-
When user adds new row or changes value in some identifier column and the id will became nonunique, the last attribute value (from the IdNames) will be regenerated.
Therefore the last item in IdNames must be column name. But the column need not be editable or visible.
- Other items in IdNames can be column names (editable or read only, visible or hidden), standard row attributes like Def or any user defined attribute filled in <I> tag.
- The attributes in IdNames must not be 'id' attribute or any array attribute like Enum or Defaults.
- The unique id attribute generated from the IdNames contains all their values separated by '$'.
-
The row id attribute is not changed immediatelly after the editable IdNames column is changed. The row id is changed after the changes are sucessfully uploaded to server or AcceptChanges API method is called.
- Other id attributes like FullId, AppendId or IdChars can be used in the same way as in previous examples.
Custom id generated by API
- See documentation for API for row ids.
-
It is possible to generate new id by client side JavaScript by API event OnGenerateId or OnSetRowId.
-
OnGenerateId
generates or modifies unique part of the row id.
If set FullId it controls only the row id part, not its parents part.
In more editable columns as id it controls only the last column value as unique part.
For other settings it controls the whole id like OnSetRowId.
-
OnSetRowId
generates or modifies the complete row id set to the id attribute.
-
This example uses OnGenerateId event to generate GUID, see the <script> in this HTML code (06-Rows_identification.html).
Custom id generated on server side
- See documentation for NewId attribute.
-
If the row id must be generate on server side, e.g. by SQL database, the server can change the row id and return it back to the grid.
-
The server returns the changes in <Changes> tag in row's attribute
NewId
- Simple server response changing one row id looks like:
<Grid><Changes><I id='orig id' Changed='1' NewId='new id'/></Changes></Grid>
Where the 'orig id' is the row id generated by TreeGrid and the 'new id' is the new row id generated by server.
-
This example uses simulated server response generated in client side script in OnDataSend API event. It is used just to avoid server code in many server script languages.