walder
v4.1.3
Walder offre un moyen facile de créer un site Web ou une API Web en plus des graphiques de connaissances décentralisés. Les graphiques de connaissances intègrent des données avec la signification de ces données. Cela permet de combiner des données à partir de plusieurs graphiques de connaissances, même si différentes parties indépendantes les maintiennent ou les hébergent. Les graphiques de connaissances peuvent être hébergés via des pods solides, des points de terminaison SPARQL, des interfaces de fragments de motifs triples, des fichiers RDF, etc. En utilisant la négociation de contenu, Walder met les données de ces graphiques de connaissances à la disposition des clients via HTML, RDF et JSON-LD. Les utilisateurs définissent dans un fichier de configuration que les données que Walder utilise et comment elle traite ces données. Découvrez les API construites avec Walder ici.
Table des matières
Installez Walder à l'échelle mondiale via yarn global add walder .
Pour le développement, suivez ces étapes:
yarn install .$ yarn global add file:$(pwd) . Walder est disponible en bibliothèque CLI et 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 serverVous écrivez un fichier de configuration dans YAML en suivant la spécification OpenAPI 3.0. Le fichier de configuration doit avoir la structure suivante:
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 clé x-walder-resources du fichier de configuration contient des chemins de main vers les répertoires utilisés par Walder. Cette clé et ses valeurs sont facultatives. Si un utilisateur ne donne pas de chemins, Walder utilise les valeurs par défaut suivantes par rapport au répertoire du fichier de configuration.
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts Pour empêcher Walder de rendre les mauvais fichiers publics, lorsqu'un utilisateur ne donne pas de chemin vers le domaine public , Walder crée un nouveau répertoire public s'il ne trouve pas ce répertoire dans le répertoire de travail actuel et utilise celui-ci.
Une entrée de chemin définit un itinéraire et a la structure suivante:
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)La commande suivante démarre un serveur sur le port 3000 (par défaut) à l'aide d'un exemple de fichier de configuration.
$ walder -c example/config.yaml
Cela démarrera un serveur sur localhost:3000 avec les routes suivantes:
Dans l'entrée de chemin ci-dessus, l'utilisateur a défini options comme un identifiant global (facultatif) que Walder utilise pour chaque requête de ce chemin. Nous avons deux options où nous pouvons choisir: sort et remove-duplicates . Avec syntaxe donnée:
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 vous ne voulez pas que options soient globales pour l'ensemble du chemin, vous pouvez définir options par requête.
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)
...La commande suivante démarre un serveur à l'aide de ce fichier de configuration.
$ walder -c example/config-sorting-duplicates.yaml
Cela démarrera un serveur sur localhost:3000 avec les routes suivantes:
Vous pouvez diviser un fichier de configuration dans plusieurs fichiers, à l'aide du mot clé $ref . Nous suivons la spécification OpenAPI 3.0 qui explique comment utiliser le référencement.
Lors de la première référence, vous devez utiliser le chemin d'accès à partir du répertoire du fichier de configuration, mais si le fichier référencé a lui-même des références, il peut utiliser des chemins par rapport à son propre emplacement, comme indiqué ci-dessous.
Le fichier de configuration réel faisant référence à ses chemins
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 Ci-dessous, vous voyez ./example/paths/movies_actor.yaml en référence avec le chemin par rapport à son propre emplacement
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
À l'aide de la négociation de contenu, Walder met les formats de sortie suivants disponibles:
Walder utilise GraphQL-LD-COMUNICA pour exécuter les requêtes GraphQL et @ Comunica / Query-Sparql pour exécuter des requêtes SPARQL. Le résultat d'une requête GraphQL-LD est une données JSON. Walder le convertit d'abord en json-ld. Cela permet la conversion à d'autres formats RDF lors de la négociation de contenu. Le résultat d'une requête SPARQL est un tableau de quads. Si une trame JSON-LD est spécifiée, les quads sont convertis en JSON-LD. En raison de l'importance de la négociation de contenu, seules les requêtes de construction sont prises en charge.
Walder utilise Consolidate pour récupérer automatiquement le moteur correspondant pour un modèle donné. Cela signifie que les moteurs de modèle pris en charge dépendent de la consolidation.
Vous pouvez utiliser différents moteurs de modèles pour différentes itinéraires, par exemple, PUG rend HTML d'une route, tandis que le guidon rend le HTML d'un autre itinéraire. Walder fait tout cela en regardant l'extension de fichier du modèle donné.
Les modèles peuvent être utilisés dans les vues ainsi que dans les dispositions. Nous les nommerons donc de voir les modèles et les modèles de mise en page afin de distinguer.
Les résultats des requêtes, spécifiées dans le fichier de configuration pour un itinéraire, sont disponibles pour le rendu dans les modèles d'opinion sous forme de données.
data . Dans le cas d'une requête GraphQL-LD, chaque objet sera un tableau, à moins que la requête ne soit singularisée. Songs.Handlebars est un exemple de la consommation du résultat de la requête unique dans la route /music/{musician} dans ce fichier de configuration. Songs_movies.Handlebars est un exemple de la consommation des résultats des deux requêtes dans la route /artist/{artist} dans ce fichier de configuration.
Dans le cas d'une requête SPARQL, chaque objet est un tableau de quads si aucune trame JSON-LD n'est spécifiée. Sinon, ce sera un objet JSON-LD.
L'utilisation de dispositions est un excellent moyen d'éviter la répétition dans les modèles de vue spécifiques à l'itinéraire. Les structures HTML réutilisables telles que les en-têtes, les pieds de page, les barres de navigation et autres contenus, destinés à apparaître dans plusieurs itinéraires, sont préférables spécifiées dans les fichiers de mise en page .
Un fichier de modèle de mise en page peut être spécifié dans un fichier de modèle de vue, au moyen de layout des champs de métadonnées de la matière de métaux. Il doit contenir un nom de fichier, disponible à l'emplacement layouts défini dans le fichier de configuration. Il peut contenir un chemin relatif devant le nom de fichier.
Exemple d'affichage du modèle de modèle spécifiant une mise en page:
---
layout: my-layout.pug
---
// view template continues here
Walder met les contenus HTML intérieurs générés à partir du fichier de modèle de vue dans les données transmises au fichier de modèle de mise en page en tant qu'objet nommé content .
Le fichier de modèle de mise en page est encore un autre modèle. Il élargit généralement ces teneurs en HTML intérieures à la position de son choix.
Un exemple de carburant simple (Mind the !{content} ):
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
En plus des résultats de la requête, Walder ajoute des métadonnées de la matière frontale, spécifiées dans les modèles de vue, en tant qu'attributs supplémentaires aux données.
Le nom de chaque attribut supplémentaire est égal au nom du champ de métadonnées fourni. Le champ de métadonnées suivant est réservé: layout , content , data et les noms attribués aux requêtes dans les itinéraires ayant plusieurs requêtes (voir ci-dessus).
Ces attributs sont disponibles pour le modèle de vue et pour le modèle de mise en page auquel il fait référence, le cas échéant.
Exemple Voir le fichier de modèle spécifiant un champ de métadonnées de la matière de front et la lecture de ce champ (attention le #{a1} ):
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
Exemple d'affichage du modèle de modèle, spécifiant un modèle de mise en page et un autre champ de métadonnées de la matière frontale:
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
Exemple modèle de mise en page correspondant (disposition-fm.pug) en lisant ce champ (Mind the #{a2} ):
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
Lors de l'analyse du fichier de configuration, Walder valide également l'exactitude et l'exhaustivité de l'entrée. Lorsque Walder a analysé l'ensemble du fichier de configuration et trouvé des erreurs, Walder renvoie toutes les erreurs et sorties.
Pour le moment, Walder valide ce qui suit:
200~x-walder-input-text/html . Walder lie les pages d'erreur à un certain code d'état HTTP. Vous pouvez définir les pages d'erreur par défaut, mais également les pages d'erreur spécifiques au chemin de chemin en les ajoutant à la clé responses dans l'entrée de chemin correspondante.
404 : page introuvable500 : Erreur du serveur interne 500 : Impossible d'appliquer les modules de tuyaux donnés 404 : la variable attendue n'a pas été donnée500 : Impossible d'exécuter la requête donnéeLorsque vous exécutez Walder en utilisant la commande suivante:
$ walder -c example/config-errors.yaml
Les chemins suivants conduisent à des erreurs:
404 (global: page introuvable)500 (modules de tuyau: ne peut pas appliquer les modules de tuyaux donnés)500 (graphQl-ld: n'a pas pu exécuter la requête donnée) L'extrait de fichier de configuration suivant utilisera le modèle de vue spécifique moviesServerError.handlebars sur les erreurs conduisant au code d'état 500 lors de la navigation vers /movies .
Lorsque l' actor de paramètre de requête requis n'est pas adopté, Walder renvoie le code d'état 404 . Walder utilisera le fichier error404.html par défaut car le fichier de configuration n'a pas de modèle de vue HTML spécifique au chemin pour l'état correspondant.
...
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 Lors de l'élaboration de votre site Web, vous voulez probablement que votre site Web se recharge tout en apportant des modifications à config.yaml . Vous pouvez facilement le faire en utilisant NPM-watch. Voir l'extrait package.json ci-dessous sur la façon de commencer
{
"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 "
}
} Exécutez npm run watch et Walder recharge chaque config.yaml change!
| Bibliothèque | Licence |
|---|---|
| @comunica | Mit |
| accepter | Mit |
| axios | Mit |
| chai | Mit |
| commandant | Mit |
| consolider | Mit |
| déboguer | Mit |
| exprimer | Mit |
| châssis | Mit |
| FS-EXTRA | Mit |
| GraphQl-LD | Mit |
| graphql-ld-conica | Mit |
| guidon | Mit |
| is-html | Mit |
| jade-to handlebars | Mit |
| JSON-REFS | Mit |
| jsonld | Clause BSD-3 |
| jsonpath | Mit |
| Markdown-it | Mit |
| moka | Mit |
| Morgan | Mit |
| n3 | Mit |
| chemin d'objet | Mit |
| carlin | Mit |
| super-test | Mit |
| TMP | Mit |
| Winston | Mit |
| yaml | Isc |
Avez-vous construit quelque chose de Walder et souhaitez l'ajouter à la liste? Veuillez créer une demande de traction!
Ce code est protégé par des droits d'auteur © 2019-2020 par Gand University - IMEC et libéré sous la licence MIT.
