Merge pull request #6 from ec-europa/FRONT-4047-Documentation

feat(ssg): Docs - FRONT-4047

README.md

@@ -4,36 +4,68 @@
   </a>
 </p>
 <h1 align="center">
-  Gatsby Minimal TypeScript Starter
+  ECL ssg starter based on gatsby typescript starter kit
 </h1>
 
 ## 🚀 Quick start
 
-1.  **Create a Gatsby site.**
+1.  **Clone this repo**
 
-    Use the Gatsby CLI to create a new site, specifying the minimal TypeScript starter.
+    Clone the repository in your user space in github if you plan to start developing a website using ECL ssg.
 
     ```shell
-    # create a new Gatsby site using the minimal TypeScript starter
-    npm init gatsby -- -ts
+    # fetch the repository
+    git clone [email protected]:ec-europa/ecl-ssg.git
     ```
 
 2.  **Start developing.**
 
     Navigate into your new site’s directory and start it up.
 
     ```shell
-    cd my-gatsby-site/
-    npm run develop
+    cd my-ecl-ssg-site/
+    yarn start
     ```
 
-3.  **Open the code and start customizing!**
+3.  **Access the website**
 
     Your site is now running at http://localhost:8000!
 
-    Edit `src/pages/index.tsx` to see your site update in real-time!
+4. **Access the content in the cms**
 
-4.  **Learn more**
+    ```shell
+    yarn netlify-cms-proxy-server
+    cd static/admin/
+    sed -i '/^#/d' config.yml
+    ```
+
+    The cms is now accessible at http://localhost:8000/admin!
+    Since you configured the cms with a local backend you will have immediate access without providing any credential.
+
+5. **What you will find**
+
+    Not much, this starter comes with an homepage in english, in terms of content.
+    This page will show a site header, a footer, a menu, but these are the defaults set by the tool, which are using the EC theme as long as you haven't changed the `customTheme` property in the `gatsby-config.js` file.
+    You can override these default content using the cms, your content will be used instead of the "mocked" site header and footer.
+    This is also true for the menu, which is by default automatically built browsing the existing pages, but this is only to provide you with some default, the menu is not particularly smart so you are invited to create your own menu and adapt it everytime you add or remove a content.
+
+6. **Using the playground environments**
+
+    Two special environments are available to you to try out this tool without cloning the repo and making the needed steps to connect your instance with a CI environment to get the website deployed somewhere.
+    These are accessible at:
+    - https://ec-playground--ecl-ssg.netlify.app/
+    - https://eu-playground--ecl-ssg.netlify.app/
+
+    Request access to these environments in order to be able to see their backend and start using the cms and the editor.
+    If you already have access, the playgrounds are configured in order to generate preview urls for the content you create.
+    You are invited to create content and save it but not to publish it, unless you're content is meant to improve the minimal
+    setup of this starter.
+    When you save a content a pull request will be generated, if you publish that would be merged in one of the two branches attached to the playground environments, in order not to pollute those, publishing is dicouraged, and if you do it we might then remove the content added if we find it inappropriate.
+
+7. **Learn more about ECL ssg**
+    - [Documentation](./docs/README.md)
+
+8.  **Learn more about gatsby**
 
     - [Documentation](https://www.gatsbyjs.com/docs/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter-ts)
     - [Tutorials](https://www.gatsbyjs.com/docs/tutorial/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter-ts)
@@ -42,8 +74,4 @@
     - [Plugin Library](https://www.gatsbyjs.com/plugins?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter-ts)
     - [Cheat Sheet](https://www.gatsbyjs.com/docs/cheat-sheet/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter-ts)
 
-## 🚀 Quick start (Netlify)
-
-Deploy this starter with one click on [Netlify](https://app.netlify.com/signup):
 
-[<img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify" />](https://app.netlify.com/start/deploy?repository=https://github.com/gatsbyjs/gatsby-starter-minimal-ts)

docs/README.md

@@ -0,0 +1,39 @@
+# ECL ssg documentation
+
+ECL ssg is a static site generator based on [gatsby](https://www.gatsbyjs.com/) that integrates [ECL webcomponents](https://github.com/ec-europa/ecl-webcomponents) and an admin interface where a rich text area using the [ECL webcomponents ckeditor plugin](https://ecl-webcomponents.netlify.app/playground/) is provided.
+
+It comes with a basic configuration providing a page template which includes all the components that will provide a default output in the two systems EC and EU with mocked data, this can be then replaced by content generated through the admin interface, using the rich text area with the ecl-webcomponents enabled.
+
+It assumes the website is multilingual, but currently defines only english as an available language, this can be changed in the `gatsby-config.js` by adding languages in the i18n plugin section.
+
+ ```text
+ {
+  resolve: 'gatsby-plugin-i18n',  
+  options: {  
+    createPages: false,    
+    langKeyDefault: 'en',  
+    useLangKeyLayout: false,  
+    localizedPaths: { 
+      'en': '/en/',  
+    },  
+    languageLabels: {  
+      'en': 'English',  
+    },  
+  }  
+ }
+ ```
+
+Internazionalition is supported through the admin interface, when other languages are enabled it is possible to select the language but also a primitive string translation logic is in place.
+Most of the current templates are supporting this using `t()`, but the locales files currently hosted are not necessarily relevant and there is no advanced logic in the tool to generate prettier locales based on the current strings used in the website.
+
+It comes with an automatic language switcher, a default menu (..pretty dumb), a basic breadcrumb, a very basic search (unthemed) example,
+
+## Playgrounds
+
+If you are looking for info on how to use the playgrounds there are two environments https://ec-playground--ecl-ssg.netlify.app/ and https://eu-playground--ecl-ssg.netlify.app, these are connected with netlify cms instances that can be used to test the creation of pages and the usage of the ckeditor plugin, their access is restricted, if you believe you are entitled to get an account on them, feel free to submit a request about it. 
+
+- [ECl ssg](./ecl-ssg.md): The tool presentation
+- [Playgrounds](./playgrounds.md): This is for you that want to start using the playgrounds.
+- [Ecl webcomponents](./webcomponents.md): What are them, where to find documentation.
+- [Netlify Cms](./netlify-cms.md): Some info about the backend.
+- [Ckeditor](./editor.md): The magic, and the misery of..

docs/ecl-ssg.md

@@ -0,0 +1,32 @@
+# ECL Ssg
+
+ECL ssg is a static site generator based on gatsby that uses ECL webcomponents to build pages and layouts using the EC or the EU theme. 
+The tool is pretty basic, being based on gatsby we won't cover here what the [gatsby documentation](https://www.gatsbyjs.com/docs/) already provides, this document is more meant to explain the purpose of ECL ssg, its limitations together with its effectiveness.
+[ECL](https://ec.europa.eu/component-library/) is the library defining the UI elements of the [EC (Europen Commission)](https://ec.europa.eu/component-library/ec/) and the [EU (Europena Union)](https://ec.europa.eu/component-library/eu/) visual identities, it's markkup is consequently pretty reach and complex to be reproduced.
+This makes the usage of ECL, outside of its official implementation in twig, a complex matter in relation to the markup definition.
+ECL webcomponents can simplify this, its markup is way much simpler than the one defined by the vanilla component but still it is far from being something a generic user, not aware of the html language and not familiar with custom elements, would easily insert by hand.
+
+## How is is this tool supposed to help?
+
+We've tried to imagine what would have been the easiest way to create layouts using ECL components, and what we imagined was a rich text area with the capability of rendering our webcomponents, offering a simplified interface where to insert values for predefined attributes, which are the main way of passing data to the webcomponent.
+Furthermore, once we had the chance to generate the "content" of a web page was not difficult to think about an environment where everything could be put together, the ECL webcomponents, the ckeditor plugin, into a simple tool that would create full web-pages in a such a "simple" way.
+
+## Is this really that simple?
+
+No, something complex can hardly be reduced to a simple task, but to a certain extent, depending on the needs, it can really be pretty straighforward:
+In the editor might be complex sometimes to understand what is happening, many times you would find yourself in troubles when inserting complex components that include others, it can be challenging.
+Indeed this approach of creating pages through the cms is only one of the approaches possible and when working on a real project you might prefer editing some file manually to get the achieved result.
+
+## Do i have to use this approach with the netlify cms to create any page?
+
+Absolutely not, this is only a basic gatsby application that currently generates pages based on the available md files created by the cms, but you can take it over entirely, fork this repo and make any change you might want, in the end this is gatsby and it's up to you to create the needed configuration for your project, here we are just creating a basic configuration that might serve only demoing purposes.
+Think about the editor as an opportunity, if that is not what it is for you, don't use it, change the configuration and generate pages the way you want.
+
+## Can i use this tool to render content from a drupal website?
+
+Yes you can, gatsby can easily connect with a drupal database and fetch content from it through a graphQL query, if enabled also in Drupal.
+It's a matter of configuring the app in order to do so, an example is available in the [demo website of ECL ssg](https://ecl-ssg.netlify.app/en/drupal/), the content in the linked page is fetched from a mysql database using the drupal graphQl and shown as cards in the website.
+
+## What others data source can i use for my project?
+
+Gatsby has many plugins that can be explored to identify many different possible integrations or definitions of data sources for your project, in the demo website a few of these options are used to build a few simple pages. You can see the source code related to this demo website in this [branch](https://github.com/ec-europa/ecl-ssg/tree/chore-demo-website) on github.

docs/editor.md

@@ -0,0 +1,78 @@
+# Editor
+
+This whole project started from the idea of having the possibility of using a rich text editor to simplify the creation of content using ECL webcomponents.
+When this started to be available, in the form a [ckeditor plugin we developed](https://ecl-webcomponents.netlify.app/playground), it seemed natural to create a simple static site generator which would use it to generate pages through an admin interface.
+
+This was identified in [netlify cms](https://v1.netlifycms.org/) and the editor was integrated into it, so it can be used at `./admin` to generate pages (and other content).
+
+## How do i access the admin interface?
+
+At `localhost:8000/admin`
+To access the admin interface locally remind to change the commented line at ./static/admin/config.yml, from `#local_backend: true` to `local_backend: true`.
+
+Mind the fact that if this doesn't have to pushed ever, locally it has to be switched back whenever committing.
+Furthermore run `yarn netlify-cms-proxy-server` and then access the admin interface at: `localhost:8000/admin`.
+
+## How does it work?
+
+It's a ckeditor plugin, we add one main ECL button in the textarea of a classic edition of ckeditor 5.
+Clicking on this button reveals a big (...too big) dropdown, it contains buttons for each of the available components. Some of them, when they are children, will be nested into their parent button and identified by a label usually containing "items".
+
+Clicking on the icon will open the form for generating the requested webcomponent markup. There are fields where to insert your custom data, technically this will generate html attributes, so only plain text can be inserted.
+
+At the moment most of the components come with predefined data, because the editor was mainly used for demoing purposes, this also helps in getting a consistent layout when simply clicking on the save button without editing the form, but it's clear that most of the times, if the intention is to insert user data this implies deleting the existing values and typing them again.
+
+When the configuration is done, clicking on the "save" button will insert the component in the editor and it will also be visible in the preview area on the right, if enabled.
+
+## Why do i see all the standard buttons in a ckeditor instance, aren't most of them duplicated in the webcomponents?
+
+Oh yes, the plugin is built using the same buttons as the classic textarea, probably not the best idea, we should complain about this! It will probably make sense to remove most if not all the standard ckeditor buttons, mind the fact that elements created this way will not have any particular styling from ECL, there is no general css from ECL loaded in this project, styles are directly coming from the webcomponents.
+
+## What is this Ui that i see in the editor textarea?
+
+The editor doesn't render the webcomponents in a browser, so we style the components you create in order to make them identifiable, it would be otherwise very tricky to move around the complex structures you might create.
+
+The background colors and the label are tryingto help you identify the different elements you created.and to know where what you might be typing is going to be placed, look at your cursor, when you type on a button to create an ECL component this will give you confidence about where your content will be placed.
+
+## How do i move in the textarea?
+
+As said the editor has a complex task, a few gesture are handled to make the markup traversable in the textarea.
+
+ - The **Enter** command moves you out of the current component, so it has to be used only when the component is finished, or a child component is created to start inserting the next one, when needed. 
+ If you are in a child component pressign `Enter` will move you to the next available position in the parent component, pressing it again would move you to the next position available after the parent.
+
+ - **Shift+enter** can be used to insert line breaks. This is the way to manage the insertion of block of text where you want to have line breaks, clicking enter would, as said before, move you out of the component you are editing, instead.
+
+ - **arrowUp** can be used to traverse back the ECL webcomponents markup in the textarea, also the mouse can normally be used, but using `arrowUp` is more reliable.
+
+ ### How do i delete content that i created wrongly?
+
+Mmh..try `backspace`, but it might not work always as expected, handling the markup in the editor is complex, sometimes you might want to enable the "source code" view mode in ckeditor and adjust the markup manually, it is sub-optimal but it also gives a way to handle potentially blocking situations.
+
+### How do i edit a component that i've inserted before?
+
+For most components it will be possible to edit an instance created by going into its area and clicking the related button in the toolbar, the form will load the current values and you can further edit the component. This is not possible in components that can include other instances of the same component (like grid).
+
+### How do i insert a nested component inside the parent?
+
+It's easy, once inserted the parent click on the child button in the toolbar, when you will save that, you will be in the item's area in the editor, you should also see that visually thanks to a label that appears, if content is expected in the child, start typing and when you've done click `Enter`, this will complete the insertion of the first child component, if then you want to include some other click on the relative button in the toolbar and you can go on like this until you've created all the needed markup.
+
+## How do i know what is expected as content of the component i created?
+
+Many of the ecl webcomponents expect content, indeed, to know how complex components are built, which component to include to get what, you can refer to https://ecl-webcomponents.netlify.app, there you'll find what you need, and to a certain extent, you could also use that markup and copy paste it in the editor.
+
+## Where do i complain about the hundred bugs i've already found?
+
+The plugin is far from being perfect, per se it has a huge task which is potentially handling a full page content markup, it has been challenging to reach the current status, where you can build potentially do it, but the editor is pretty rough, the ECL dropdown is giant and you need to adapt the window in the cms in order to be able to see it all, some components might not have been ever tested, there could be misalignments with the current version of the ecl-webcomponents and many situations where you might find yourself blocked, or simply not able to fully reproduce what you had in mind.
+We know the limitations of this editor and the criticalities about it, but being such a powerful tool, it feels worth making it available despite them.
+
+There is no plan to offer continuos support about the editor, and no plan about keep developing on it, but it all depends on how much this tool will be used and how many requests about it we could receive.
+If this remains a playground to try out ecl-webcomponents, maybe there will not be any further development, just an alignment of the components to the version of the webcomponents used.
+
+## Where do i find the documentation about the cms?
+
+Our brief document is available [here](./cms.md)
+
+## Which version of ckeditor uses?
+
+It is based on CkEditor 36.0.1 and it's not planned to upgraded it to newer versions of ckeditor because it would involve a deep rewriting of the plugin.