walder
v4.1.3
Walder предлагает простой способ настроить веб -сайт или веб -API на вершине децентрализованных графиков знаний. Графики знаний включают данные вместе со значением этих данных. Это позволяет объединить данные с нескольких графиков знаний, даже если разные независимые стороны поддерживают или размещают их. Графики знаний могут быть размещены с помощью твердых стручков, конечных точек Sparql, интерфейсов тройного рисунка, файлов RDF и так далее. Используя переговоры о контенте, Walder предоставляет данные в этих графах знаний доступными для клиентов через HTML, RDF и JSON-LD. Пользователи определяют в файле конфигурации, который использует данные Walder и как он обрабатывает эти данные. Узнайте, какие API построены с Уолдером здесь.
Оглавление
Установите Walder по всему миру через yarn global add walder .
Для развития выполните следующие действия:
yarn install .$ yarn global add file:$(pwd) . Уолдер доступен в виде библиотеки CLI и JavaScript.
Usage: walder [options]
Options:
-v, --version output the version number
-c, --config < configFile > YAML configuration file input
-p, --port [portNumber] server port number (default: 3000)
-l, --log [level] enable logging and set logging level (one of [error, warn, info, verbose, debug]) (default: " info " )
--no-cache disable Comunica default caching
--lenient turn Comunica errors on invalid data into warnings
-h, --help output usage information // From the root directory
const Walder = require ( '.' ) ;
const configFilePath = 'path/to/configfile' ;
const port = 9000 ; // Defaults to 3000
const logging = 'info' ; // Defaults to 'info'
const cache = false ; // Defaults to true
const lenient = true ; // Defaults to false
const walder = new Walder ( configFilePath , { port , logging , cache , lenient , cwd } ) ;
walder . activate ( ) ; // Starts the server
walder . deactivate ( ) ; // Stops the serverВы записываете файл конфигурации в YAML после спецификации OpenAPI 3.0. Файл конфигурации должен иметь следующую структуру:
openapi : 3.0.2
info : # OpenAPI metadata
title : ' Example site '
version : 0.1.0
x-walder-resources : # Directories used by Walder - OPTIONAL
root : # Path to the root folder of the directories used by Walder (absolute or relative to the directory containing the config file) - OPTIONAL (default: .)
views : # Path to directory containing view template files (absolute or relative to the root folder) - OPTIONAL (default: views)
pipe-modules : # Path to directory containing local pipe modules (absolute or relative to the root folder) - OPTIONAL (default: pipe-modules)
public : # Path to directory containing all files that should be available statically (e.g. stylesheets) (absolute or relative to the root folder) - OPTIONAL (default: public)
layouts : # Path to directory containing all layout template files that can be used by view template files (absolute or relative to the root folder) - OPTIONAL (default: layouts)
x-walder-datasources : # Default list of data sources
- ... # E.g. link to SPARQL endpoint or a GraphQL-LD query
paths : # List of path entries
path-entry-1 :
...
path-entry-2 :
...
x-walder-errors : # Default error page views - status codes with files containing the HTML view template (absolute path or relative to the views directory)
404 : ...
500 : ...
... Ключ x-walder-resources файла конфигурации содержит пути к каталогам, используемым Walder. Этот ключ и его значения необязательны. Если пользователь не дает пути, Уолдер использует следующие значения по умолчанию относительно каталога файла конфигурации.
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts Чтобы Уолдер не обнародовал неправильные файлы, когда пользователь не дает пути в public область, Уолдер public новый каталог, если он не найдет этот каталог в текущем рабочем каталоге и использует это.
Вход пути определяет маршрут и имеет следующую структуру:
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
json-ld-context : ... # The JSON-LD corresponding to the GraphQL query
sparql-query : ... # One or more SPARQL queries
json-ld-frame : ... # A JSON-LD frame that should be applied to the result of a SPARQL query
options : # Global options that will be applied to all the graphql-queries of this path (OPTIONAL)
datasources : # Query specific datasources (OPTIONAL)
additional : ... # Boolean stating that the following datasources are meant to be used on top of the default ones
sources : # List of query specific datasources
- ... # E.g. link to SPARQL endpoint
x-walder-postprocessing : # The (list of) pipe modules used for postprocessing
module-id : # Identifier of the pipe module
source : ... # Path leading to source code of the pipe module (absolute path or relative to the pipe-modules directory)
parameters : # the parameters for the pipe module (OPTIONAL)
- _data # (DEFAULT) this gives all the data, but all paths in the data object are supported (e.g. _data.0.employee)
- ... # Additional parameters if your function supports those (OPTIONAL)
responses : # Status codes with files containing the HTML view template (absolute path or relative to the views directory)
200 : ... # (REQUIRED)
500 : ... # (OPTIONAL)Следующая команда запускает сервер на порту 3000 (по умолчанию), используя пример файла конфигурации.
$ walder -c example/config.yaml
Это запустит сервер на localhost:3000 со следующими маршрутами:
В приведенной выше записи, пользователь определил options как глобальный (необязательный) идентификатор, который Уолдер использует для каждого запроса этого пути. У нас есть два варианта, в которых мы можем выбрать: sort и remove-duplicates . С данным синтаксисом:
options :
sort : # Enable sorting on the data (OPTIONAL)
object : # JSONPath to the object you want to sort for
selectors : # The values inside the object over which you want to sort
- ... # The default option when you want ascending order, just give the value (JSONPath notation supported for further nesting)
- value : ... # When you want descending order, specify the value/order (JSONPath notation supported for further nesting)
order : desc
remove-duplicates : # Enable the removal of duplicates of the data (OPTIONAL)
object : ... # The JSONPath tot the object that you want to compare
value : ... # The value that has to be compared to determine whether it's duplicate (JSONPath notation is also supported for further nesting) Если вы не хотите, чтобы options были глобальными для всего пути, вы можете определить options на запрос.
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
name :
query : ... # The GraphQL query
options : # options that will be applied only to this specific graphql-query (OPTIONAL)
...Следующая команда запускает сервер, используя этот файл конфигурации.
$ walder -c example/config-sorting-duplicates.yaml
Это запустит сервер на localhost:3000 со следующими маршрутами:
Вы можете разделить файл конфигурации в нескольких файлах, используя ключевое слово $ref . Мы следуем спецификации OpenAPI 3.0, которая объясняет, как использовать ссылки.
При первом упоминании вам необходимо использовать путь, начиная с каталога файла конфигурации, но если указанный файл имеет свои ссылки, он может использовать пути относительно своего собственного местоположения, как показано ниже.
Фактический файл конфигурации, ссылающийся на его пути
openapi : 3.0.2
info :
title : ' Example site '
version : 0.1.0
x-walder-resources :
path : ./
views : views
pipe-modules : pipeModules
public : public
x-walder-datasources :
- http://fragments.dbpedia.org/2016-04/en
paths :
/music/{musician} :
$ref : ' ./paths/music_musician.yaml '
/movies/{actor} :
$ref : ' ./paths/movies_actor.yaml '
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html Ниже вы видите ./example/paths/movies_actor.yaml со ссылкой на путь относительно его собственного местоположения
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : path
name : actor
required : true
schema :
type : string
description : The target actor
x-walder-query :
$ref : ' ../walderQueryInfo/movies_actor_info.yaml '
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
Используя переговоры о контенте, Walder делает следующие выходные форматы доступными:
Walder использует GraphQL-LD-Comunica для выполнения запросов GraphQL и @Comunica/Query-Sparql, чтобы выполнить запросы sparql. Результатом запроса GraphQL-LD является данные JSON. Уолдер сначала превращает его в JSON-LD. Это обеспечивает конверсию в другие форматы RDF во время переговоров по контенту. Результатом запроса Sparql является множество квадроциклов. Если указан кадр JSON-LD, квадраты преобразуются в JSON-LD. Из -за важности согласования контента поддерживаются только запросы построения.
Уолдер использует Consolidate для автоматического извлечения соответствующего двигателя для данного шаблона. Это означает, что поддерживаемые шаблонные двигатели зависят от консолидации.
Вы можете использовать разные шаблонные двигатели для разных маршрутов, например, мопс производит HTML одного маршрута, в то время как руль отдает HTML другого маршрута. Уолдер делает все это, глядя на расширение файла данного шаблона.
Шаблоны могут использоваться как в представлениях, так и в макетах. Таким образом, мы назваем их представлять шаблоны и шаблоны макетов , чтобы различить.
Результаты запросов, указанные в файле конфигурации для маршрута, доступны для рендеринга в шаблонах вида в качестве данных.
data . В случае запроса GraphQL-LD каждый объект будет массивом, если запрос не был единственным. Songs.handlebars является примером потребления результата единственного запроса в маршруте /music/{musician} в этом файле конфигурации. songs_movies.handlebars является примером потребления результатов двух запросов в маршруте /artist/{artist} в этом файле конфигурации.
В случае запроса Sparql каждый объект представляет собой массив квадратов, если не указано кадр JSON-LD. Иначе это будет объект JSON-LD.
Использование макетов-отличный способ избежать повторения в шаблонах представления, специфичных для маршрута. Постоянные HTML -структуры, такие как заголовки, нижние колонтитулы, навигационные стержни и другое содержимое, предназначенные для появления в нескольких маршрутах, предпочтительны в файлах макета .
Файл шаблона макета может быть указан в файле шаблона представления с помощью layout поля метаданных переднего вещества. Он должен содержать имя файла, доступное в расположении layouts , определенных в файле конфигурации. Это может содержать относительный путь перед именем файла.
Пример просмотра файла шаблона, указанный на макете:
---
layout: my-layout.pug
---
// view template continues here
Уолдер помещает внутреннее содержание HTML, сгенерированное из файла шаблона представления в данные, направленные в файл шаблона макета в качестве объекта с именем content .
Файл шаблона макета - еще один шаблон. Обычно он расширяет это внутреннее содержание HTML в положении по своему выбору.
Простой пример мопса (ум !{content} ):
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
В дополнение к результатам запроса, Уолдер добавляет метаданные переднего вещества, указанные в шаблонах видов, в качестве дополнительных атрибутов к данным.
Имя каждого дополнительного атрибута равна указанному имени поля метаданных. Следующее поле метаданных зарезервировано: layout , content , data и имена, назначенные запросам на маршрутах, имеющих несколько запросов (см. Выше).
Эти атрибуты доступны для шаблона представления и для шаблона макета, на который он ссылается, если таковые имеются.
Пример просмотра файла шаблона, указавший поле метаданных переднего материала и чтение этого поля (разумный #{a1} ):
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
Пример просмотра файла шаблона, указанный шаблон макета и другое поле метаданных переднего материала:
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
Пример соответствующего шаблона макета (Layout-fm.pug) Чтение этого поля (разумный #{a2} ):
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
При анализе файла конфигурации Уолдер также подтверждает правильность и полноту ввода. Когда Уолдер проанализировал весь файл конфигурации и обнаружил ошибки, Уолдер возвращает все ошибки и выходы.
На данный момент Уолдер подтверждает следующее:
200~x-walder-input-text/html . Walder связывает страницы ошибок с определенным кодом состояния HTTP. Вы можете определить страницы ошибок по умолчанию, но также также страницы с конкретными ошибками пути, добавив их к ключу responses в соответствующем вводе пути.
404 : страница не найдена500 : Ошибка внутреннего сервера 500 : Не удалось применить заданные модули трубки 404 : ожидаемая переменная не была дана500 : не удалось выполнить заданный запросКогда вы запускаете Walder, используя следующую команду:
$ walder -c example/config-errors.yaml
Следующие пути приводят к ошибкам:
404 (глобальная: страница не найдена)500 (модули труб: не могут применить заданные модули труб)500 (graphql-ld: не удалось выполнить заданный запрос) В следующем конфигурационном отрывке будет использоваться специфический шаблон moviesServerError.handlebars по ошибкам, ведущим к коду состояния 500 при навигации по /movies .
Когда требуемый actor параметров запроса не пройден, Уолдер возвращает код состояния 404 . Walder будет использовать файл по умолчанию error404.html , так как файл конфигурации не имеет шаблона представления HTML-конкретного пути для соответствующего статуса.
...
paths :
/movies :
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : query
name : actor
schema :
type : string
minimum : 0
description : The actor from whom the movies are requested
required : true
x-walder-query :
graphql-query : >
{
id @single
... on Film {
starring(label: $actor) @single
}
}
json-ld-context : >
{
"@context": {
"Film": "http://dbpedia.org/ontology/Film",
"label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
"starring": "http://dbpedia.org/ontology/starring"
}
}
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
500 :
description : internal movie server error
x-walder-input-text/html : moviesServerError.handlebars
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html При разработке вашего веб -сайта вы, вероятно, хотите, чтобы ваш веб -сайт перезагрузил, внося изменения в config.yaml . Вы можете легко сделать это с помощью NPM-наблюдения. Смотрите фрагмент package.json ниже, как начать
{
"watch" : {
"run" : " config.yaml "
},
"scripts" : {
"run" : " walder -c config.yaml --no-cache " ,
"watch" : " npm-watch "
},
"dependencies" : {
"walder" : " ^2.0.1 "
},
"devDependencies" : {
"npm-watch" : " ^0.7.0 "
}
} Запустите npm run watch , а Walder Reloads Every config.yaml изменение!
| Библиотека | Лицензия |
|---|---|
| @comunica | Грань |
| принимает | Грань |
| Аксиос | Грань |
| чай | Грань |
| командир | Грань |
| консолидировать | Грань |
| отлаживать | Грань |
| выражать | Грань |
| Передняя вещество | Грань |
| FS-Extra | Грань |
| graphql-ld | Грань |
| Graphql-Ld-Comunica | Грань |
| руль | Грань |
| is-html | Грань |
| нефрито-хэндлебары | Грань |
| json-refs | Грань |
| jsonld | BSD-3-CLAUSE |
| jsonpath | Грань |
| Markdown-It | Грань |
| мокко | Грань |
| Морган | Грань |
| n3 | Грань |
| Объектный путь | Грань |
| мопс | Грань |
| супер -тест | Грань |
| TMP | Грань |
| Уинстон | Грань |
| Ямл | ISC |
Вы построили что -то Уолдер и хотите добавить его в список? Пожалуйста, создайте запрос на привлечение!
Этот код защищен авторским правом © 2019–2020 Университетом Гента - IMEC и выпущен по лицензии MIT.
