The records skill
records reads the lists of the form the user is working on. Two actions, neither of which asks first - they change nothing but the record shown:
| Action | What it does |
|---|---|
count_records | How many records a list has, as it is filtered now, and the filter |
find_record | Moves a list to the record the user names, by its code or its description, and reports its values |
It answers "how many customers are there in Lombardy?" with the number the user sees, and turns "edit the customer Rossi" into two steps of the model: find_record brings Rossi, then fill_form with mode = edit changes it.
What a list is
A list is a data set the form shows. The skill finds it as:
- a control that shows a data set as a whole: one with a published
DataSourceand noDataField- aTDBGrid, aTDBNavigator, aTDBCtrlGrid, and the grids of third parties built the same way. Its id is the name of the control (grdCustomers); a grid wins over a navigator of the same data set, because it has the columns; - a grid or a list a LiveBindings link fills with a data set (
TLinkGridToDataSource,TLinkListControlToField: aTStringGrid, a list box, a list view) and aTBindNavigator, in the VCL and in FireMonkey: the data set of their bind source; - the record of the form: the data set behind its data-aware fields, even when no grid shows it - a card that edits one customer at a time is a list of customers too. Its id is the name of the data set.
Each list appears once, however many controls show it, and the visible ones only. They are also listed at the end of describe_form:
Lists: grdCustomers (Customers: 120 record(s), filtered by: Region = 1).count_records
With no list named, every list of the form is counted; with one, that list:
grdCustomers: 34 record(s), filtered by: Region = 1.The number is the RecordCount of the data set, that is what the user sees after their filter - which is why the filter is reported with it: "34 customers" is true of the list on the screen, not of the database. A data set that cannot tell (a unidirectional one) reports an unknown number of records; one that is closed says so.
find_record
The model passes the text, and optionally the field and the list (the first list of the form, when it does not name one).
The fields it searches are the ones the user sees: the visible columns of the grid, or the visible text, number and date fields of the data set when no grid shows it. With a field named
- by name or by its label - that field alone.
The order it searches in is the one a person would follow:
- the same value, case apart, in any of those fields (
LocatewithloCaseInsensitive): the code "C2" finds the record whose code is C2 before one whose name contains C2; - then a value that starts with the text, in the text fields (
loPartialKey): "rossi" finds Rossi Srl.
A value of the wrong type for a field (a word in a numeric code) is skipped, not an error. The answer gives the record found, with the values of up to ten of those fields - or none, with HideFieldValues:
The list grdCustomers is on the record found for "rossi". Code = C2, Company = Rossi Srl,
Region = Piemonte.The one thing it refuses
It never moves a list whose record is being edited. On a data set in insert or edit, moving to another record posts the one being edited - the user's changes, or the values the assistant has just filled, would be saved without anybody pressing Save. So find_record stops, says the record is being edited, and that the user saves it first or cancel_edit abandons it. The same holds while a detail of the list is being edited: a master that moves posts the detail record, so find_record names the detail and stops.
A field shown in a password edit is neither searched nor reported with the record found.