<datastore ... />
Невизуальный тэг, отвечающий за работу с источником данных.
Синтаксис
datastore умеет выполнять 5 команд: refresh, delete, update, insert, check-unique. Для каждой команды свой вложенный тэг.
Полная запись:
<datastore master="..."
master-link="..."
onBeforeDelete
onAfterDelete
onBeforeInsert
onAfterInsert
onBeforeRefresh
onAfterRefresh
>
<refresh source-type="sql | webdb"
table-name="..." id-field="..."
where="..." order-by="..." group-by="..." having="..."
name="webdb_command_name"
method="...">
SQL
</refresh>
<delete source-type="sql | webdb"
table-name="..." id-field="..."
where="..."
name="webdb_command_name"
method="...">
SQL
</refresh>
</datastore>
, где refresh.name по умолчанию: sql: «select * from » + table-name | webdb: «$» + table-name + ».view»
delete.name по умолчанию: sql: «delete from » + table-name + » where » + id-field + »=…» | webdb: «$» + table-name + ».delete» (id записи передается в параметре с именем id-field)
refresh.method, delete.method - ручные методы выполнения команд для сложных случаев
source-type - для каждого действия может быть свой. Как следствие, большая гибкость в работе.
master-link пишется в формате: sql: «local_field1:master_field_with_value1, local_field2:master_field_with_value2, …» | webdb: «param_name1:master_filed_with_value1, param_name2:master_field_with_value2, …»
Краткая запись:
<datastore table-name="..." id-field="..." source-type="..." master="..." master-link="..." name="webdb_refresh_command_name" where="..." order-by="..." group-by="..." having="..."> SQL </datastore>
здесь table-name, id-field, source-type - копируются во все тэги (<refresh>, <delete>)
Среднекраткая запись (префикс атрибута - это вложенный тэг):
<datastore refresh-table-name="..." refresh-id-field="..." ... delete-table-name="..." delete-type="..." ... ... >
Таким образом можно читать/писать в атрибуты вложенных тэгов.
Атрибуты
Основные атрибуты (R/W):
| Название | Тип | Описание |
|---|---|---|
| id | string | Идентификатор объекта. |
| source-type | db | webdb | none | Тип источника данных. db - работа с СУБД, webdb - работа с прикладным вэб-сервером, none - генерация пустой таблицы размерностью datastore.cols x datastore.rows (если они указаны) |
| cmd | string | Имя команды на Веб-сервере, в случае работы с WebDB |
| query | string | Задает объект запроса для общения с СУБД. |
| connect | string | Задает объект типа connect. |
| sql | string | Текст запроса. По умолчанию, sql=«select * from » + <table-name>. Т.е. достаточно задать table-name и сделать refresh.  Внимание! Если использовать параметры (%param_name) в запросе (см. Передача параметров в объекты) то следует обязательно здесь же в описании <view> задавать начальные значения параметров, при которых запрос будет считаться корректным с точки зрения драйвера СУБД. Причина этого в том, что при создании <view> автоматически выполняется команда refresh (в противоположность <query>, который ждет явную команду execute). |
| table-name | string | Идентификатор объекта. |
| id-field | string | Имя таблицы. Необходимо для выполнения операции «удалить запись». |
| cols | string | Регулирует кол-во колонок. |
| rows | string | Регулирует кол-во строк. (Рекомендуется использовать при описании view, в то время как add-row - во время работы) |
| master | string | Ссылка на master datastore, datastore_id или view_id |
| where | string | соответствующий кусок sql-запроса |
| group-by | string | соответствующий кусок sql-запроса |
| having | string | соответствующий кусок sql-запроса |
| order-by | string | соответствующий кусок sql-запроса |
| master-link | string | для организации связи master-detail sql: «local_field1:master_field_with_value1, local_field2:master_field_with_value2, …» webdb: «param_name1:master_filed_with_value1, param_name2:master_field_with_value2, …» |
| parent-field | string | имя поля для возможности автоматического добавления новых дочерних записей в БД. |
| last-generated-id | string | Возвращает последний сгенерированный id после сохранения новой записи. |
| rows | number | Кол-во строк для ручной генерации пустой таблицы. |
| cols | number | Кол-во колонок для ручной генерации пустой таблицы. |
Событийные атрибуты (R/W):
| Название | Тип | Описание |
|---|---|---|
| onBeforeRefresh | code | Событие возникает перед обновлением. Правила описания см. (Описание событий в ApplicationXML). |
| onAfterRefresh | code | Событие возникает после обновления. Правила описания см. (Описание событий в ApplicationXML). |
| onEmptyRefresh | code | Событие возникает при пустом результате запроса. Правила описания см. (Описание событий в ApplicationXML). |
| onBeforeDelete | code | Событие возникает перед удалением записи. Правила описания см. (Описание событий в ApplicationXML). |
| onAfterDelete | code | Событие возникает после удаления записи. Правила описания см. (Описание событий в ApplicationXML). |
| onErrorDelete | code | Событие возникает, если sql-сервер вернул ошибку. Правила описания см. (Описание событий в ApplicationXML). |
datastore.checkUnique.onBeforeCheckUnique
datastore.checkUnique.onAfterCheckUnique
datastore.checkUnique.onErrorCheckUnique
datastore.update.onBeforeUpdate
datastore.update.onAfterUpdate
datastore.update.onErrorUpdate
datastore.update.log-datetime
datastore.update.log-datetime-field
Описание
Поддерживается связывание datastore по принципу master-detail.
Связывание описывается фактом вложения одного <datastore> в другой:
<datastore id="ds1" table-name="order_client">
<datastore id="ds2" table-name="order_client_detail" master-link="order_id:id"/>
</datastore>
Во вложенном datastore будут загружены записи, связанные с первой записью верхнего datastore.
Количество вложений (связей master-detail) неограниченно.
Рекомендации по использованию datastore:
Если используется ручная установка данных view.setData(), то следует самостоятельно ставить курсор на первую запись.
Если используется datastore, он сам позаботится об этом.
Поддерживается зарезервированное слово 'last' в качестве первого индекса массивов datastore (view), query.
Поддерживаются параметры вида %my_param в произвольном месте sql-запроса. Подставляются значения, переданные в <datastore> в виде param:my_param=value.
Поддерживаемые методы
size
size() - кол-во записей.
where
where(hash) - добавить дополнительное динамическое условие в секцию where в формате: local_field_name ⇒ value. Строковое value нужно добавлять с кавычками.
save
save() - сохранить изменения в текущем datastore и подчиненных ему в БД.
refresh
refresh() - обновить содержимое datastore. Содержимое подчиненных datastore будет обновлено автоматически (для первой записи в master datastore).
refreshSlaves
refreshSlaves() - обновить содержимое подчиненных относительно данного datastore.
refreshSlaves(rowNum) - обновить содержимое подчиненных относительно записи номер rowNum данного datastore.
addSlave
addSlave(datastore) - добавить новый datastore в список подчиненных. возвращает список подчиненных datastore.
removeSlave
removeSlave(datastore | id) - удалить указанный datastore из списка подчиненных. возвращает список подчиненных datastore.
getSlaves
getSlaves() - возвращает список подчиненных datastore.
setParentDatastore
setParentDatastore(datastore) - установить связь данного подчиненного datastore с родительским (master).
getUpdatingId
getUpdatingId() - возвращает id записи, которая в данный момент обрабатывается (при удалении/обновлении/добавлении).
clearParams
clearParams() - очищает значение параметров datastore. (Нужно вызывать вручную перед установкой параметров datastore, в случае работы с WebDB)
setParam
setParam(param_name, value) - установка параметра datastore. (в случае работы с WebDB)
restoreById
restoreById(id_value_of_record) - возвращает запись из буфера удаленных записей в первичный буфер.
getMetadata
getMetadata() - возвращает метаданные.
getMetadata().addStringColumn(column_name) - добавляет колонку строкового типа.
getMetadata().addNumberColumn(column_name) - добавляет колонку целочисленного типа.
getMetadata().addDecimalColumn(column_name) - добавляет колонку числового типа с плавающей точкой.
getMetadata().addDateColumn(column_name) - добавляет колонку типа date.
getMetadata().addTimeColumn(column_name) - добавляет колонку типа time.
getMetadata().addDatetimeColumn(column_name) - добавляет колонку типа datetime.
