Руководство по составлению модели

Модель bem-site-engine описывает структуру сайта. Данная структура позволяет в автоматическом режиме построить меню, роуты, загрузить связанные ресурсы, построить файл sitemap.xml и.т.д. Она представляет собой массив хешей, которые должен возвращать модуль model/index.js при его подключении с помощью require, например:

module.exports = {
    get: function() {
        return [
            ...
        ]
    }
};

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

Таким образом, модель bem-site-engine представляет собой дерево js-объектов, часть свойств которых может быть записана вручную, а часть вычислена на этапе сборки. Кроме того, некоторые части такой древовидной модели на этапе сборки могут быть построены автоматически. Так например строятся страницы авторов и переводчиков, а также страницы тегов и библиотек блоков.

Описание типичного узла модели выглядит следующим образом:

{
    title: 'Привет Bem-Engine',
    route: {
        name: 'index',
        pattern: '/'
    },
    source: {
        ru: {
            title: 'Bem-site-engine',
            createDate: '12-07-2014',
            editDate: '12-07-2014',
            authors: ['kuznetsov-andrey'],
            translators: ['kuznetsov-andrey'],
            tags: ['readme'],
            content: 'https://github.com/bem/bem-site-engine/blob/dev/README.md'
        }
    }
}

title

Тип: {String|Object}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Текст, который будет отображен в пункте меню ассоциированным с текущим узлом в модели. Если значением поля title является строка, то это значит, что она будет отображена для всех языков, для которых сконфигурирован bem-site-engine. Используя объект с ключами локализации можно отображать разный текст для каждого языка, например:

title: {
    en: 'Hello Bem-Engine',
    ru: 'Привет Bem-Engine'
}

route

Тип: {Object|String}
Наличие: не обязательно
Значение по умолчанию: наследуется от родительского узла

Данное поле позволяет сформировать url для узла на этапе сборки данных.

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

route: {
    name: 'documentation',
    pattern: '/documentation(/<id>)(/)'
}

где:

name - уникальное имя соотвтетствующее разделу,
pattern - регулярное выражение, написанное по правилам модуля Susanin

Дочерние узлы данного раздела должны иметь роуты, которые конкретизируют значение переметра <id> указанного в паттерне уорневого узла раздела, например:

route: {
    conditions: {
        id: "model"
    }
}

Примечание: приведенная выше конструкция может быть записана в сокращенном виде route: 'model', но только если параметр паттерна имеет имя id.

view

Тип: {String}
Наличие: не обязательно
Значение по умолчанию: 'post' при наличии поля source и 'posts' при его отсутствии.

Значение модификатора view блока content. По сути позволяет указывать вид шаблона, для отображения информации по текущему узлу модели.

Сейчас в модели описаны такие возможные значения view:

index - особый шаблон для отображения главной страницы.
post - шаблон для отображения текста, который был загружен для текущего узла.
posts - шаблон публикаций в виде списка состоящего из заголовков, тегов и так далее.
author - шаблон информации по атору совместно со списком его публикаций сгруппированных по разделам сайта.
authors - шаблон для отображения аватаров авторов в виде таблицы.
tags - шаблон выборки публикаций по определенному тегу сгруппированных по разделам сайта.
block - шаблон для отображения документации, jsdoc и примеров для отдельного блока из библиотеки блоков.

type

Тип: {String}
Наличие: не обязательно
Значение по умолчанию: 'group' в случае отсутствия полей и url, 'simple' во всех остальных случаях.

Тип пункта меню. Может иметь значения:

simple - стандартный пункт меню в виде ссылки.
group - некликабельный группировочный пункт меню с текстом.
select - пункт меню в виде выпадающего списка элементами которого являются дочерние узлы.
delimeter - пункт меню в виде разделителя.

size

Тип: - {String}
Наличие: не обязательно
Значение по умолчанию: 'normal'

Стилевая опция для пункта меню. Значение модификатора size элемента link блока menu-list.

hidden

Тип: {Boolean|Array}
Наличие: не обязательно
Значение по умолчанию: false

Режим отображения текущего узла на сайте. По умолчанию при сборке для этого поля выставляется значение false, что означает, что данные связанные с данным узлом будут отображены для всех языковых версий сайта.

При выставлении значения true для поля hidden данный узел будет присутсвовать в модели, но его данные не будут отображаться на сайте.

Можно также настроить скрытие узла для определенных языков для которых настроен сайт. Для этого значением поля hidden нужно указать массив в качестве элементов которого выступают ключи локализации.

Например, для того чтобы скрыть отображение какого-либо узла для англоязычной версии сайта, нужно написать в конфигурации узла модели:

...
hidden: ['en'],
...

source

Тип: {Object}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Детально

items

Тип: {Array}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Массив дочерних узлов.

url

Тип: {String|Object}
Наличие: не обязательно
Значение по умолчанию: отсутствует

При сборке поле url генерируется автоматически с помощью методов модуля Susanin Однако, иногда бывает необходимо задать значение этого поля в ручную, например для ссылок на внешние ресурсы или другие ресурсы на самом сайте.

Также существует возможность задания индивидуальных url для различных локалей сайта, например:

...
url: {
    en: "https://twitter.com/bem_en",
    ru: "https://twitter.com/bem_ru"
},
...

search

Тип: {Object}
Наличие: не обязательно
Значение по умолчанию: { changefreq: 'weekly', priority: 0.5 }

Индивидуальные настройки для индексации поисковыми системами страницы, связанной с текущим узлом. Значения данных полей вместе с url узлов записываются в файл sitemap.xml, который собирается автоматически при сборке данных.

dynamic

Тип: {String}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Установка значения для данного поля превращает текущий узел в якорный для тех узлов, которые могут быть построены в атоматическом режиме на этапе сборки данных.

Сейчас значениями поля dynamic могут быть:

authors
translators
tags:en
tags:ru

lib

Тип: {String}
Наличие: не обязательно
Значение по умолчанию: отсутствует

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

К примеру, код:

function(lib) {
    return {
        title: lib,
        route: {
            conditions: {
                lib: lib
            }
        },
        type: 'select',
        lib: lib
    };
}('bem-core');

построит пункт меню для библиотеки bem-core и расположит пункты меню, соответствующие версиям этой библиотеки, в виде выпадающего списка.

Source. Мета-информация и источник данных для узла.

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

Пример:

source: {
        en: {
            ...
        }
        ru: {
            title: 'Bem-site-engine',
            createDate: '12-07-2014',
            editDate: '12-07-2014',
            authors: ['kuznetsov-andrey'],
            translators: ['kuznetsov-andrey'],
            tags: ['readme'],
            content: 'https://github.com/bem/bem-site-engine/blob/dev/README.md'
        }
    }

Значением поля source является объект с ключами локализации. В качестве значений к данным ключам выступают объекты содержащие в себе мета-данные к публикации и ссылку на ее источник на github.

title

Тип: {String}
Наличие: обязательно
Значение по умолчанию: отсутствует

Заголовок, публикации.

Примечание: Будет отображаться вместо оригинального заголовка публикации в случае, если тот при конвертации из md в html формат будет представлен тегом h1.

createDate

Тип: {String}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Дата создания публикации в формате dd-mm-yyyy.

editDate

Тип: {String}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Дата последнего изменения публикации в формате dd-mm-yyyy.

В случае, если данное поле будет отсутствовать, то дата последнего изменения будет получена на этапе сборки данных как дата последнего коммита *.md файла, путь к которому указан поле content.

authors

Тип: {Array}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Массив со строковыми значениями ключей авторов.

translators

Тип: {Array}
Наличие: не обязательно
Значение по умолчанию: отсутствует

Массив со строковыми значениями ключей переводчиков.

content

Тип: {String}
Наличие: обязательно, если отсутствует поле stub в значении true
Значение по умолчанию: отсутствует

Ссылка на источник данных для текущей публикации на github, записанная в формате url к файлу на github в браузере. Например, ссылка на README.md файл данного проекта:

{
    ...
    content: 'https://github.com/bem/bem-site-engine/blob/dev/README.md'
}

stub

Тип: {Boolean}
Наличие: не обязательно
Значение по умолчанию: отсутствует

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

Navigation Menu

Uh oh!

Руководство по составлению модели

Детальное описание полей узлов модели

title

route

view

type

size

hidden

source

items

url

search

dynamic

lib

Source. Мета-информация и источник данных для узла.

title

createDate

editDate

authors

translators

tags

content

stub

Uh oh!

FilesExpand file tree

model.ru.md

Latest commit

History

model.ru.md

File metadata and controls

Руководство по составлению модели

Детальное описание полей узлов модели

title

route

view

type

size

hidden

source

items

url

search

dynamic

lib

Source. Мета-информация и источник данных для узла.

title

createDate

editDate

authors

translators

tags

content

stub