Headless docs/start #3

espen42 · 2020-10-01T17:56:54Z

Chapter 8 (guillotine requests) first draft: basically just https://github.com/enonic/doc-react4xp/blob/headlessDocs/start/docs/guillotine.adoc

… the setup chapter

…t the graphQL playground.

…he react components before the static movie list is done.

…only making it dynamic remains.

…hen clicking the list

poi33 · 2020-10-02T07:34:17Z

Ser ut som en bra start Espen. Har du tenkt å gjøre det mulig å gjøre react helt headless alså en webapp?

… maybe a bit more downboiling.

espen42 · 2020-10-08T18:11:24Z

Ja, skriver på kapittel 9 nå - webapp. Available now at a CR near you!

* commit 'cea53c88d8afe1889a46cadc525b1851cb484ecd': Emphasize that react4xp components don't need to be inserted into react-rendered XP regions, and vice versa. Important NPM install note during the setup.

…proaches

…e second, XP-helper variation, then PR.

poi33

The more i read on this guide i think we should create 2 different ones.
I see that this is only sued for the poor developers thrown into a headless cms and need to learn how our system works. Might ask Thomas about it.
One guide for pure headless.
And one for XP rendering and healess fetching?

Review not completed. about 50% done.

poi33 · 2020-11-03T14:32:30Z

docs/guillotine.adoc

+.site/content-types/movie/movie.xml:
+[source,xml,options="nowrap"]
+----
+<content-type xmlns="urn:enonic:xp:model:1.0">


I do want the decleration of namespace, but i wonder if it might confuse people.
Since it can be tricky to setup in anything that is not intelliJ

Or just getting into the xml model etc. Keep it if you think people will mostly just ignore it and not ask questions.

Good point, fixing.

poi33 · 2020-11-03T14:34:01Z

docs/guillotine.adoc

+        <occurrences minimum="1" maximum="1"/>
+    </input>
+
+    <input name="description" type="HtmlArea">


Exclude all
Inlucde text
TextArea?

What did you mean, it should be a text area (or that it practically is)?

I just thought it'd be neat to both allow bold/italic/underline, which requires a html area (and demonstrates that transferring unescaped data and rendering with dangerouslyInsertHtml works).

It's not really a big deal, of course I can fix it if you think it makes things clearer.

This practically is a text area. I just don't understand why you excluded 90% of the html features. Just allow all no need to restrict on a demo.

Excluding those features enables me to skip the processHtml step in XP...

How about you @sigdestad , do you have an opinion? Between:

using a textarea and keeping it real simple,

like it is now: a simplifiled htmlarea with only bold/italic/underline, so that it processHtml isn't needed and we keep the server side of things simpler... but still have one content point that delivers html tags so that it demonstrates an instance of unescaped rendering (dangerouslyInsertHtml = data-th-utext) still working in a headless context, OR

allowing full html features, so that the entire flow of that is demonstrated in a headless/hybrid context? On the downside: increases the complexity of the lesson a bit, and will require more writing/polish on these docs

Change HTMLarea to TextArea #9

poi33 · 2020-11-03T14:36:18Z

docs/guillotine.adoc

+
+This is a pure entry wrapper that just imports the next react component from _react4xp/shared_.
+
+Why import code from _shared_ instead of keeping it all in the entry? Two reasons:


Remove two reasons. And add a numbered list below. If you think it looks fine now, ignore comment 😄

Hmm, how about this:

Why import code from _shared_ instead of keeping it all in the entry? Firstly, it's a good rule of thumb to keep entries slim, for better optimization. And secondly, in addition to a Content Studio preview for single movies, we're going to use the *imported components* in the actual movie list too, for each single movie in the list.

It's more of a side note actually, bullets and numbered list both made it seem too central. 👍

poi33 · 2020-11-03T14:39:14Z

docs/guillotine.adoc

+
+        <Info heading="Description">
+            <div className="description"
+                 dangerouslySetInnerHTML={{ __html: description }}>


Is this actually a react method dangerouslySetInnerHTML? 👍
If we change it to a textArea we might not scare people that much.
But they will not learn how to insert unformated text with react components.

Yes, it's the standard way - equivalent to thymeleaf's data-th-utext. Strictly speaking it's not a necessary part of this lesson, I just thought it would be interesting to show that this context handles that too. Hmm, scary, I guess it's supposed to be... :D Maybe worth a comment at least?

No need for more comments everything is so defailed allready. We probably want people to learn how to use html area.

@sigdestad , same issue here.

-> #7

Change HTMLarea to TextArea #9

poi33 · 2020-11-03T15:15:31Z

docs/guillotine.adoc

+Two important points when using a controller mapping like this:
+
+[NOTE]
+====


Excellent node 👍 Easy to confuse the two.

poi33 · 2020-11-03T15:17:50Z

docs/guillotine.adoc

+====
+First, the controller reference in a mapping in _site.xml_ must always refer to *the runtime name of the controller*. In our case, the source file of our controller is _/controllers/previewMovie_ *_.es6_*, but at compile time, this is compiled into *_.js_* which is used at XP runtime.
+
+Second, controller mappings use qualified content type names that have *the name of the app* in it: `com.enonic.app.react4xp`. If/when you use a different name for your app, make sure to update content type references like this, e.g. `<match>type:'my.awesome.app:movie'</match>`


This could maybe even be part of the main text? I assume everyone will not use the default name in production?

Hmm, isn't notes supposed to be for emphasis, "above" the main text, like you-should-really-take-special-note-of-this? Or are they more like side notes, feel-free-to-skip-this stuff? Hope I don't have to rewrite too many of them...

Differs from context. Its fine if we keep it like this. The most important is mentioning it.

Okay, I'll just keep it then.

poi33 · 2020-11-03T15:26:14Z

docs/guillotine.adoc

+
+In order to make requests for a list of movies below a container item in the content hierarchy, we'll need a specific guillotine query string, as well as functionality to adapt the resulting data into the proper props structure for the react components.
+
+And by using the same code on the frontend and backend, for this too, we gain a bit of isomorphism (the predictability of a singe source of truth, in short). So we'll make *a module with custom helper functionality* for our use case, and import from it in both places.


singe -> single

What did you mean?

(the predictability of a singe source of truth, in short)

Oh, a typo! Hah, thanks!

Singed source of truth... 🔥

poi33 · 2020-11-03T15:27:58Z

docs/guillotine.adoc

+
+
+// Not using util-lib, to ensure usability on frontend
+const forceArray = maybeArray => Array.isArray(maybeArray)


Double ternary 😕

If you write your own forceArray just use that everywhere. No need to include lib-util then.

Good points.

I'll need to restructure a little bit of code then, and subsequently the docs. Suggestion: we release the docs without this improvement, and create a polish-task for it?

Code improvements in examples #8

poi33 · 2020-11-03T15:32:23Z

docs/guillotine.adoc

+
+NOTE: Again, remember that this query hardcodes qualified names to a content type, that contain the name of the app: `com.enonic.app.react4xp:movie` and `com_enonic_app_react4xp_Movie`. Change these if your app name is not `com.enonic.app.react4xp`.
+
+For more about the query language, see the link:https://developer.enonic.com/docs/headless-cms/2.x/api[guillotine API documentation].


When i read query language i think abotu our implementation of elastic search. NoQl reference.
Maybe just say "For more about the guillotine query see ..."

poi33 · 2020-11-04T08:07:30Z

docs/guillotine.adoc

+
+    const query = buildQueryListMovies();                     <!--3-->
+
+    const variables = {                                       <!--4-->


This is the most meta variable i have seen.
A variable named variables containing varius variables used as variables. 😹
Jokes aside please rename this, maybe params?

Haha, true dat. But the argument for keeping it like this: variables is what guillotine calls it, it expects the params query and variables. So, 1-to-1 (and also, it's sent through POST params, so then you'd get a params param. 😄 )

I'm adding a parenthesis about this name, then

"<4> Build the variables object with the query's parameters (what's up with a variable called variables, you ask? This is for consistencty - the guillotine lib and its docs refer to the encapsulated object of values for the various variables in the query, as an argument called variables. Now we have that clarified),"

poi33 · 2020-11-04T08:11:56Z

docs/guillotine.adoc

+[source,sass,options="nowrap"]
+----
+.movieList {
+  margin: 0 auto; width: 1024px; max-width: 100%;


Could you set each value on a new line?

Uhh, I don't really wanna? :D

In a regular code context I'd agree heavily. But here, the styling just takes heaps of space and creates a sidetrack for the reader's attention span in an already crowded doc...

poi33 · 2020-11-04T08:32:39Z

docs/guillotine.adoc

+</site>
+----
+
+After rebuilding, the API is now up and running at `<site-url>/api/headless` (e.g. `http://localhost:8080/admin/site/preview/default/draft/moviesite/api/headless`).


Question: Why did you choose to expose this as a controller mapping instead of a service?
I'm okay with both.

No great reasons.

I think it was @sigdestad 's suggestion.

I've never used one so I wanted to try. :D

Seemed at the time like it didn't matter much one way or the other. Now I guess I'm a bit locked-in.

poi33 · 2020-11-04T08:34:30Z

docs/guillotine.adoc

+    handleResponseErrorFunc,    <!--4-->
+    extractDataFunc,            <!--5-->
+    handleDataFunc,             <!--6-->
+    catchErrorsFunc             // <!--7-->


Why is 7 commented out? Poor 7.

poi33 · 2020-11-04T08:37:40Z

docs/guillotine.adoc

+
+<1> `url` (string, mandatory): URL to the API endpoint, i.e. to the controller mapping of `headless/guillotineApi.es6`: `<site-url>/api/headless`.
+<2> `query` (string, mandatory): valid link:https://developer.enonic.com/docs/headless-cms/2.x/api[guillotine query] string.
+<3> `variables` (object, optional): object with key-value pairs where the keys correspond to parameters in the `query` string, e.g. the value of `variables.first` will be inserted into the query string as `$first`.


Variables is to generic.
queryVariables will be more confusing, params could work. Values can we pass the query values?

See above: guillotine itself calls it "variables", so this way it corresponds with everything else.

"<3> variables (object, optional): corresponds to the guillotine variables object: key-value pairs where the keys correspond to parameters in the query string. E.g. the value of variables.first will be inserted into the query string as $first."

Headless docs/webapp

espen42 added 16 commits September 29, 2020 21:44

Starting the headless docs: introductory background about guillotine

d15e6c9

Lesson overview

dd1b78f

Reference to next chapter

e621604

Mention the added guillotine API in the project structure overview in…

b9d1516

… the setup chapter

Source file structure, and general thematic layout of chapter 8.

59469e2

Groundwork part of chapter 8 is done

e55f9cd

Started describing guillotineApi, and added a section at the end abou…

9ceb9ed

…t the graphQL playground.

Guillotine helpers described, part controller is done. Only missing t…

71c2a9d

…he react components before the static movie list is done.

React components and movie-list part setup. Static list is finished, …

43ffa25

…only making it dynamic remains.

Details: emphasis and illustrations

f8385f2

Exposing the guillotine API

218cf26

Added the frontend request from MovieList.jsx, and updating the DOM w…

7827344

…hen clicking the list

Chapter 8 first draft done.

913256b

Tweak

c8419bf

Tweak

662fd6e

Tweak

bdfe60c

espen42 requested review from sigdestad and poi33 October 1, 2020 17:57

alansemenov assigned espen42 Oct 6, 2020

Intro to the chapter 9: standalone webapp. Could use a few links, and…

299e925

… maybe a bit more downboiling.

espen42 added 6 commits October 8, 2020 20:16

Merge master into headlessDocs/webapp

67aabf7

* commit 'cea53c88d8afe1889a46cadc525b1851cb484ecd': Emphasize that react4xp components don't need to be inserted into react-rendered XP regions, and vice versa. Important NPM install note during the setup.

Started on the first variation

ce89890

First variation is done.

7911b60

Docs: shortening and diadactifying the intro, and swapping the two ap…

77d3acb

…proaches

First, completely headless variation is done. Rewrite and simplify th…

3831e8a

…e second, XP-helper variation, then PR.

Docs: second part with XP helpers, first draft. PR ready.

9fa18f1

espen42 mentioned this pull request Nov 2, 2020

Headless docs/webapp #6

Merged

poi33 reviewed Nov 3, 2020

View reviewed changes

poi33 reviewed Nov 4, 2020

View reviewed changes

PR fixes and suggestions (#3 and #6)

3a7635b

poi33 approved these changes Nov 6, 2020

View reviewed changes

Merge pull request #6 from enonic/headlessDocs/webapp

d506d71

Headless docs/webapp

espen42 merged commit b47ec6f into master Nov 6, 2020

espen42 deleted the headlessDocs/start branch November 6, 2020 12:09


		This is a pure entry wrapper that just imports the next react component from _react4xp/shared_.

		Why import code from _shared_ instead of keeping it all in the entry? Two reasons:


		In order to make requests for a list of movies below a container item in the content hierarchy, we'll need a specific guillotine query string, as well as functionality to adapt the resulting data into the proper props structure for the react components.

		And by using the same code on the frontend and backend, for this too, we gain a bit of isomorphism (the predictability of a singe source of truth, in short). So we'll make a module with custom helper functionality for our use case, and import from it in both places.



		// Not using util-lib, to ensure usability on frontend
		const forceArray = maybeArray => Array.isArray(maybeArray)


		const query = buildQueryListMovies(); <!--3-->

		const variables = { <!--4-->

Headless docs/start #3

Headless docs/start #3

Conversation

espen42 commented Oct 1, 2020 • edited Loading

poi33 commented Oct 2, 2020 • edited Loading

espen42 commented Oct 8, 2020 • edited Loading

poi33 left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 6, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 3, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 6, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 3, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 4, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 4, 2020 • edited Loading

Choose a reason for hiding this comment

espen42 Nov 4, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 4, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 4, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espen42 Nov 4, 2020 • edited Loading

Choose a reason for hiding this comment

espen42 commented Oct 1, 2020 •

edited

Loading

poi33 commented Oct 2, 2020 •

edited

Loading

espen42 commented Oct 8, 2020 •

edited

Loading

poi33 left a comment •

edited

Loading

espen42 Nov 6, 2020 •

edited

Loading

espen42 Nov 3, 2020 •

edited

Loading

espen42 Nov 6, 2020 •

edited

Loading

espen42 Nov 3, 2020 •

edited

Loading

espen42 Nov 4, 2020 •

edited

Loading

espen42 Nov 4, 2020 •

edited

Loading

espen42 Nov 4, 2020 •

edited

Loading

espen42 Nov 4, 2020 •

edited

Loading

espen42 Nov 4, 2020 •

edited

Loading

espen42 Nov 4, 2020 •

edited

Loading