ЛК позволяет не только менять оформление и тексты, но и дорабатывать поведение: переопределять шаблоны и скрипты экранов, добавлять свои страницы, передавать во фронтенд дополнительные данные и подключать серверный код. Эта страница описывает клиентскую часть; серверная вынесена на страницу Серверные расширения (engine), а пошаговые примеры — на страницу Разработка виджетов.

Общие принципы, расположение каталогов и правила наложения слоев описаны на странице Настройка личного кабинета. Все пути ниже указаны относительно каталога кастомизации (local/<client> или clients_stuff/<client>).

Как устроен интерфейс

ЛК — одностраничное приложение: сервер отдает данные в JSON, а страницы собираются в браузере из шаблонов. Используются Backbone.js (модели, коллекции, представления), CoffeeScript и шаблоны .jst.hamlc (Haml с возможностью вставлять CoffeeScript). Исключение — страница входа, восстановление пароля и печатная форма квитанции: они рендерятся на сервере.

Полезные объекты в консоли браузера:

• Application.data — данные, переданные сервером при загрузке страницы;
• Application.objects — те же данные в виде моделей и коллекций: personalAccounts, servs, person или company, widgets и другие;
• Application.getCurrentAccount() — текущий лицевой счет;
• JST — скомпилированные шаблоны по их путям, например JST['layout/footer'].

Шаблоны интерфейса

Чтобы изменить экран, положите в assets/templates файл с тем же путем, что у шаблона приложения: он полностью заменит стандартный. Пути шаблонов приложения можно посмотреть внутри контейнера в /opt/hydra/hupo/app/assets/templates; наиболее востребованные:

Шаблоны, которые есть в приложении, подхватываются автоматически. Новые шаблоны (свои баннеры, страницы, виджеты) нужно подключить к сборке, см. следующий раздел.

JavaScript

Точка входа

Скрипты лежат в assets/javascripts с расширением .js.coffee (CoffeeScript) или .js. Точка входа клиентского кода — файл custom.js.coffee; в слое default он подключает шаблоны, представления и файл client_custom:

#= require_tree ../templates
#= require_tree ./views
#= require client_custom

Поэтому для своих доработок достаточно создать в своем слое файл client_custom.js.coffee:

#= require_tree ../templates
#= require_tree ./views
#= require my_plugin

Директивы require подключают другие файлы: require_tree — каталог целиком, require имя — файл по логическому имени без расширения. Так подключаются и jQuery-плагины, положенные в assets/javascripts.

Код после загрузки ЛК

Код, которому нужен инициализированный ЛК, выполняется в обработчике ApplicationLoader.done:

#= require_tree ../templates
#= require_tree ./views

ApplicationLoader.done (app) ->
  # app -- экземпляр ЛК, Application.data -- данные сервера
  console.log('Текущий счёт', app.getCurrentAccount().get('vc_account'))
  $.get('/my_info').done (data) ->
    $('.content').prepend("<div class='my-info'>#{data.text}</div>")

Переопределение представлений

Поведение существующих экранов меняется переопределением класса представления: положите файл с тем же путем, что в app/assets/javascripts/views приложения, и объявите в нем класс с тем же именем. Так слой default переопределяет views/accounts/servs/closed_subscription.js.coffee. Исходный класс при этом недоступен, поэтому скопируйте его из контейнера и измените нужные методы.

Чтобы дополнить класс, а не заменить, положите файл под другим именем и унаследуйтесь от исходного класса:

#= require views/index

BaseIndex = HupoApp.Views.Index

class HupoApp.Views.Index extends BaseIndex
  render: =>
    super()
    @$el.append('<div class="promo">Акция месяца</div>')
    @$el

Свои страницы

Новые страницы со своими адресами добавляются расширением маршрутов и диспетчера:

HupoApp.routes.push ->
  @resources 'accounts', {only: ['show']}, ->
    @get 'bonus': 'bonus'

class ExampleDispatcher extends HupoApp.Dispatcher
  accounts: =>
    Object.assign(
      super,
      bonus: (vc_account_no) =>
        view = new HupoApp.Views.Example.Bonus(vc_account_no)
        @router.updateContent(view.index))

@HupoApp.Dispatcher = ExampleDispatcher

Оба файла подключаются из client_custom.js.coffee директивами require. Страница открывается по адресу /accounts/<номер счёта>/bonus. Данные для нее, если они нужны с сервера, отдает engine.

Серверные представления (views)

Каталог views переопределяет серверные шаблоны приложения; путь указывается относительно app/views:

Данные для фронтенда

Пустой серверный шаблон application/_custom.json.jbuilder — место, куда можно добавить свои данные. Все, что в нем выведено, попадает в Application.data и доступно в шаблонах и скриптах:

json.current_user_person current_user.person?
json.qr_image_url asset_path('qr.jpg')
json.support_hours '09:00-21:00'

.shortcut-content
  - if Application.data.current_user_person
    %img{src: Application.data.qr_image_url}
    .shortcut-text= "Поддержка: #{Application.data.support_hours}"

В шаблоне доступен текущий пользователь (current_user, его лицевые счета, услуги, дополнительные параметры) и хелперы Rails. Это самый простой способ вынести во фронтенд данные из Гидры без написания engine.