Структура определения библиотеки

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

Каждый файл определения библиотеки представляет собой простой структурированный объект данных JSON для максимальной переносимости. Эти данные в этом файле аналогичны тем, что были объявлены в реализациях hook_libraries_info () в 7.x-2.x с некоторыми ключевыми отличиями.

Имя файла определения (машинное имя библиотеки)

Центральная часть метаданных библиотеки - это имя или идентификатор библиотеки. Это машинное имя также служит именем файла JSON, содержащего определение библиотеки, и, следовательно, уникальным URI, используемым для доступа к определению локально или удаленно. Для максимальной совместимости имя машины должно состоять только из строчных букв ASCII, цифр и знаков подчеркивания. Поскольку машинное имя является единственным идентификатором библиотеки и не зависит от имени какого-либо модуля или темы, оно должно быть уникальным среди всех библиотек, известных API библиотек.

 

Пример определения с документацией

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

Этот пример определения с использованием имени библиотечного компьютера " example " будет доступен через глобальный удаленный реестр по адресу:
http://cgit.drupalcode.org/libraries_registry/plain/registry/8/example.json.

http://cgit.drupalcode.org/libraries_registry/plain/registry/8/example.json.

{
    "name": "Example Library",
    "type": "asset",
    "vendor url": "http:\/\/example.com",
    "download url": "http:\/\/example.com\/download\/example.zip",
    "css": {
        "base": [
            "css\/example-styles.css"
        ]
    },
    "js": {
        "js\/example-logic.js": {}
    },
    "version_detector": {
        "id": "line_pattern",
        "configuration": {
            "file": "js\/example-logic.css",
            "pattern": "\/Example Library v([0-9a-zA-Z\\.-]+)\/",
            "lines": 3,
            "columns": 50
        }
    },
    "variants": {
        "minified": {
            "css": {
                "base": [
                    "css\/example-styles.min.css"
                ]
            },
            "js": {
                "js\/example-logic.min.js": {}
            }
        }
    }
}

Признанные в настоящее время свойства

name: (строка) Официальное удобочитаемое имя библиотеки.

type : (строка) Подключаемый модуль типа библиотеки, используемый для загрузки и управления библиотекой в ​​API библиотек. Следующие типы являются собственными для Libraries API, хотя могут быть созданы плагины дополнительных типов (дополнительные сведения см. В документации Advanced API ):

" asset ": применимо к библиотекам ресурсов, которые объявляют дополнения css и js.

" asset_multiple ": применимо для библиотек ресурсов, которые содержат несколько "вспомогательных" библиотек, каждую из которых можно загрузить отдельно. См. Более подробную информацию в разделе «Несколько библиотек активов» ниже.

php_file ": применимо для простых php- включений, которые не могут быть обработаны с помощью формального инструмента управления зависимостями, такого как Composer.

vendor url: (строка, необязательно) URL домашней страницы библиотеки.

download url: (строка, необязательно) URL-адрес веб-страницы, на которой можно получить библиотеку.

css : (объект, необязательный для библиотек ресурсов) Список файлов CSS, которые необходимо включить как часть библиотеки, вложенной в группы SMACSS. Структура этого свойства должна соответствовать структуре свойств «css», используемой для определения основной библиотеки .

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

files : (массив, требуется для библиотек php) Список файлов PHP, включаемых в состав библиотеки. Все пути к файлам указаны относительно корня исходного кода библиотеки.

version detector : (объект) Плагин детектора версии, используемый для расчета текущей установленной версии библиотеки. Он состоит из:

id : (строка) Идентификатор плагина определения версии в API библиотек. См. Примеры свойств конфигурации ниже.

configuration : (объект) Конфигурация, необходимая плагину для определения версии. Конкретные свойства будут зависеть от идентификатора плагина. Следующие плагины детекторов и их свойства конфигурации являются собственными для Libraries API, хотя можно создавать дополнительные плагины детекторов (подробнее см. В документации Advanced API ):« line_pattern »: считывает версию из текстового шаблона внутри файла библиотеки. Использует конфигурацию:

file : (строка) Имя файла для синтаксического анализа версии относительно пути к библиотеке.

pattern : (строка) Строка, содержащая регулярное выражение (PCRE), соответствующее версии библиотеки.

lines : (строка, необязательно) Максимальное количество строк для поиска шаблона. По умолчанию 20.

columns : (строка, необязательно) Максимальное количество символов в строке, которое необходимо учитывать. По умолчанию 200.

" static ": укажите статическую версию как часть самого определения. Использует конфигурацию:

version : (строка) Объявление статической версии.

Несколько библиотек

Отдельные библиотеки активов могут упаковывать несколько «вложенных» библиотек, которые можно загружать независимо, используя тип библиотеки «asset_multiple». Каждая подбиблиотека использует одни и те же высокоуровневые метаданные библиотеки (имя, URL-адрес поставщика и т. д.), Но может объявлять разные файловые активы. Затем подбиблиотеки идентифицируются с помощью уникального имени, которое состоит из имени библиотечного компьютера и имени компьютера подбиблиотеки, разделенных точкой (.) Разделителем (например, «example_multiple.first»). В определении библиотеки можно определить уникальные файлы ресурсов для подбиблиотеки, вложив свойства «js» и «css» под компьютерное имя подбиблиотеки. Например, определение example_multiple.json может объявлять как подбиблиотеки «example_multiple.first», так и «example_multiple.second» следующим образом:

{
  "name": "Example Library with Multiple Sub-Libraries",
  "type": "asset_multiple",
  "version_detector": {
    "id": "static",
    "configuration": {
      "version": "1.0.0"
    }
  },
  "remote_url": "http://example.com",
  "libraries": {
    "first": {
      "css": {
        "base": {
          "example.first.css": {}
        }
      },
      "js": {
        "example.first.js": {}
      }
    },
    "second": {
      "css": {
        "base": {
          "example.second.css": {}
        }
      },
      "js": {
        "example.second.js": {}
      }
    }
  }
}