Синтакс-помощник

При работе с алгоритмами и запросами печатной формы под рукой нужен справочник платформы 1С — описания объектов встроенного языка, их методов, свойств и событий, а в запросе ещё и ключевых слов с функциями. В конфигураторе для этого есть синтакс-помощник, а в тонком клиенте взять его было негде. Теперь справка платформы встроена прямо в редакторы PrintWizard.

Справка читается из файлов, которые платформа кладёт рядом со своими исполняемыми файлами. Таких файлов несколько — объектная модель, встроенный язык, язык запросов и язык выражений системы компоновки данных (см. Книги). В типовом случае ничего скачивать и настраивать не нужно: файлы находятся сами.

Справка панелью справа от редактора кода

Как открыть

Справка вызывается кнопкой «Синтакс-помощник» (подсказка «Показать справку платформы») в командной панели редактора кода. Первое нажатие показывает справку, повторное — прячет.

Кнопка есть:

в редакторе кода, открытом отдельным окном;
в конструкторе печатной формы (форма макета) — одна справка на все вкладки с кодом и на редактор запроса;
в конструкторе QR-кода;
в консоли запросов;
в консолях формы представлений ЗУП.

Панель на форме одна, а редакторов на ней может быть несколько, и книга у каждого своя. Поэтому кнопка, нажатая рядом с редактором, чья книга сейчас не показана, не прячет панель, а переключает её на нужную книгу. Спрятать панель можно кнопкой того редактора, чья книга открыта, или кнопкой «Закрыть» в самой панели.

По умолчанию справка показывается панелью справа от редактора. Настройка «В отдельном окне» меняет поведение: та же кнопка открывает справку отдельным окном. Окно одно на сеанс — нажатие кнопки в другой форме выводит вперёд уже открытое окно, а не заводит второе.

Справка отдельным окном рядом с конструктором печатной формы

Открывается справка не мгновенно: файл объектной модели объёмный, на его подготовку уходит около полутора секунд, и всё это время в строке состояния видно, что справка готовится. Остальные книги (см. Книги) весят сотни килобайт и открываются заметно быстрее. Пока справку не открыли, форма за неё не платит — файл читается при первом показе.

Справка по слову под курсором

Короткий путь к статье — CTRL+F1. Поставьте курсор на имя объекта, метода, свойства или на ключевое слово запроса и нажмите сочетание: справка откроется на закладке «Индекс» со списком найденного по этому слову. Если совпадение единственное, сразу открывается статья.

Что при этом происходит со справкой, зависит от того, в каком она виде:

панель открыта — слово уходит в её строку поиска;
панель скрыта — разворачивается сама, дальше как выше;
справка настроена отдельным окном — открывается окно, слово уходит в него. Окно одно на сеанс: повторное нажатие выводит вперёд уже открытое и меняет в нём поиск.

Книга подбирается по редактору, в котором стоит курсор: в редакторе алгоритма — объектная модель платформы, в редакторе запроса — язык запросов. Если нужная книга ещё не открыта, она открывается по ходу дела: слово подождёт в строке поиска и применится, как только книга будет готова.

Книги

Справка платформы разложена по нескольким файлам-книгам. Панель показывает одну книгу за раз и не склеивает их в общее дерево.

Книга	Файл	Что внутри
Платформа	`shcntx_*.hbk`	Объектная модель: объекты встроенного языка, их методы, свойства и события. Самая большая книга — около 40 МБ
Встроенный язык	`shlang_*.hbk`	Обзорные статьи о языке: формат программного модуля, зарезервированные слова и подобное. Справочника функций в ней нет
Язык запросов	`shquery_*.hbk`	Синтаксис текста запроса: ключевые слова и функции — `ВЫБРАТЬ`, `СГРУППИРОВАТЬ ПО`, `ЕСТЬNULL`, `ПОДСТРОКА`, `РАЗНОСТЬДАТ`
Язык выражений СКД	`dcsui_*.hbk`	Раздел системы компоновки данных о языке выражений: операции, агрегатные функции, работа с датами

Звёздочка в имени файла — языковой вариант: ru — русские описания, root — с английской терминологией. Какой из них открыть, задаёт подменю «Язык» в командной панели; если выбранного варианта нет, берётся ru, затем root, затем первый найденный.

Книгу подсказывает редактор, из которого позвали справку, а сменить её можно подменю «Книга» в командной панели справки.

Там, где на форме только редакторы запросов — в консоли запросов и в представлениях ЗУП, — книга предопределена: панель сразу открывается на языке запросов, а подменю «Книга» не выводится, выбирать там нечего. В остальных местах — в консоли кода, в конструкторе печатной формы, в окне справки — выбор редактора только начальный, дальше книгу выбирает человек.

Где берутся файлы книг

Каждое переключение книги — это новый поиск файла. Порядок один и тот же, и на вашем компьютере, и на сервере — какая из сторон ищет, задаёт настройка «Где читать справку»:

Путь, уже известный этой стороне — файл, открытый в текущем сеансе. Годится, если он читается отсюда.
Путь из настройки «Файл справки» — только для книги «Платформа». У остальных книг своего пути в настройках нет: он указывал бы на чужой файл.
Рядом с указанной «Платформой» — каталог файла из настройки плюс имя нужной книги. Книги одной установки платформы лежат в одном каталоге, поэтому, если объектную модель вы указали вручную, соседей разумно брать оттуда же.
Автопоиск по установке платформы — каталог исполняемых файлов, затем каталоги соседних версий, самая свежая первой.

Для книги «Платформа» шаги 3 и 4 пропускаются, когда «Где читать справку» стоит не в «Авто»: путь в этом случае указали вы (или администратор — для серверного пути), и молчаливый уход в другой файл показал бы справку не от той платформы. На остальные книги это ограничение не распространяется — их путей настройка не хранит, перебивать нечего, а запрет оставил бы их без файла вовсе.

Ваш компьютер и сервер ищут независимо: у каждого своя установка платформы. Это и нужно там, где сервер работает под Linux, а вы — на другой машине.

Что внутри

Под командной панелью расположены две закладки — «Содержание» и «Индекс», а ниже — текст выбранной статьи.

Содержание

Дерево разделов справки: разделы, объекты, их свойства, методы и события. Ветви разворачиваются по мере обращения.

Закладка «Содержание» и статья выбранного метода

Индекс

Поле поиска (подсказка ввода «Имя объекта, метода или свойства») и список найденного. Поиск идёт по началу имени, регистр не важен. В книге «Платформа» он работает и по русскому, и по английскому имени — ТаблицаЗначений и ValueTable найдут одно и то же, а в списке выводится полное имя с владельцем, как в конфигураторе: «ТаблицаЗначений.Добавить (ValueTable.Add)». В книгах языка запросов и выражений СКД английских имён нет — ищите русские. Удачные запросы запоминаются и предлагаются в поле поиска при следующем вводе.

Закладка «Индекс»: поиск по имени объекта

Статья

Текст выбранной статьи. Внутренние ссылки статьи работают: переход по ссылке открывает нужную статью здесь же, а вернуться назад можно кнопкой «Назад».

Командная панель

В командной панели справки собраны выбор файла и языка, переходы по истории и по содержанию.

Командная панель справки, открыто подменю «Язык»

Кнопка	Описание
Открыть…	Выбрать файл пакета справки
Запомнить	Открывать этот файл и в следующий раз
Книга	Какую книгу читать: «Платформа», «Встроенный язык», «Язык запросов», «Язык выражений СКД». Заголовок подменю показывает открытую книгу, текущий пункт помечен. Там, где книга предопределена, подменю не выводится
Язык	Язык описаний платформы: «Русский» — русская справка, «English» — справка с английской терминологией. Заголовок подменю показывает открытый язык
Назад	Вернуться к предыдущей статье
Вперёд	Вернуться к статье, с которой ушли назад
Выше	Перейти к разделу уровнем выше
Ниже	Перейти к первой вложенной статье
Найти в содержании	Показать открытую статью в дереве содержания
Закрыть	Убрать панель справки с формы. Есть только у панели, в отдельном окне кнопки нет

Кнопка «Запомнить» доступна, когда файл выбран вручную кнопкой «Открыть…» и отличается от уже сохранённого. Она записывает выбор в персональную настройку, чтобы в следующий раз открывался тот же файл. Запоминается путь только к книге «Платформа»: её объём заставляет переносить файл и указывать его руками, а остальные книги невелики и находятся сами.

Настройки

Настройки справки — в разделе PrintWizard → Настройки, закладка «Редактор», группа «Синтакс-помощник» (см. также настройки редактора кода).

Поле	Описание
В отдельном окне	Выключен — справка показывается панелью рядом с редактором, включён — отдельным окном. По умолчанию выключен
Где читать справку	Сторона, которая читает файлы книг. Настройка одна на все книги. По умолчанию «Авто»
Файл справки	Путь к файлу `.hbk` книги «Платформа»*, если автоматический поиск не подходит. Пусто — искать самим. Рядом выводится отметка проверки: годится ли указанный файл и кто его проверял. Остальные книги ищутся в том же каталоге (см. Где берутся файлы книг)

Значения поля «Где читать справку»:

Значение	Описание
Авто	По умолчанию. Файл ищется сначала на вашем компьютере, а если его там нет — читает сервер. Указывать путь необязательно: найденный файл запоминается в ваших настройках, а если он пропадёт, поиск повторится. Подходит почти всем
Клиент	Файл читает только ваш компьютер, по указанному пути. Если файла по этому пути нет, справка сообщит об этом и другой искать не станет
Сервер	Файл читает только сервер, под учётной записью своего процесса. Путь общий для всей базы, поэтому подходит и сетевой каталог, доступный серверу. Нужно там, где у клиента файла заведомо нет, — например, при работе через веб-клиент
Отключено	Справка выключена целиком: панель не строится, кнопка в редакторе не выводится, `CTRL+F1` ничего не делает

Настройки «В отдельном окне», «Где читать справку» и клиентский «Файл справки» — персональные, у каждого пользователя свои. Путь к файлу на сервере описывает окружение сервера, поэтому он общий для базы: записать его может только пользователь с полными правами, остальным поле видно для просмотра.

Особенности

Расширение требует режима совместимости конфигурации не ниже 8.3.18 (см. Требования).
Справка берётся из установки платформы, поэтому её содержимое соответствует версии платформы, под которой работает клиент — или сервер, смотря что выбрано в настройке «Где читать справку».
В веб-клиенте файл читает только сервер (в режиме «Авто» это происходит само). Выбор файла вручную в веб-клиенте недоступен: путь на машине пользователя означал бы для сервера другой файл.
Если файл книги не найден, справка сообщает об этом в строке состояния и остаётся работоспособной: путь к «Платформе» можно указать кнопкой «Открыть…» или в настройках, а при переключении на отсутствующую книгу (скажем, в поставке платформы нет файла языка запросов) панель остаётся на прежней.
Указанный в настройке путь, который перестал существовать (например, после обновления платформы), открытие не ломает: в режиме «Авто» файл снова ищется автоматически.
Смена книги перечитывает файл: история переходов и уже прочитанные статьи сбрасываются — так же, как при смене языка.
В книгах «Язык запросов» и «Язык выражений СКД» имена только русские. Над английским ключевым словом (SELECT, WHERE) CTRL+F1 ничего не найдёт — ищите русское имя (ВЫБРАТЬ, ГДЕ). Раздел о двуязычных ключевых словах есть в книге отдельной статьёй.
В дереве книги «Язык запросов» не показываются разделы, за которыми нет статьи: платформа держит там место для тем, наполненных только в книге «Платформа» («Выполнение и работа с запросами во встроенном языке», «Таблицы запросов»). Их содержимое смотрите в книге «Платформа» — она в том же подменю.
В формах сравнения кода панели справки нет: CTRL+F1 там открывает окно, если справка настроена отдельным окном, и не делает ничего в противном случае.