что такое функция apex
Туториал по Oracle Application Express. Обзор IDE
Недавно я с удивлением обнаружил, что, оказывается, толковых туториалов по Oracle Application Express (он же APEX, он же апекс, но не путать с языком apex, который используется в Salesforce) в природе не существует.
Это не самая распространенная технология, конечно, но, тем не менее, довольно востребованная. Есть десятки блогов об апексе (англоязычные, в основном), пара тысяч вопросов на Stackoveflow, специальный раздел по апексу на официальных форумах оракла, сам апекс существует уже 15 лет и все время развивается. Я был уверен, что и хороших туториалов полно. Но нет!
Мне тут же пришла в голову гениальная мысль восполнить этот пробел.
Оглавление
Почему существующие туториалы — плохие
Я немного поясню, почему я считаю существующие туториалы плохими. Апекс — это не язык программирования, это такой очень высокоуровневый инструмент разработки, ближайшим идейным аналогом которого я бы назвал MS Access. Соответственно, большая часть разработки на апексе состоит из работы с веб-интерфесом этой среды: нажимания на кнопки, перехода по ссылкам, заполнение полей с названиями компоментов, выбора значений из списков и так далее. Что делает типовой туториал? Он показывает скриншоты этих самых экранов с подписями «нажмите туда-то». При этом сама IDE достаточно удобная и понятная, почти все элементы снабжены справочными пояснениями, есть встроенная помощь. В итоге, если нужно объяснить пользователю, как создать приложение, в туториале будет большой скриншот, объясняющий, как нажать на кнопку «Create a new app». Вот, посмотрите сами на официальный оракловый туториал:
Они бы еще объяснили со скриншотами, что «клик» — это однократное нажатие на левую кнопку манипулятора типа «мышь».
Конечно, полезная информация в таких туториалах тоже есть, но ее там крохи. Процентов на 80 туториалы состоят из таких вот скриншотов, причем по своему опыту я могу сказать, что человек, не читавший никаких туториалов вообще, самостоятельно найдет, как создать приложение, добавить страницу, поместить на нее отчет и так далее. А потом ему нужно будет организовать более-менее нетривиальное взаимодействие нескольких элементов апекса, и оказывается, что этот вопрос туториалом почти не покрывается. Приведу аналогию: вы только-только учитесь программировать, изучили переменные, массивы, циклы, условия, и получили задание, в рамках выполнения которого вам нужно отсортировать массив. Как-то отсорировать массив — достаточно просто, но как только задание усложнится до «отсортировать большой массив быстро«, окажется, что имеющихся у вас знаний недостаточно. Погуглив, покопав Stackoverflow и форумы, вы найдете алгоритм быстрой сортировки. Конечно, кто-то и сам переизобретет этот алгоритм рано или поздно, но более эффективным путем было бы сразу прочитать книжку с разбором типовых алгоритмов. И вот как раз такого набора «типовых алгоритмов» для апекса обычно нигде нет, а на помощь приходят те же самые метод научного тыка, поисковики, форумы и Stackoverflow (и, я надеюсь, этот туториал).
Вводная информация
Предполагается, что читатель знаком с Oracle Database версии хотя бы с 11-й, SQL, PL/SQL и особенно с тем, что такое EXECUTE IMMEDIATE и как оно работает.
IDE апекса значительно изменилась при переходе с версии 4.2 на 5.0 (релиз был как раз 4 года назад, в марте 2015-го). С тех пор IDE меняется мало, но иногда добавляются новые возможности. Я буду делать скриншоты на apex.oracle.com, где сейчас установлена версия 19.1, но если у вас где-то используется более ранняя версия (5.х, 18.х), вы без труда найдете нужный элемент, если только он не появился в более поздней версии, чем ваша.
Я начну с обзора наиболее часто используемых разделов IDE. Я тоже покажу несколько скриншотов. Куда же без них, раз всё здесь сделано из визуальных компонентов. Но их будет не так много, как в плохих туториалах, и в основном они будут в начальных главах, а дальше я буду просто указывать название раздела IDE, в котором находятся необходимые вещи. Сразу обращу ваше внимание, что это просто первое знакомство с IDE. Более подробная информация о том, когда на какую кнопку нажимать и где что смотреть, будет дана дальше, когда я перейду к конкретным темам.
Обзор IDE
Стартовый экран, который вы увидите сразу после входа в IDE:
Главные элементы здесь — это 4 большие кликабельные картинки:
В меню в самом верху страницы продублированы эти же 4 пункта.
Кроме этого, есть еще несколько малополезных вещей: ниже есть некоторое количество статистической информации (типа наиболее часто редактируемых приложений или наиболее активных разработчиков). И есть колонка справа, где также немного статистики и дополнительных ссылок.
Рассмотрим App Builder и SQL Workshop подробнее.
App builder
Эта страница выглядит примерно вот так:
Основные элементы этой страницы: четыре большие кнопки как на предыдущей странице, список уже имеющихся приложений, правая колонка со списком последних измененных приложений и дополнительными действиями. Четыре кнопки — это:
Так же хочу обратить ваше внимание на вот такую маленькую кнопочку в панели отчета:
Она переключает вид отчета с такого, как на скриншоте выше (с «картинками» приложений) на отчет в виде таблицы:
Похожие отчеты встречаются и в других разделах IDE. Я предпочитаю табличный вид, поэтому далее все скриншоты будут с ним.
Страница приложения
После того, как вы создадите приложение или откроете существующее, вы увидите следующую страницу (очень похожую на предыдущую по структуре):
На эту страницу вы будете заходить очень часто, и полезных функций здесь тоже очень много. Большие кнопки с картинками:
И две дополнительные кнопки, которые обведены оранжевой рамкой на скриншоте:
Application properties
Здесь прежде всего интересна организация доступа к большому количеству настроек.
Настройки сгруппированы в 4 группы (см. верхнюю рамку), а в каждой группе есть еще по нескольку подгрупп (см. нижнюю рамку), у каждой группы есть свое название. Похожим образом настройки организованы в очень многих местах в апексе. В дальнейшем я буду просто указывать путь к нужной настройке примерно так: «Application Properties» → «Definition» → «Name» → «Version».
Также, если вы посмотрите на хлебные крошки вверху страницы, вы увидите, что там написано «Edit Application Definition», хотя заходили вы, казалось бы, в «Application Properties». Просто не обращайте внимания.
Shared Components
Shared Components — это наше всё. Этот раздел является промежуточным пунктом на пути к конкретным компонентам приложений. Покажу здесь общий вид, просто чтобы вы представляли, где что находится:
Совсем неважной ерунды здесь почти нет. Каждый раздел вам так или иначе может понадобиться. Названия разделов говорят сами за себя, добавить почти нечего:
Перевод приложений в апексе сделан просто ужасно (честно, я пытался придумать, как сделать его хуже — и не смог), и нет никаких свидетельств того, что в будущем станет лучше.
Ужасно с точки зрения архитектуры и удобства работы над переводом. Могу только сказать разработчикам: «Спасибо, что хотя бы без багов» (но тут как посмотреть: переводы устроены так, что некоторые особенности их работы мало чем отличаются от багов).
Приходится с этим жить.
Page Designer
Page Designer — редактор страниц. Это, наверное, главное место в IDE. Здесь вы будете создавать то, с чем напрямую взаимодействует пользователь, — страницы приложения. Здесь просто куча функций, почти как в кабине самолета. Чтобы попасть в Page Designer, нужно кликнуть по ссылке с названием страницы на странице приложения (извините за тавтологию). На скриншоте разноцветными рамками выделены основные составляющие редактора:
Панель кнопок вверху (в красной рамке):
Слева (в оранжевой рамке) — панель с компонентами страницы. В этой панели есть 4 закладки:
По центру (в зеленой рамке) — панель, содержащая много разнородной информации. В верхней части панели есть 5 закладок, на которых можно найти:
Также центральная панель имеет снизу еще одну дополнительную панель, которую можно использовать для быстрого добавления компонентов на страницу.
Справа (в синей рамке) — панель свойств. Тут все просто — она показывает свойства выбранного в данный момент компонента. Часть свойств компонентов — простые: текст, число, значение из списка. Но у более сложных свойств компонентов есть дополнительные интерфейсные возможности, сильно облегчающие жизнь при работе с ними.
Свойство, представляющее собой большой текст. Например, код на PL/SQL или JavaScript. Выглядит так:
Можно писать код прямо так, в этом поле, а можно щелкнуть по кнопке вверху страва, и тогда откроется модальное окно с редактором кода, где доступны подсветка синтаксиса (для SQL, JavaScript, CSS, HTML), поиск в тексте и другие функции редактора.
Свойство — Shared Component. Если свойство является одним из компонентов приложения (Shared Component), то выбирать конкретный компонент можно из списка, а нажав на кнопку справа от списка
можно переместиться в раздел Shared Components непосредственно в свойства выбранного компонента (чтобы, например, их изменить).
Если у вас значение свойства выбирается из списка, иногда справа можно увидеть другую дополнительную кнопку:
Она называется «Quick pick» и используется, когда вариантов очень много. «Quick pick» дает чуть более быстрый доступ к небольшому подмножеству вариантов — как правило, там находятся наиболее часто используемые варианты. «Часто используемые варианты» здесь — не вами используемые, а «вообще». Это жестко заданный список и со временем не меняется.
SQL Workshop
Как я уже говорил, SQL Workshop — это заменитель обычной IDE (если у вас по каким-то причинам нет возможности ее использовать).
Он состоит из 5 разделов:
Object Browser
Здесь есть все, что нужно для работы с объектами БД: создание, изменение, удаление, просмотр свойств объектов, ввод данных в таблицы — для всего этого в этом разделе есть графический интерфейс. Вверху слева в выпадающем списке можно выбрать тип объектов (на скриншоте показаны таблицы), вверху справа можно выбрать схему, объекты которой вы можете посмотреть. В списке доступных схем вы не увидите все схемы сразу — это нормально. Как сделать схемы видимыми в апексе, я расскажу, когда дойду до администрирования.
Также я не вижу большого смысла описывать этот раздел подробнее: если вы знаете, что значит фраза «добавить столбец в таблицу», вы без труда догадаетесь, когда вам нужно будет нажимать на кнопку «Add Column» и что вас может ждать дальше.
SQL Commands
В этом разделе можно выполнять SQL запросы и PL/SQL код.
По возможностям этот раздел почти не уступает полноценным средам разработки. Не хватает разве что автодополнения кода и подсветки синтаксиса (а в Object Browser подсветка синтаксиса есть, кстати). Имеющиеся возможности:
Это, как вы понимаете, далеко не всё, что есть в IDE APEX, но на данном этапе не имеет смысла углубляться дальше. Отдельные элементы интерфейса апекса будут разобраны более подробно в темах, которые имеют к ним непосредственное отношение.
P. S. Я пока не могу сказать, что четко продумал структуру этого туториала, возможно, в будущем я добавлю еще скриншоты и описания в эту статью или опишу дополнительные возможности в других статьях. Осталось придумать, как оповещать заинтересованных о значительных правках старых статей.
Визуализация данных с помощью Oracle Apex
Oracle Apex – компонент для разработки конечных приложений, входящий в состав поставки СУБД Oracle, позволяющий быстро «доставать» данные из базы и доставлять их через веб-интерфейс конечному пользователю. Как правило, данные для просмотра и редактирования выдаются в табличном виде и Apex предоставляет богатые возможности для настраивания отчета: можно накладывать фильтры, делать сортировку и группировку, скрывать имеющиеся столбцы и добавлять расчетные новые, делать сводные отчеты, выгружать данные в формате csv, pdf и даже Excel. Каждый пользователь может сохранить предпочитаемые им настройки каждого отчета как индивидуально, так и для совместного использования. В таком формате Apex функционирует у большинства наших заказчиков.
Однако мало кто использует довольно широкие возможности Apex’а для построения графиков. Эта тема, на наш взгляд, довольно интересна и мало освещена в интернете.
В этой статье будем предполагать, что читатель имеет представление о разработке приложений с помощью Oracle Apex.
В качестве примера рассмотрим гипотетический дашборд, показывающий переработки и недоработки сотрудников департамента за отчетный период, а также распределение трудозатрат по активностям.
С точки зрения разработки добавление графика на страницу приложения в Apex’е представляет собой добавление региона типа Chart. У него есть ряд обычных для региона свойств, которые можно заполнить значениями по умолчанию или не заполнять вообще.
В интерфейсе разработки Apex 5.1 часть свойств самого региона заполнялась через пункт меню Attributes, что вносило некую неразбериху: было интуитивно не всегда понятно, что и где лежит. Надеюсь, в новых версиях UI эту путаницу убрали. В частности, именно в «атрибутах» указывался тип графика, который мы хотим получить (Рисунок 1). Как видим, выбор достаточно большой и охватывает все основные визуальные представления, используемые аналитиками в большинстве случаев.
Рисунок 1 Выбор типа графика
Здесь же мы указываем ориентацию столбцов гистограммы (вертикальная или горизонтальная), высоту панели, настройку всплывающих подсказок (показывать ли их вообще, а если показывать, то что именно выводить), настройку легенды, а также можем добавить код на JavaScript для тонкой «подгонки» графика под требования заказчика. Это нужно, например, в том случае, если каждому столбцу на диаграмме мы хотим задать цвет на наш выбор. Код можно добавить явно или указать наименование функции, реализацию которой мы можем привести где-то еще (Apex позволяет добавлять в приложение js-файлы для определения кода на «высшем» уровне или указывать код в рамках одной страницы веб-приложения).
В каждом графическом регионе может быть несколько графиков, если они объединены общей осью абсцисс (при этом по оси ординат может быть две шкалы). В таком случае мы добавляем их через пункт меню Series и указываем SQL-запрос, который будет возвращать нам значения по осям и – при желании – некоторую дополнительную информацию: наименование ряда, значения для всплывающих подсказки или даже ссылку для перехода на другую страницу приложения (Рисунок 2). В нашем примере табличный тип данных, возвращаемый запросом, объявлен следующим образом:
Рисунок 2 Настройка графика
Передача параметров (в нашем случае – даты отчета и идентификатора департамента или какого-либо из его подразделений) из формы ввода на сервер происходит стандартным для Apex образом: или через кнопку Submit, или путем создания DynamicAction, который реализует технологию Ajax и может обновить тот или иной регион, их совокупность (ограничения по числу обновляемых регионов нет) на странице динамически. Лично я предпочитаю второй вариант. Изменение графиков при этом происходит в режиме мультфильма: столбцы гистограмм, к примеру, при этом «вырастают» или «съеживаются», появляются стрелки-указатели динамики изменений – пользователь может немного развлечься.
Графики «из коробки» выглядят вполне прилично, но иногда требуется их подстройка под требования заказчика. Например, мой заказчик долгое время получал отчеты в Excel и уже привык к его цветовой гамме, маркерам и т.п. На помощь может прийти JavaScript.
Например, этот код задает цвета для трех вхождений в круговой диаграмме:
Итоговый вид круговой диаграммы приведен на Рисунке 3.
Рисунок 3 Круговая диаграмма Лирическое отступление про цвета
Предположим, например, что нам нужно показать диаграмму распределения трудозатрат по ранее заданному довольно широкому списку активностей. Т.е. активностей много, но в отчетный период заранее неизвестно, работали ли сотрудники над каждой конкретной из них. График строился динамически, поэтому появилась задача подбора цветов для их различения таким образом, что два соседних оттенка довольно контрастно отличались между собой. Выяснилось, что цветов из стандартной поставки буквально не хватает и активности могли начать смешиваться между собой.
Рисунок 4 О цветовой дифференциации – распределение по активностям, в каждой из групп активностей – Co, Ho, Su, могут быть активности из списка над графиком
Почитав пару обсуждений на stackoverflow.com, я решил изобрести свой велосипед следующим образом. Взял таблицу цветов с сайта material design, отсортировал, чтобы близкие группы оттенков (например, «розовый» и «фиолетовый» или «лимонный» и «светло-зеленый») не оказались соседними, какие-то группы цветов исключил и взял только оттенки, которые в css имеют индекс 300, 500, 700 или 900.
В результате получил вот такой список из заведомо избыточных 76 цветов, который и используется в графике (Рисунок 4).
Тех, кому интересна эта тема, могу отправить в обсуждения вот здесь, здесь или здесь.
Надо отметить, что справочных материалов по графикам довольно мало, и настройка через JS может потребовать какое-то время, в первую очередь, на выяснение доступных методов API.
Рисунок 5 Переработка сотрудников какого-то подразделения в феврале какого-то года
Например, для того, чтобы отобразить цифры в кружках на левом графике (см. Рисунок 5), потребовалось сделать настройки для каждого элемента в отдельности:
А референсная линия «0» на правом графике настраивается вот таким кодом:
Мне всё-таки кажется, что подобное вмешательство в установленную функциональность инструмента напоминает костыли. Надеюсь, что в новых версиях Oracle Apex этих «костылей» потребуется меньше. Справедливости ради надо отметить, что в моей практике был случай, когда мне пришлось «допиливать» какие-то настройки BI-отчета с помощью JavaScript в «профессиональном» Oracle BI EE версии 12. На мой взгляд, это говорит о том, что каким бы ни продвинутым инструмент ни был, найдется требование заказчика, выходящее за рамки его штатной функциональности.
В качестве заключения можно сказать, что возможности Oracle Apex как инструмента графического представления данных, конечно, несопоставимы с профессиональными BI-инструментами, особенно если вам потребуется выводить на дашборд что-нибудь вроде линий тренда. Но если вы уже используете БД Oracle, то этими возможностями пренебрегать не стоит. Опять же, с учетом весьма низкого порога входа в эту технологию, она кажется весьма заслуживающей внимания.
Автор статьи: Вадим Бояркин, ведущий консультант группы разработки Big Data Solutions в компании Neoflex
Oracle APEX: Interactive Report with Checkboxes
В этой статье описывается процесс создания в среде Oracle APEX страницы c интерактивным отчетом, в котором можно отметить записи для последующей их обработки. Предполагается,
что читатель имеет базовые знания о среде разработки APEX и БД Oracle.
Отчет с возможностью отметки отдельных записей для обработки — вещь очень удобная, но к сожалению до сих пор не реализованная «из коробки». В APEX API имеется функция apex_item.checkbox2 которая позволяет показать в отчете чекбоксы, но обрабатывать их приходится программисту. Обработку сильно осложняет то, что в многостраничном отчете чекбоксы существуют только для текущей страницы, и при переходах между страницами отчета значения отмеченных чекбоксов нужно где-то сохранять. В данном случае для этого используется коллекция APEX.
Несколько слов о коллекции APEX. Коллекция APEX — это именованная структура данных, существующая в пределах пользовательской сессии, предназначенная для манипуляций с данными при построении сложных форм ввода данных, мастеров и пр. Коллекция напоминает своей структурой таблицу из 50 атрибутов типа VARCHAR2(4000), 5 атрибутов типа Number, 5 атрибутов типа Date, 1 атрибута типа XML, 1 атрибута типа BLOB и 1 атрибута типа СLOB. Работают с коллекцией через PL/SQL API APEX_COLLECTION.
Итак, на страничке будем использовать такие хитрости и трюки:
где id — поле первичного ключа таблицы. Его мы будем передавать в качестве атрибута чекбокса в коллекцию, и его будем использовать при обработке отмеченных записей.
П.1 Создадим процесс на странице :
Create → Page Component → Process →
Process type: PL/SQL code
Name: AJAX_UpdateChBoxCollection
Point: Ajax Callback
PL/SQL Page Process заполняем следующим кодом:
Эта процедура создает коллекцию с именем «CHBOXCOLL» если она еще не была создана,
и добавляет/удаляет запись в коллекцию для изменившего состояние чекбокса. Название коллекции везде пишется капсом. Оно должно быть уникальным. В результате в коллекции будут атрибуты отмеченных записей.
П.2 Далее добавим на страницу код javascript функции который будет вызывать этот процесс:
Edit Page → JavaScript → Function and Global Variable Declaration
Эта функция вызовет ранее нами созданную функцию с именем «AJAX_UpdateChBoxCollection» и передаст ей значение «val» через глобальную переменную apex_application.g_x01.
Результат типа «text» может быть возвращен из процедуры «AJAX_UpdateChBoxCollection» при
помощи функции Htp.Prn(‘какой-то результат’).
П.3 Создадим чекбоксы в отчете, для этого отредактируем запрос следующим образом:
В данном случае в запрос добавляется колонка на базе функции apex_item.checkbox2,
а также наша коллекция, связанная с нашей таблицей по id. Коллекция нам нужна лишь для получения состояния чекбокса при первоначальной загрузке страницы и при переходе между страницами отчета. Тип колонки с чекбоксами должен быть «Standart report column».
Коротко опишу используемые параметры apex_item.checkbox2:
номер переменной APEX_APPLICATION 1 соответствует F01; 2 — F02 и тп.
значение, которое будем передавать в коллекцию, в данном случае это поле «id» таблицы
HTML атрибуты, в данном случае используется тэг который потом используется в качестве jQuery selector в Dynamic Action.
использует значение из коллекции для указания состояния чекбокса
Для наглядности добавим еще один отчет на базе Sql запроса, который назовем Collecton и который будет показывать нам содержимое коллекции:
П.4 Создадим Dynamic Action который будет срабатывать по изменению состояния чекбокса и вызывать созданную в П.3 JavaScript функцию:
Event: Change
Selection Type: jQuery Selector
jQuery Selector:.chbox_UpdColl
Condition: none
Action: Execute JavaScript Code
Fire When Event Result Is: True
Fire On Page Load: False
Code:
В поле jQuery Selector записывается значение атрибута ‘class’ из параметров функции apex_item.checkbox2 в П.3. Перед ним нужно обязательно поставить точку.
В созданный Dynamic Action добавим еще одно действие — обновление отчета коллекции после нажатия на чекбокс:
Action: Refresh
Selection Type: Region
Region: Collecton
Функционал чекбоксов уже работает, остается только добавить обработчик отмеченных чекбоксами записей. Пример такого обработчика с последовательным извлечением данных из коллекции при помощи курсора и записью их в файл собираюсь оформить в виде отдельной статьи.
Основная идея почерпнута здесь. Автор сохраняет отмеченные чекбоксы списком в Item на странице.
Недостаток — максимальная длина хранимого списка — 4000 символов. Использование коллекции в нашем случае снимает это ограничение.
Про использование Ajax Callback в APEX хорошо написано здесь.