walder
v4.1.3
Walder ofrece una manera fácil de configurar un sitio web o una API web además de los gráficos de conocimiento descentralizados. Los gráficos de conocimiento incorporan datos junto con el significado de esos datos. Esto permite combinar datos de múltiples gráficos de conocimiento, incluso si las partes diferentes e independientes los mantienen o alojanlos. Los gráficos de conocimiento se pueden alojar a través de vainas sólidas, puntos finales SPARQL, interfaces de fragmentos de patrón triple, archivos RDF, etc. Utilizando la negociación de contenido, Walder pone los datos en estos gráficos de conocimiento a disposición de los clientes a través de HTML, RDF y JSON-LD. Los usuarios definen en un archivo de configuración qué datos usa Walder y cómo procesa estos datos. Descubra qué API se construyen con Walder aquí.
Tabla de contenido
Instale Walder a nivel mundial a través de yarn global add walder .
Para el desarrollo, siga estos pasos:
yarn install .$ yarn global add file:$(pwd) . Walder está disponible como una biblioteca CLI y 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 serverEscribe un archivo de configuración en YAML después de la especificación OpenAPI 3.0. El archivo de configuración debe tener la siguiente estructura:
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 : ...
... La tecla x-walder-resources del archivo de configuración contiene rutas a los directorios utilizados por Walder. Esta clave y sus valores son opcionales. Si un usuario no da rutas, Walder usa los siguientes valores predeterminados en relación con el directorio del archivo de configuración.
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts Para evitar que Walder haga público los archivos incorrectos, cuando un usuario no da una ruta al campo public , Walder crea un nuevo public de directorio si no encuentra este directorio en el directorio de trabajo actual y usa ese.
Una entrada de ruta define una ruta y tiene la siguiente estructura:
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)El siguiente comando inicia un servidor en el puerto 3000 (predeterminado) usando un archivo de configuración de ejemplo.
$ walder -c example/config.yaml
Esto iniciará un servidor en localhost:3000 con las siguientes rutas:
En la entrada de ruta anterior, el usuario definió options como un identificador global (opcional) que Walder usa para cada consulta de esa ruta. Tenemos dos opciones en las que podemos elegir: sort y remove-duplicates . Con sintaxis dada:
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) Si no desea que options sean globales para toda la ruta, puede definir options por consulta.
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)
...El siguiente comando inicia un servidor usando este archivo de configuración.
$ walder -c example/config-sorting-duplicates.yaml
Esto iniciará un servidor en localhost:3000 con las siguientes rutas:
Puede dividir un archivo de configuración en varios archivos, utilizando la palabra clave $ref . Seguimos la especificación de OpenApi 3.0 que explica cómo usar la referencia.
Cuando se hace referencia por primera vez, debe usar la ruta que comienza desde el directorio del archivo de configuración, pero si el archivo referenciado tiene referencias en sí, puede usar rutas relativas a su propia ubicación, como se muestra a continuación.
El archivo de configuración real que hace referencia a sus rutas
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 A continuación se ve ./example/paths/movies_actor.yaml con referencia con ruta relativa a su propia ubicación
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
Usando la negociación de contenido, Walder hace que los siguientes formatos de salida estén disponibles:
Walder usa GraphQL-LD-Comunica para ejecutar las consultas GraphQL y @Comunica/Query-Sparql para ejecutar consultas SPARQL. El resultado de una consulta GraphQL-LD son los datos JSON. Walder primero lo convierte en JSON-LD. Esto permite la conversión a otros formatos RDF durante la negociación de contenido. El resultado de una consulta SPARQL es una variedad de quads. Si se especifica un marco JSON-LD, los quads se convierten a JSON-LD. Debido a la importancia de la negociación de contenido, solo se respaldan consultas de construcción.
Walder usa Consolidate para recuperar automáticamente el motor correspondiente para una plantilla determinada. Esto significa que los motores de plantilla compatibles dependen de consolidar.
Puede usar diferentes motores de plantilla para diferentes rutas, por ejemplo, PUG renderiza el HTML de una ruta, mientras que el manillar representa el HTML de otra ruta. Walder hace todo esto mirando la extensión del archivo de la plantilla dada.
Las plantillas se pueden usar en vistas, así como en diseños. Por lo tanto, los nombraremos plantillas de vista y plantillas de diseño para distinguir.
Los resultados de las consultas, especificadas en el archivo de configuración para una ruta, están disponibles para representar las plantillas de vista como datos.
data . En el caso de una consulta GraphQL-LD, cada objeto será una matriz, a menos que la consulta fuera singularizada. Songs.HandleBars es un ejemplo del consumo del resultado de la consulta única en la ruta /music/{musician} en este archivo de configuración. Songs_movies.handleBars es un ejemplo del consumo de los resultados de las dos consultas en la ruta /artist/{artist} en este archivo de configuración.
En el caso de una consulta SPARQL, cada objeto es una matriz de quads si no se especifica un marco JSON-LD. De lo contrario, será un objeto JSON-LD.
El uso de diseños es una excelente manera de evitar la repetición en las plantillas de vista específicas de ruta. Las estructuras HTML reutilizables, como encabezados, pies de página, barras de navegación y otros contenidos, destinados a aparecer en múltiples rutas, son preferibles especificadas en archivos de diseño .
Se puede especificar un archivo de plantilla de diseño en un archivo de plantilla de vista, mediante el layout del campo de metadatos delanteros. Debe contener un nombre de archivo, disponible en la ubicación layouts definidos en el archivo de configuración. Puede contener una ruta relativa frente al nombre de archivo.
Ejemplo de vista de plantilla de vista especificando un diseño:
---
layout: my-layout.pug
---
// view template continues here
Walder coloca los contenidos HTML internos generados a partir del archivo de plantilla de vista en los datos reenviados al archivo de plantilla de diseño como un objeto llamado content .
El archivo de plantilla de diseño es otra plantilla. Por lo general, amplía estos contenidos HTML internos en la posición de su elección.
Un ejemplo simple de pug (mente el !{content} ):
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
Además de los resultados de la consulta, Walder agrega metadatos delanteros, especificados en las plantillas de vista, como atributos adicionales a los datos.
El nombre de cada atributo adicional es igual al nombre del campo de metadatos proporcionado. El siguiente campo de metadatos se reserva: layout , content , data y los nombres asignados a consultas en rutas que tienen múltiples consultas (ver arriba).
Estos atributos están disponibles para la plantilla de vista y para la plantilla de diseño a la que se refiere, si es que hay.
Ejemplo de vista de plantilla de vista especificando un campo de metadatos delantero y lectura de ese campo (mente el #{a1} )::
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
File de plantilla de vista de ejemplo, especificando una plantilla de diseño y otro campo de metadatos delanteros:
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
Ejemplo de plantilla de diseño correspondiente (Layout-FM.Pug) Lectura de ese campo (Mind the #{a2} )::
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
Mientras analiza el archivo de configuración, Walder también valida la corrección e integridad de la entrada. Cuando Walder ha analizado todo el archivo de configuración y encontró errores, Walder devuelve todos los errores y salidas.
Por el momento, Walder valida lo siguiente:
200~x-walder-input-text/html en entradas. Walder vincula las páginas de error a un cierto código de estado HTTP. Puede definir páginas de error predeterminadas, pero también páginas de error específicas de ruta agregándolas a la clave responses en la entrada de ruta correspondiente.
404 : página no encontrada500 : error de servidor interno 500 : no se pudo aplicar los módulos de tubería dados 404 : no se dio la variable esperada500 : no pudo ejecutar la consulta dadaCuando ejecuta Walder usando el siguiente comando:
$ walder -c example/config-errors.yaml
Las siguientes rutas conducen a errores:
404 (Global: Página no encontrada)500 (módulos de tubería: no se pudo aplicar los módulos de tubería dados)500 (GraphQL-LD: no pudo ejecutar la consulta dada) El 500 extracto de archivo de configuración utilizará la plantilla /movies vista de moviesServerError.handlebars de ruta.
Cuando no se pasa el actor de parámetro de consulta requerido, Walder devuelve el código de estado 404 . Walder usará el error404.html predeterminado404.html ya que el archivo de configuración no tiene una plantilla de vista HTML específica de ruta para el estado correspondiente.
...
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 Mientras desarrolla su sitio web, probablemente desee que su sitio web recargue mientras realiza cambios en config.yaml . Puede hacerlo fácilmente usando NPM-Watch. Vea el fragmento package.json a continuación sobre cómo comenzar
{
"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 "
}
} Ejecute npm run watch y Walder recarga cada cambio config.yaml .
| Biblioteca | Licencia |
|---|---|
| @Comunica | MIT |
| aceptación | MIT |
| axios | MIT |
| chai | MIT |
| comandante | MIT |
| consolidar | MIT |
| depurar | MIT |
| expresar | MIT |
| martillo delantero | MIT |
| FS-Extra | MIT |
| GraphQL-LD | MIT |
| GraphQl-LD-Comunica | MIT |
| bigote daliniano | MIT |
| is-html | MIT |
| jade-to-handlebars | MIT |
| JSON-REFS | MIT |
| jsond | Cláusula BSD-3 |
| jsonpath | MIT |
| markdown-it | MIT |
| moca | MIT |
| morgan | MIT |
| N3 | MIT |
| ruta de objeto | MIT |
| doguillo | MIT |
| suplente | MIT |
| TMP | MIT |
| Winston | MIT |
| yaml | ISC |
¿Construyó algo Walder y quiere agregarlo a la lista? ¡Cree una solicitud de extracción!
Este código tiene derechos de autor © 2019–2020 por Ghent University - IMEC y publicado bajo la licencia MIT.
