Platex-классы и функции

Приложения АСР Platex® используют внутренние механизмы для работы с базой данных, поэтому для системы отчётов используются соответствующие обёртки на наборы данных. Эти обёртки есть наследники от класса TfrxCustomDBDataSet, описание которого можно найти в справочной системе FastReport, и используют текущее подключение к базе данных для выборки данных. Существуют четыре типа обёрток:

•контейнер (TplxContainer);

•контейнер с условием (TplxContainerEx);

•запрос (TplxQuery);

•однопроходной запрос (TplxSinglePassQuery).

Иерархия Platex-классов для выборки данных из БД

Первые два типа считаются устаревшими и не рекомендуются к использованию, однако стоит описать их особенности.

TplxContainer – это набор данных, который можно связать с любыми табличными данными, используемыми данным приложением. Через свойство TableName выбирается таблица из списка (для каждого из приложений этот список свой). Управлять данными, которые будут доступны через TplxContainer нельзя, список доступных полей определяется разработчиком приложения (разработчик шаблона не может добавлять свои поля).

TplxContainerEx – является расширением TplxContainer, единственное и основное его отличие заключается в том, что разработчик шаблона может указать произвольное условие для выборки данных из БД, либо полностью составить произвольный запрос, однако список доступных полей определяется, как и в TplxContainer, разработчиком приложения.

TplxQuery – это произвольный набор данных. Разработчик шаблона может составить произвольный запрос и указать произвольное условие. Список полей будет получен после выполнения запроса, т.е. в RunTime шаблона; из дизайнера список полей не доступен (однако этот факт не запрещает обращаться к полям набора данных).

TplxSinglePassQuery - это ограниченный по функционалу произвольный набор, данные которого доступны только в один проход по НД. Этот класс имеет смысл использовать только в тех случаях, когда надо отобразить очень большое количество записей (например, более миллиона).

Стоит обратить внимание на следующие свойства наборов данных:

.OpenDataSource – определяет, надо ли автоматически открывать набор данных (т.е. делать запрос к БД). Для тех наборов данных, у которых запрос и/или условие статичны (т.е. не определяются в момент прогона шаблона), это свойство можно оставить равным True, для остальных случаев его надо сбрасывать в False.

.Filters – список простых фильтров. Одна строка – один фильтр. Формат такой: field_name=value, где field_name – имя фильтруемого поля, value – значение фильтра. Все фильтры объединяются логической операцией AND.

.SortByFields – список (разделённых точкой запятой) полей, по которым необходимо отсортировать данные.

.SortMode – направление сортировки (по возрастанию или по убыванию).

.Master, .MasterPKFields, .MasterFKFields – свойства, которые позволяют задать отношение главный-детальный (master-detail) между двумя наборами данных, используются для построения соответствующих отчётов. Master – указывает главный набор данных, MasterPKFields – список (разделённых точкой запятой) полей первичного ключа главного набора данных, MasterFKFields – список (разделённых точкой запятой) полей данного набора данных, по которым строится отношение главный-детальный.

.SQLSelect – запрос, который будет выполняться к базе данных.

.WhereCondition – условие, которое будет применяться к запросу перед его выполнением.

В запросе SQLSelect можно указать макросы, которые будут заменяться на условие WhereCondition по следующим правилам:

Если SQLSelect не содержит секции WHERE и не содержит ни одного из перечисленных макросов, но при этом задано условие WhereCondition, то это условие автоматически добавляется к SQLSelect.

Иерархию классов и дополнительные свойства и методы, можно посмотреть в плавающей панели Дерево данных, во вкладке Классы:

Классы и их свойства, доступные скриптовой системе

В скриптовой части шаблона доступны дополнительные свойства и методы наборов данных:

.Container: TbuDataContainer, ссылка на экземпляр класса, который отвечает за выборку данных из БД, за хранение их в оперативной памяти компьютера; через этот класс можно на прямую обращаться к выбранным данным.

.CurrentRecord: TbuRecord, ссылка (указатель) на текущую запись. Текущая запись может быть изменена в скрипте явно. Например, так:

var
  R: TbuRecord;
begin
  //поиск записи, у которой поле id равно 5.
  if Query1.Locate('id', [5], R) then
    Query1.CurrentRecord := R; //установка текущей записи 
end;

либо так:

begin
  Query1.First;           //переход к первой записи в наборе данных
  while not Query1.Eof do //пока не будет достигнут конец данных
  begin
    // добавление строки в комбобокс:
    ComboBox1.Items.AddObject(
      Query1.Value('name'), TObject(Query1.Value('id')));
    Query1.Next;          //переход к следующей записи в наборе данных
  end;
end;

либо изменяется движком FastReport во время прогона отчёта (когда набор данных связан с MasterBand’ом).

.FieldByName(name: string): TbuField, – default-свойство, по которому можно получить ссылку на экземпляр класса, который определяет методы обращения к данным внутри записи. Пример использования:

var
  R: TbuRecord;
  s1, s2, s3: string;
begin
  if Query1.Locate('id', [5], R) then
  begin
    // т.е. FieldByName – defaul-свойство, можно использовать так:
    s1 := Query1['name'].AsString[R];
 
    // это эквивалентно обращению:
    s2 := Query1.FieldByName('name').AsString[R];
 
    // также можно получить значение по текущей записи:
    Query1.CurrentRecord := R;
    s3 := Query1.Value('name');
 
    // s1, s2 и s3 будут равны
  end;
end;

.Locate(FieldNames: string; Values: array of variant; var ResultRecord: TbuRecord): Boolean, метод для поиска записи. FieldNames – имена полей, разделённых через точку с запятой, Values – список искомых значений, ResultRecord – ссылка на найденную запись. Если запись найдена, метод Locate возвращает True, если нет – False и ResultRecord = 0. Если записей, удовлетворяющих критерию поиска, несколько – результатом может оказаться любая из этих записей. Примеры использования – см. выше.

Из скриптовой части шаблона доступны дополнительные функции, которые можно использовать для форматирования текста, конвертирования данных, либо для взаимодействия с приложением. Список доступных функций можно посмотреть в плавающей панели Дерево данных, во вкладке Функции:

Функции, доступные скриптовой системе

При выделении функции в этом списке ниже отображается описание.