Мануал для начинающего разработчика Falcon Space

Введение

Общее введение в платформу Falcon Space можно найти здесь - https://falconspace.ru/docs/vvedenie-v-falcon-space--c-chego-nachat

В этой статье мы познакомимся с процессом создания сайта на Falcon Space и ключевыми вопросами, которые возникают у новичков Falcon Space.

Как построен процесс разработки

В системе определяются основные области (неавторизованная область и личные кабинеты) и страницы в них. 

К примеру неавторизованная область может содержать ленд на главной, страницы info и contacts. 

Личный кабинет содержит страницы, которые будут доступны пользователям с определенной ролью. Например, кабинет менеджера будет содержать страницу Клиенты, Карточка клиента, Заказ.

На каждой странице размещается либо некий статичный контент, либо компонент в виде сниппета разметки. 

Вывод обычного контента удобно делать через HTML блоки. А компоненты (Таблицы, Формы и т.д.) создаются также в Панели управления, после чего для них прописываются нужные хранимые процедуры по шаблону (процедура автогенерируются из шаблона соответсвующей SP при их первом редактировании). 

Далее мы рассмотрим как создавать каркас приложения + добавлять начинку на страницы сайта. 

Создаем кабинеты пользователей и страницы для них

Идем в /roles и создаем роли в системе. Роль задает некую группу пользователей, на которую можно давать доступы к объектам сайта - страницы, формы, таблицы, ресурсы и т.д. К примеру, создайте роль seller.  

Далее идем в /members и создаем пользователя (например, seller1 с паролем 123456) в системе (выбираем роль seller).

См. также Доку по работе с ролями и пользователями.

Теперь попробуйте зайти на сайт под новым пользователем в другом браузере (чтобы не выходить из системы из под админа). Вы увидите его пустой кабинет (т.к. нет пока для этой роли страницы). Давайте их создадим. 

В /pages мы можем создать новые страницы и прописать в доступах роль seller. Тем самым мы даем доступ пользователям с ролью seller к этой странице. В этом поле можно прописывать несколько ролей через запятую. Также есть 2 специальных значения: * - для всех авторизованных пользователей, all - для всех пользователей (неавторизованных и авторизованных). 

Чтобы они появились в меню в настройках системы надо задать: 

• Включить переключатель "В меню" 
• Указать Порядок в меню
• Указать иконку в меню

В теле страницы просто укажите пока текстовое описание "страница такая-то".

Создайте все необходимые страницы по подобию и посмотрите теперь кабинет пользователя с ролью seller. В меню появятся новые страницы (если поставили переключатель В меню). 

См. также Доку по работе со страницами. В ней вы узнаете как делать хлебные крошки, указывать SEO Title, Description, делать редирект, вставлять JS, CSS и т.д.

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

Добавляем начинку для страниц - компоненты или контент

В разделе /pages находим нужную страницу и переходим на ее редактирование. 

Мы можем добавить на страницу сниппет некоего компонента (через кнопку Сниппеты либо некую статичную разметку). 

Сниппет - это некая простая разметка для div со спец классом (as-table, as-form и т.д.) с передачей еще неких data- параметров. Самые частые параметры: 

• data-code - определяют код компонента, например форма newClient. 
• data-itemID - некий идентификатор, который передается в компонент (например для формы editContragent может быть data-itemID="123"). 

Примечание:

1. вы можете передать неявно параметр из URL адреса в разметку через такой прием url-itemID в фигурных скобках - т.е. из URL возьмется URL параметр itemID и подставится в разметку.
2. вы можете использовать на странице sp параметры. В разметке пишем {sp-name1} и SP процедуре страницы в SELECT 3 указываем значение этого параметра. Таким образом на страницу можно поместить любую динамическую разметку.  

Реализация компонентов Таблица, Форма и т.д.     

Как сниппет превращается в таблицу или форму? При загрузке страницы платформа ищет типовые сниппеты. Если находит, то начинается процесс загрузки в них компонента - идет обращение к серверу, получаем данные и визуализируем их на основе тех настроек, что пришли от сервера.  В итоге в DIV подгружается сам компонент (таблица, форма).

Настройки компонентов задаются на странице редактирования компонента с нужным кодом (например на странице управления формы newContact), а также в ее хранимых процедурах. 

У каждого компонента есть строго определенный набор хранимых процедур, которые имеют фиксированный вид входных (входные параметры храннимой процедуры) и выходных параметров (выходные SELECT из процедуры). К примеру у форм это процедуры GetItem, SaveItem CheckField, SaveField, Progress и др.  Их формат описан в документации Работа с формами. 

Для примера выведем Таблицу первых 5 записей из системной таблицы as_trace.

Работа с таблицами описана в этой статье . 

ВАЖНО! Компонент таблицы и таблица базы данных - это совершенно несвязанные сущности. Вы можете выводить таблицу не на основе данных из таблицы БД (а например формировать данные прямо в ХП или на основе JSON данных из API). 

Примечание. Таблицы базы данных вы можете создать в БД, следуя этой документации. 

Давайте на странице разместим сниппет таблицы с кодом showTrace: 

<div class="as-table" data-code="showTrace"></div>

Добавим теперь такой компонент - создаем таблицу showTrace

Укажем столбцы вывода таблицы id, header, username:

Укажем процедуру вывода записей  GetItems: 

Процедура создается всегда по шаблону. Наша задача  - просто правильно подменить данные в типовой процедуре и настроить параметры вывода. 

Здесь мы в SELECT 1 выдали табличные данные для заполнения таблицы.

В SELECT 2 надо указать общее количество (для работы пагинации). 

В SELECT 3 мы указываем различные настройки вывода таблицы.

Информацию о параметрах и структуре процедуры GetItems можно посмотреть в доке Работа с таблицами. 

Важный момент - укажите в настройках таблицы параметр Роли = seller. Иначе ваш пользователь не получит доступа к этой таблице. Таким образом доступ к странице не означает доступа ко всем компонентам на этой странице. 

Также вы можете настраивать доступ более тонко на основе переменной @username в процедурах (от него можно получить проверку наличия той или иной роли, а также фильтровать данные по @username). 

После проверки страницы под пользователем seller1 она будет выглядеть примерно так: 

Если что-то не так сработало, то проверьте как указан сниппет, доступ по ролям, а также точное совпадение кодов полей с выходными кодами полей в SELECT 1 GetItems. 

Решение общесистемных вопросов 

Изменение глобальных настроек выводимого Layout страницы

Смотрите процедуру GetLayout в Настройки системы. Эта процедура выполняется при загрузке каждой страницы сайта и  определяет общие настройки страницы (класс для body, логотип, тема сайта и т.д.), служебное меню пользователя, панель быстрых действий и т.д.

Настройка меню

Для кабинетов обычно используется стандартное меню, оно управляется на основе ролей и строится на базе страниц сайта. См. раздел /menu

Если вы делаете общее меню для лендингов, то обычно это кастомное меню, которое делается на основе HTML блока (обычно для него мы используем код topbar). См. статью Как создать динамическое меню для лендингов. 

Регистрация пользователя и вход пользователя на сайт. 

Форма регистрации создается под проект. Вы можете за пример взять форму создания пользователя на сайте на странице /members.

Важно, там есть особенность - outer процедуры для выполнения дополнительных действий после выполнения операции регистрации пользователя в системе через Внешнее действие.  Подробнее про Внешние действия. Также используется JS коллбек (для saveItem) для обработки результата выполнения операции. 

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

Сами пользователи хранятся в таблице БД as_users. 

Настройка стилей сайта 

В настройках /settings есть форма Настройки дизайна, где вы можете настроить некоторые параметры для стандартного дизайна. 

В начальных настройках можно настроить фавикон, логотип. 

В быстрых действиях есть возможность управлять CSS для всего сайта. Там же вы можете загрузить новый шрифт. 

Если вам нужно использовать полностью кастом страницы, то используйте механизм Лендов - см Работа с лендами. 

Как управлять структурой базы данных

Есть отдельный раздел для управления таблицами базы данных /dbtables - там вы можете управлять столбцами, отношениями, индексами на таблицах, получать SQL код для переноса структуры таблицы БД.

Также вы можете напрямую работать с таблицами БД через SQL Server Management Studio. 

Заносить данные в таблицы вы можете либо через Insert запросы в RunSQL в Быстрых действиях, либо создать таблицу управления для внесения данных 

Как подлезть со своим JS

Свой JS можно внедрять в Быстрые действия / JS, а также на отдельных страницах - раздел JS (2 поля - для вставки добавления скриптов разметки, так и для кода JS).

В /settings настройка CommonScripts предназначена для добавления кода различных счетчиков, внешних чат-консультантов и т.д. Если хочется добавить что-то в head, то это настройка CommonStyles

У многих компонентов есть свои коллбеки, которые позволяют в нужном месте подлезть со своим JS кодом (например, после загрузки таблицы или после сохранения формы).

Также смотрите доку по кастомной разработке на JS в платформе. 

Отправка почты

Для отправки почты требуется настроить почту на странице /email-settings. После занесения настроек на той же странице можно проверить как идет отправка email. 

Документация по работе с почтой на Falcon Space. 

Сама почта отправляется через внешнее действие с кодом email.   

HTML блоки - блоки типовой верстки

Блок может быть статичным (например, footer блок) либо динамическим (например, блок вывода списка статей). 

Где-то в коде SP мы можем получить HTML блоки и вывести их разметку.

Управление блоками находится на /htmlblocks

У блока мы указываем тело блока (статичный HTML), либо процедуру генерации блока (она выдает строку с разметкой). 

Работа с HTML блоками описана здесь . 

Можно сказать, что HTML блок инкапсулирует в себе некую сложность, связанную с разметкой некой области на странице, например, футер, кастом-меню, блок отзывов, карточка товара, список похожих товаров и т.д. Т.е. работает как функция, выдающая некую разметку на основе входящих параметров. 

Дополнительные важные настройки в /settings

domain - используется для организации полных ссылок. 

isDemo - используется на деморешениях для вывода некоторых рекламных демонстрационных элементов.

Лендинги

Лендинг - это настройка над механизмом страниц.

Лендинг не имеет стилей кабинетов и разделяется на секции (у каждой секции свой HTML блок, который может быть динамическим или статическим). 

При добавлении секции вы можете выбрать один из шаблонов разметки секции. Также примеры секций с кодом можно взять здесь - https://falconspace.ru/landguide

Раздел про лендинги.

Более сложные вопросы для проработки

Получение уведомлений в Телеграм. Создание телеграм-бота

Вы можете создать бота (через @botfather в телеграм) и прописать токен в appsettings.json. 

Это позволит платформе управлять ботом через хранимую процедуру (она находится в /syssp).

Когда кто-то пишет боту, то эта команда попадает на вход в хранимую процедуру action. И в выходном select мы указываем боту что сделать (отправить такое-то сообщение). 

Бота также можно использовать для уведомлений пользователей телеграм. Для этого пользователь сначала должен указать в профиле телеграм, обратиться к боту (бот создаст привязку chatID). Затем при появлении нового уведомления в системе, если у пользователя привязан chatID, то ему будет отправлено сообщение в телеграм от бота.

Дока по телеграм ботам

Создание API методов

В платформе есть универсальный механизм для отправки запросов во внешние системы - это исходящие запросы API.

Также вы можете создать свой слой API методов или веб-хуки, к которым будут обращаться извне другие системы. Это входящие запросы API. 

Управление API методами находится в разделе /asapi.

Внешние действия

В SQL можно делать многое, но нельзя напрямую отправить почту, или вызвать метод API (отправить запрос во внешнюю систему).

Для этого мы используем систему Внешних действий. Мы выдаем некий SELECT, который платформа воспринимает как  команду что-то сделать (например, отправить письмо на email). 

Дашборды, графики, визуализация данных 

Дашборды можно строить как на базе компонента Дашборд, так и на базе простой разметки с множеством панелей as-panel и таблицами формами в них. 

Пример разметки для подобного дашборда: 

       <div class="row mt-3 ">
        	<div class="col-12 col-md-12 col-lg-8">
            	<div class="row mb-3">
                	<div class="col">
                        <a href="/searchprojects" class="btn btn-outline-primary btn-block mb-1"><i class="fa fa-search"></i> Искать проект</a>
                    </div>
                	<div class="col">
                        <a href="/favorites" class="btn btn-outline-primary btn-block mb-1"><i class="fa fa-heart"></i> Избранные проекты</a>
                    </div>
                	<div class="col">
                    </div>
                </div>           
				<div class=" as-table as-panel" data-code="supplierBidsShort">                	
                </div>
                <div class=" as-table as-panel" data-code="supplierProjectsShort">                	
                </div>           
                <div class=" as-table as-panel" data-code="supplierReviewsShort">                	
                </div>
                <div class=" as-table as-panel" data-code="supplierordersShort">                	
                </div>
                
			</div>
        	<div class="col-12 col-md-12 col-lg-4">
            	<div class="as-panel text-center">
                     <h3 class="mt-3">Мой баланс</h3>
                     <a href="/balance" class="h1 btn-block mb-1 text-decoration-none mb-1">
                        	<span class="as-money" data-nocolor="1" data-value="100" data-hidesign="1"></span>
                            
                     </a>     
                     <a href="/addbalance" class="btn btn-outline-primary btn-block">Пополнить баланс</a>
                </div>    
                <div class="as-form as-panel" data-code="tariffInfo" data-itemid=""></div>
            </div>        
        </div>

Графики и другие способы визуализаци данных - это специальные режимы работы таблиц

Особо можно выделить создание графиков на основе Apex Chart. Вся задача сводится просто к созданию правильного JSON с данными на входе. 

Визуализацию данных можно смотреть на демостенде - https://demo.web-automation.ru/list/watch/dashbord

Некие периодические действия

К примеру необходимо запускать каждый день в 2 часа ночи что-то. Или раз в неделю. 

Для этого используем sync процедуры, они находятся в /syssp (Час, День, Месяц) и в них добавляем вызовы нужных процедур. Пример:

CREATE PROCEDURE [dbo].[falcon_nt_sync_hour]
AS
BEGIN
	EXEC [dbo].[as_trace_warn]
		@code = N'sync',
		@header = N'hour',
		@itemID = 2,
		@text = N'3',
		@username = N''
	if(DATEPART(HOUR, GETDATE())=23) begin 
    	-- обновляем рейтинги, кол-во отзывов, проектов всех supplier
   		exec [dbo].[au_updateSuppliers] 
        exec [dbo].[au_updateProducts]        
	end
END

Подробнее про периодические действия