This is an automated email from the ASF dual-hosted git repository.
bdelacretaz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git
The following commit(s) were added to refs/heads/master by this push:
new f33a02b Move 'under the hood' to the README
f33a02b is described below
commit f33a02bd9ec3ba895654f7c4a7adadda823b74c2
Author: Bertrand Delacretaz <bdelacre...@apache.org>
AuthorDate: Fri May 29 10:52:13 2020 +0200
Move 'under the hood' to the README
---
org.apache.sling.graphql.samples.website/README.md | 53 ++++++++++---
.../content/graphql-website-demo.html | 92 ----------------------
2 files changed, 44 insertions(+), 101 deletions(-)
diff --git a/org.apache.sling.graphql.samples.website/README.md
b/org.apache.sling.graphql.samples.website/README.md
index 3d688aa..16ee86f 100644
--- a/org.apache.sling.graphql.samples.website/README.md
+++ b/org.apache.sling.graphql.samples.website/README.md
@@ -18,18 +18,28 @@ of results returned.
A website with rich navigation is implemented with server-side GraphQL queries
and client-side
Handlebars templates for HTML rendering.
-http://localhost:8080/content/graphql-website-demo.html is the entry point,
after starting
+http://localhost:8080/content/articles is the entry point, after starting
this as described below.
-The rendering is based on JSON content that's aggregated server-side using
GraphQL queries
-to provide all the page content, navigation etc. in a single request. Add
`.json` to any
-demo website URL to see that.
+The articles and some navigation pages are rendered using server-side
Handlebars templates,
+which retrieve the aggregated JSON content of the current page by making an
internal request
+to the current path with a `.json` extension.
-This is just an initial prototype. As a next step I'd like to render the
article pages using
-server-side Handlebars templates and implement a few single-page applications
for search
-and browsing. While keeping the articles rendering server-side (so that they
make sense
-for Web search engines for example) and ideally using the same languages
(GraphQL and
-Handlebars) either server- or client-side.
+That aggregated JSON content is retrieved using server-side GraphQL queries so
that a single
+request provides all the page content and navigation.
+
+Those `.json` URLs are also accessible from the outside if client-side
rendering is preferred.
+
+As a next step, to demonstrate "universal querying and rendering" the plan is
to implement
+a small single-page application for content browsing, using client-side
GraphQL queries and
+client-side Handlebars templates.
+
+With this we'll get the best of both worlds: server-side queries and rendering
for the article
+pages (so that they make sense for Web search engines for example) and
client-side queries and
+rendering for the single-page applications that our website needs.
+
+Using GraphQL and Handlebars in both cases, with a small quantity simple Java
code to implement
+the content querying and aggregation code.
## Client-side GraphQL queries
@@ -77,3 +87,28 @@ Then start the demo Sling instance using
-af src/main/resources/features/feature-graphql-example-website.json
And open the above mentioned start page.
+
+## Under the hood
+The following explanations apply to the article and navigation pages. The
(upcoming) single-page apps
+will use different mechanisms.
+
+The scripts and source code mentioned below are foud in the source code and
initial content of this
+demo module.
+
+The GraphQL core retrieves a schema for the current Sling Resource by making a
request with
+the `.GQLschema` extension. You can see the schemas by adding that extension
to article and navigation pages.
+
+The server-side GraphQL queries are defined in `json.gql` scripts for each
resource type.
+
+Based on that script's name, according to the usual Sling conventions it is
used by the Sling GraphQL
+ScriptEngine to execute the query and return a simple JSON document that
provides everything needed
+to render the page in one request. You can see those JSON documents by adding
a `.json` extension to
+article and navigation pages.
+
+This JSON document includes navigation information (the content sections for
now) and processed content
+like the `seeAlso` links which are fleshed out by the `SeeAlsoDataFetcher` as
the raw content doesn't
+provide enough information to build meaningful links. Such `DataFetcher` are
then available for both
+server-side and client-side GraphQL queries.
+
+For this demo, the `.rawjson` extension provides the default Sling JSON
rendering, for comparison or
+troubleshooting purposes.
\ No newline at end of file
diff --git
a/org.apache.sling.graphql.samples.website/src/main/resources/SLING-INF/initial-content/content/graphql-website-demo.html
b/org.apache.sling.graphql.samples.website/src/main/resources/SLING-INF/initial-content/content/graphql-website-demo.html
deleted file mode 100644
index 8aa4c83..0000000
---
a/org.apache.sling.graphql.samples.website/src/main/resources/SLING-INF/initial-content/content/graphql-website-demo.html
+++ /dev/null
@@ -1,92 +0,0 @@
-<!doctype html>
-<!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- ~ Licensed to the Apache Software Foundation (ASF) under one
- ~ or more contributor license agreements. See the NOTICE file
- ~ distributed with this work for additional information
- ~ regarding copyright ownership. The ASF licenses this file
- ~ to you under the Apache License, Version 2.0 (the
- ~ "License"); you may not use this file except in compliance
- ~ with the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing,
- ~ software distributed under the License is distributed on an
- ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~ KIND, either express or implied. See the License for the
- ~ specific language governing permissions and limitations
- ~ under the License.
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
- <!DOCTYPE html>
- <html lang="en">
- <head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <title>Sling GraphQL demo website</title>
- <link rel="stylesheet" href="https://fonts.xz.style/serve/inter.css";>
- <link rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@exampledev/new.css@1.1.2/new.min.css";>
- </head>
- <body>
- <h1>Sling GraphQL demo website</h1>
-
- <div>
- <p>To navigate the content, start at <a
href="/articles">/articles</a>.</p>
- </div>
-
- <h2>Under the hood</h2>
-
- <p>
- Some of the links below require <a
href="/system/sling/form/login">logging in as admin</a> first
- (by default that's <em>admin:admin</em>).
-
- <p>
- Taking <a
href="/content/articles/music/christine-macgyver-on-the-capacitor-of-primary-libero-dolore-aka-rss.html">
- Christine MacGyver on the capacitor of primary 'libero dolore' (aka
RSS)</a>
- as an example:
-
- <ul>
- <li>
- The GraphQL schema is retrieved with an internal Sling request
with the
- <a
href="/content/articles/music/christine-macgyver-on-the-capacitor-of-primary-libero-dolore-aka-rss.GQLschema">GQLschema
extension</a>
- </li>
- <li>
- The server-side GraphQL query is defined <a
href="/apps/samples/article/json.gql">in a json.gql script</a>.
- </li>
- <li>
- Based on that script's name, according to the usual Sling
conventions it is used by the <em>Sling GraphQL ScriptEngine</em> to execute
- the query and returns <a
href="/content/articles/music/christine-macgyver-on-the-capacitor-of-primary-libero-dolore-aka-rss.json">a
simple JSON document</a>
- that provides everything needed to render the page in one request.
- <br/>
- That document includes navigation information (the article
categories) and processed
- content like the "seeAlso" links which are fleshed out to include
the full path and title of the referenced articles, starting, from the
- article filenames present in the article content. This aggregation
happens in the <em>DataFetcher</em> Java classes of the demo bundle.
- <br/>
- </li>
- <li>
- For this demo, the <em>rawjson</em> extension provides
- <a
href="/content/articles/music/christine-macgyver-on-the-capacitor-of-primary-libero-dolore-aka-rss.rawjson">the
raw JSON rendering</a>
- of the default Sling GET servlet, for comparison.
- </li>
- <li>
- The rendering currently happens on the client side using a <a
href="/apps/samples/article/article.html">Handlebars template</a>. The
(tentative)
- plan is to move this server-side for the article renderings, and
implement a tags browsing page using GraphQL queries and client-side Handlebars
- rendering to demonstrate using the same query and rendering
languages either server- or client-side.
- </li>
- </ul>
-
- More useful links:
-
- <ul>
- <li>
- <a href="/content/tags/card+panel.json">Tag queries using a custom
ResourceResolver + server-side GraphQL queries</a>
- - raw JSON <a href="/content/tags/card+panel.rawjson">here</a>.
- <br/>
- Here's <a
href="/content/tags/card+alarm+sensor+firewall+application+panel.json">a query
with few results</a>
- and its <a
href="/content/tags/card+alarm+sensor+firewall+application+panel.rawjson"">raw
JSON</a>.
- </li>
- <li>
- <a href="/graphql.json">GraphQL servlet</a>
- </li>
- </ul>
- </body>
-</html>
