Модуль:WDFormat/doc

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

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

Использование

Модуль является библиотечным и предназначен для использования в других модулях. Данный модуль не предназначен для использования в статьях или других шаблонах напрямую через вызов #invoke.

Требуемое форматирование описывается профилем, представляющим собой таблицу Lua. Профиль описывает представление отдельных полей, то есть то, как они должны отображаться. Недостающий функционал реализуется указанием в профиле собственных функций, принимающих определённый набор аргументов и возвращающих определённый результат.

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

Для примера использования см. модуль Модуль:CiteGost.

Формат профиля в общем виде

{
    -- Корневой тег:
    tag = {
        name = 'Имя тега',
        classes = { 'class1', 'class2', ... },
        attr = { атрибут1='значение1', атрибут2='значение2', ... },
        tag = Вложенный тег,
    },
    -- Группы:
    -- Начало 1-й группы:
    {
        -- Тег группы:
        tag = {
            name = 'Имя тега',
            classes = { 'class1', 'class2', ... },
            attr = { атрибут1='значение1', атрибут2='значение2', ... },
            css = { свойство1='значение1', свойство2='значение2', ... },
            tag = Вложенный тег
        },
        ensureEnds = 'Символ/текст, которым должно заканчиваться предыдущее поле',
        delimiter = 'Разделитель, добавляемый по отношению к предыдущему полю',
        childEnsureEnds = 'Символ/текст, которым должны заканчиваться поля группы',
        childDelimiter = 'Разделитель полей в группе',
        -- Дочерние элементы текущей группы по факту продолжают предыдущие элементы (влияет на повышение первой буквы до заглавной):
        passthrough = true,
        prefix = 'Текст до начала группы',
        -- Поля группы (подгруппы):
        -- 1-е поле группы:
        {
            -- Тег поля:
            tag = {
                name = 'Имя тега',
                classes = { 'class1', 'class2', ... },
                attr = { атрибут1='значение1', атрибут2='значение2', ... },
                tag = Вложенный тег
                css = { свойство1='значение1', свойство2='значение2', ... },
            },
            ensureEnds = 'Символ/текст, которым должен заканчиваться предшествующий текст',
            delimiter = 'Разделитель, отделяющий текущий элемент от предыдущего',
            -- Функция, разрешающая отображение поля:
            cond = функция,
            prefix = 'Текст до поля',
            field = 'Название поля',
            -- Менять ли первую букву поля на заглавную
            capitalize = true/false
            urlMaskProp = 'P-идентификатор свойства, отвечающего за маску ссылки',
            -- Функции, через которые поле будет отформатировано:
            format = { функция1, функция2, ... },
            suffix = 'Текст после поля',
        },

        -- Второе поле:
        {
            value = 'Отображаемое значение',
        },

        -- Остальные группы:
        ...

        suffix = 'Текст в конце группы',
    },
    -- Остальные группы:
    ...
    ensureEnds = 'Окончение форматированных данных, например, точка.'
}

Функции форматирования полей

Форматирование поля задаётся через команду format с указанием функции форматирования, принимающей определённый набор аргументов. Доступны следующие встроенные функции:

• numericalRanges — форматирование диапазона чисел (корректирует знак диапазона);
• dash — оформление тире в тексте;
• unit — получение единицы измерения у элемента Викиданных;
• abbr — получить сокращённое обозначение (есть ограничения) у элемента Викиданных;
• short — получить короткое название у элемента Викиданных;
• abbrWithHint — получить сокращённое обозначение (есть ограничения) у элемента Викиданных с расшифровкой в подсказке;
• date — форматирование даты;
• quantity — форматирование количества с указанной в нём единицей измерения;
• entity — получить значение идентификатора элемента Викиданных;
• wikilink — оформить поле Викиссылкой, если это возможно;
• wikisource — оформить поле ссылкой на Викитеку, если в элементе Викиданных указана соответствующая статья;
• link — оформить поле внешней ссылкой, если это возможно;
• wikidata — добавление к полю надстрочной ссылки на элемент Викиданных, если хотя бы в одном языковом разделе есть статья по теме;
• wikidataLink — оформить поле ссылкой на элемент Викиданных, который с полем связан.
• forceWikidataLink — оформить поле ссылкой на элемент Викиданных, который с полем связан. Формирует ссылку, даже если ранее по тексту ссылка на такой элемент была дана.

Внесение изменений

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

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

Тесты

См. также: Модуль:WDFormat/testcases

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

См. также

• WDBackend — модуль получения информации из Викиданных по задаваемой схеме.
• WDSource — модуль получения информации об источнике из соответствующего элемента Викиданных.