Модуль:WDFormat/doc

Это страница документации Модуль:WDFormat.

Модуль предназначен для форматирования набора данных, полученных из Викиданных посредством модуля 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 — оформить поле ссылкой на элемент Викиданных, который с полем связан. Формирует ссылку, даже если ранее по тексту ссылка на такой элемент была дана.

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

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

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

Тесты

Все тесты пройдены.

	Название	Ожидается	Фактически
	test_format_array
	test_format_arrayCapitalize
	test_format_arrayForceCapitalize
	test_format_capitalize
	test_format_conflicts
	test_format_conflicts_recursive
	test_format_date
	test_format_delimiter_function
	test_format_depends
	test_format_depends_fieldPath
	test_format_depends_recursive
	test_format_ensureEndsAndDelimiter
	test_format_fieldPath
	test_format_group_childDelimiter_and_childEnsureEnds
	test_format_group_passthrough
	test_format_group_prefix_with_delimiter
	test_format_group_prefix_with_delimiter_inside_another_group
	test_format_groups_delimiter
	test_format_innerTags
	test_format_isStatic_hidden
	test_format_isStatic_hidden_in_array
	test_format_isStatic_hidden_in_array_in_additional_group
	test_format_isStatic_visible
	test_format_link
	test_format_linkOrder
	test_format_nested_array
	test_format_oneField
	test_format_person
	test_format_person_multipleNames
	test_format_prefixAndSuffix
	test_format_recurseGroups
	test_format_rootTag
	test_format_squareBrackets
	test_format_tableTag
	test_format_wikilink
	test_format_wikisource

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

✅ Тесты пройдены.

План разработки

План работ:

Реализовать форматирование сносок, подтверждающих поля.
Возможность отображения только тех утверждений, которые подтверждены сносками.
Ограничение количества сносок (по умолчанию 3-мя), подумать о возможности комбинирования сносок в троеточии.
Сделать демку шаблона (в песочнице) сноски по QID.
Более подробная документация с примерами.
Подумать о возможности форматирования группы целиком (объединение полей заглавия и подзаголовка в форматируемую группу, в которую добавится ссылка). По логике, родительская группа будет полем ссылки.

См. также

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