walder
v4.1.3
Walder menawarkan cara mudah untuk mengatur situs web atau API web di atas grafik pengetahuan terdesentralisasi. Grafik pengetahuan menggabungkan data bersama dengan arti data itu. Ini memungkinkan untuk menggabungkan data dari beberapa grafik pengetahuan, bahkan jika pihak yang berbeda dan independen memelihara atau meng -host mereka. Grafik pengetahuan dapat di -host melalui pod padat, titik akhir SPARQL, antarmuka fragmen pola triple, file RDF, dan sebagainya. Menggunakan negosiasi konten, Walder membuat data dalam grafik pengetahuan ini tersedia untuk klien melalui HTML, RDF, dan JSON-LD. Pengguna menentukan dalam file konfigurasi yang digunakan data Walder dan bagaimana memproses data ini. Cari tahu API mana yang dibangun dengan Walder di sini.
Daftar isi
Instal Walder secara global melalui yarn global add walder .
Untuk pengembangan, ikuti langkah -langkah ini:
yarn install .$ yarn global add file:$(pwd) . Walder tersedia sebagai perpustakaan CLI dan 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 serverAnda menulis file konfigurasi di YAML mengikuti spesifikasi OpenAPI 3.0. File konfigurasi harus memiliki struktur berikut:
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 : ...
... Kunci x-walder-resources dari file config berisi jalur ke direktori yang digunakan oleh Walder. Kunci ini dan nilainya opsional. Jika pengguna tidak memberikan jalur, Walder menggunakan nilai default berikut relatif terhadap direktori file konfigurasi.
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts Untuk mencegah Walder dari membuat file yang salah publik, ketika pengguna tidak memberikan jalur ke bidang public , Walder menciptakan public direktori baru jika tidak menemukan direktori ini di direktori kerja saat ini dan menggunakan yang itu.
Entri jalur mendefinisikan rute dan memiliki struktur berikut:
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)Perintah berikut memulai server pada port 3000 (default) menggunakan file konfigurasi contoh.
$ walder -c example/config.yaml
Ini akan memulai server di localhost:3000 dengan rute berikut:
Dalam entri jalur di atas, options yang ditentukan pengguna sebagai pengidentifikasi global (opsional) yang digunakan Walder untuk setiap pertanyaan dari jalur itu. Kami memiliki dua opsi di mana kami dapat memilih: sort dan remove-duplicates . Dengan sintaks yang diberikan:
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) Jika Anda tidak ingin options menjadi global untuk seluruh jalur, Anda dapat mendefinisikan options per kueri.
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)
...Perintah berikut memulai server menggunakan file konfigurasi ini.
$ walder -c example/config-sorting-duplicates.yaml
Ini akan memulai server di localhost:3000 dengan rute berikut:
Anda dapat membagi file konfigurasi di beberapa file, menggunakan kata kunci $ref . Kami mengikuti spesifikasi OpenAPI 3.0 yang menjelaskan cara menggunakan referensi.
Ketika pertama kali direferensikan, Anda perlu menggunakan jalur yang dimulai dari direktori file konfigurasi, tetapi jika file yang direferensikan memiliki referensi itu sendiri, ia dapat menggunakan jalur relatif terhadap lokasinya sendiri, seperti yang ditunjukkan di bawah ini.
File konfigurasi aktual merujuk jalurnya
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 Di bawah ini Anda lihat ./example/paths/movies_actor.yaml dengan referensi dengan jalur relatif terhadap lokasinya sendiri
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
Menggunakan negosiasi konten, Walder menyediakan format output berikut:
Walder menggunakan GraphQL-LD-Comunica untuk menjalankan kueri GraphQL dan @comunica/kueri-SPARQL untuk menjalankan kueri SPARQL. Hasil kueri GraphQL-LD adalah data JSON. Walder pertama kali mengubahnya menjadi JSON-LD. Ini memungkinkan konversi ke format RDF lainnya selama negosiasi konten. Hasil dari kueri SPARQL adalah array paha depan. Jika bingkai JSON-LD ditentukan, paha depan dikonversi menjadi JSON-LD. Karena pentingnya negosiasi konten, hanya konstruksi pertanyaan yang didukung.
Walder menggunakan Konsolidasi untuk secara otomatis mengambil mesin yang sesuai untuk templat yang diberikan. Ini berarti bahwa mesin templat yang didukung tergantung pada konsolidasi.
Anda dapat menggunakan mesin templat yang berbeda untuk rute yang berbeda, misalnya, Pug membuat HTML satu rute, sementara setang membuat HTML rute lain. Walder melakukan ini semua dengan melihat ekstensi file dari template yang diberikan.
Templat dapat digunakan dalam tampilan serta tata letak. Jadi kami akan memberi nama mereka untuk melihat templat dan templat tata letak untuk membedakan.
Hasil kueri, yang ditentukan dalam file konfigurasi untuk rute, tersedia untuk rendering dalam templat tampilan sebagai data.
data . Dalam kasus kueri GraphQL-LD, setiap objek akan menjadi array, kecuali jika kueri itu singularized. Songs.Handlebars adalah contoh konsumsi hasil kueri tunggal di rute /music/{musician} dalam file konfigurasi ini. songs_movies.handlebars adalah contoh konsumsi hasil dua pertanyaan di rute /artist/{artist} dalam file konfigurasi ini.
Dalam kasus kueri SPARQL, setiap objek adalah array paha depan jika tidak ada bingkai JSON-LD yang ditentukan. Kalau tidak, itu akan menjadi objek JSON-LD.
Menggunakan tata letak adalah cara yang bagus untuk menghindari pengulangan dalam templat tampilan rute. Struktur HTML yang dapat digunakan kembali seperti header, footer, bilah navigasi dan konten lainnya, yang dimaksudkan untuk muncul di beberapa rute, lebih disukai ditentukan dalam file tata letak .
File template tata letak dapat ditentukan dalam file templat tampilan, dengan cara layout bidang metadata front-matter. Ini harus berisi nama file, tersedia di lokasi layouts yang ditentukan dalam file konfigurasi. Ini mungkin berisi jalur relatif di depan nama file.
Contoh Tampilan File Template Menentukan tata letak:
---
layout: my-layout.pug
---
// view template continues here
Walder memasukkan konten HTML dalam yang dihasilkan dari file Template View ke dalam data yang diteruskan ke file template tata letak sebagai objek bernama content .
File template tata letak adalah templat lain. Biasanya memperluas konten HTML bagian dalam ini pada posisi pilihannya.
Contoh Pug Sederhana (Pikirkan !{content} ):
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
Selain hasil kueri, Walder menambahkan metadata materi depan, ditentukan dalam templat tampilan, sebagai atribut tambahan untuk data.
Setiap nama atribut tambahan sama dengan nama bidang metadata yang disediakan. Bidang metadata berikut dicadangkan: layout , content , data , dan nama yang ditetapkan untuk pertanyaan di rute yang memiliki beberapa kueri (lihat di atas).
Atribut -atribut ini tersedia untuk template tampilan dan templat tata letak yang dimaksud, jika ada.
Contoh Tampilan File Template Menentukan bidang metadata front-materi dan membaca bidang itu (ingat #{a1} ):
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
Contoh Tampilan File Template, Menentukan Template Tata Letak dan Bidang Metadata Minat Depan Lainnya:
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
Contoh Template Tata Letak yang sesuai (tata letak-fm.pug) Membaca bidang itu (Pikirkan #{a2} ):
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
Saat parsing file konfigurasi, Walder juga memvalidasi kebenaran dan kelengkapan input. Ketika Walder telah menguraikan seluruh file konfigurasi dan menemukan kesalahan, Walder mengembalikan semua kesalahan dan keluar.
Saat ini, Walder memvalidasi yang berikut:
200~x-walder-input-text/html . Walder mengikat halaman kesalahan ke kode status HTTP tertentu. Anda dapat mendefinisikan halaman kesalahan default, tetapi juga jalur halaman kesalahan spesifik dengan menambahkannya ke tombol responses di entri jalur yang sesuai.
404 : Halaman tidak ditemukan500 : Kesalahan server internal 500 : Tidak dapat menerapkan modul pipa yang diberikan 404 : Variabel yang diharapkan tidak diberikan500 : Tidak dapat menjalankan kueri yang diberikanSaat Anda menjalankan Walder menggunakan perintah berikut:
$ walder -c example/config-errors.yaml
Jalur berikut menyebabkan kesalahan:
404 (global: halaman tidak ditemukan)500 (modul pipa: tidak dapat menerapkan modul pipa yang diberikan)500 (graphql-ld: tidak dapat menjalankan kueri yang diberikan) Kutipan file konfigurasi berikut akan menggunakan templat spesifik moviesServerError.handlebars Template tentang kesalahan yang mengarah ke kode status 500 saat menavigasi ke /movies .
Ketika actor parameter kueri yang diperlukan tidak dilewati, Walder mengembalikan kode status 404 . Walder akan menggunakan file default error404.html karena file konfigurasi tidak memiliki template tampilan html spesifik jalur untuk status yang sesuai.
...
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 Saat mengembangkan situs web Anda, Anda mungkin ingin situs web Anda memuat ulang saat membuat perubahan ke config.yaml . Anda dapat dengan mudah melakukan ini menggunakan npm-watch. Lihat cuplikan package.json di bawah ini tentang cara memulai
{
"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 "
}
} Jalankan npm run watch dan Walder memuat ulang setiap config.yaml perubahan!
| Perpustakaan | Lisensi |
|---|---|
| @comunica | Mit |
| menerima | Mit |
| Axios | Mit |
| Chai | Mit |
| komandan | Mit |
| mengkonsolidasikan | Mit |
| debug | Mit |
| cepat | Mit |
| Materi depan | Mit |
| FS-Extra | Mit |
| graphql-ld | Mit |
| GraphQL-LD-Comunica | Mit |
| setang | Mit |
| is-html | Mit |
| Jade-to-Handlebars | Mit |
| JSON-REFS | Mit |
| jsonld | BSD-3-Clause |
| jsonpath | Mit |
| Markdown-it | Mit |
| moka | Mit |
| Morgan | Mit |
| n3 | Mit |
| jalur objek | Mit |
| Pug | Mit |
| supertest | Mit |
| TMP | Mit |
| Winston | Mit |
| yaml | ISC |
Apakah Anda membangun sesuatu Walder dan ingin menambahkannya ke daftar? Harap buat permintaan tarik!
Kode ini dilindungi hak cipta © 2019–2020 oleh Ghent University - IMEC dan dirilis di bawah lisensi MIT.
