rnixx · February 10, 2023 10:32 · Feb 10, 2023 · Feb 10, 2023 · Feb 10, 2023 · Feb 10, 2023
diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -128,7 +128,7 @@ Adding custom styles
 
 Create ``theme/extras/custom.overrides`` and restart frontend.
 
-These file contains custom LESS code.
+This file contains custom LESS code.
 
 
 Replace the logo

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -81,7 +81,7 @@ Open a dedicated terminal and run the backend server::
     make zope-start
 
 Connect to your zope instance to ``localhost:8080`` and
-create plone Site path ``Plone``.
+create a plone Site under path ``Plone``.
 
 Start frontend node server in a dedicated terminal::
 

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -31,8 +31,8 @@ Use ``yo`` to call the volto generator. It generates the directory structure for
 
 While ``yo`` runs, you get asked some questions. Answer them as follows:
 
-    - Project name (e.g. my-volto-project) frontend
-    - Would you like to add addons? false
+- Project name (e.g. my-volto-project) frontend
+- Would you like to add addons? false
 
 Install backend server. The backend server provides the actual database and REST endpoints used by Volto. The following steps create a Python virtual environment, generate a Makefile and install and start Zope/Plone::
 
@@ -59,25 +59,31 @@ Install backend server. The backend server provides the actual database and REST
 
 Hit enter until done to accept all defaults.
 
-Create ``requirements.txt``::
+Create ``requirements.txt``. It contains the Python packages to be installed. ``Plone`` is a policy package handling all the requirements needed to run the backend server::
 
     echo "Plone" > requirements.txt
 
-Create an ``instance.yaml`` containing::
+Create an ``instance.yaml``. It contains required configuration for running the Zope server. Once ``mxmake`` handles the initial creation of this file properly, this stept is not necessary any more.
+
+The minimal information to be conained in ``instance.yaml``::
 
     default_context:
         initial_user_name: 'admin'
         initial_user_password: 'admin'
         db_storage: direct
 
-Run make::
+Run make to install the backend server::
+
+    make install
+
+Open a dedicated terminal and run the backend server::
 
     make zope-start
 
 Connect to your zope instance to ``localhost:8080`` and
 create plone Site path ``Plone``.
 
-Start frontend node server::
+Start frontend node server in a dedicated terminal::
 
     cd frontend
     yarn install

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -42,7 +42,7 @@ Install backend server. The backend server provides the actual database and REST
     ./venv/bin/pip install https://github.com/mxstack/mxmake/archive/develop.zip
     ./venv/bin/mxmake init
 
-Choose::
+``mxmake init`` fires an interactive terminal session. Once asked, choose::
 
     [?] Include topics: 
         [X] applications
@@ -57,7 +57,7 @@ Choose::
         [X] core.packages
         [ ] core.sources
 
-Hit enter for all defaults.
+Hit enter until done to accept all defaults.
 
 Create ``requirements.txt``::
 

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -34,7 +34,7 @@ While ``yo`` runs, you get asked some questions. Answer them as follows:
     - Project name (e.g. my-volto-project) frontend
     - Would you like to add addons? false
 
-Install backend server. The backend server provides the actual database and REST endpoints used by Volto::
+Install backend server. The backend server provides the actual database and REST endpoints used by Volto. The following steps create a Python virtual environment, generate a Makefile and install and start Zope/Plone::
 
     mkdir backend
     cd backend

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -21,7 +21,7 @@ Install npm packages required to bootstrap a Volto project. The installation of
         yo \
         @plone/generator-volto
 
-Since we installed NPM packages locally, we want to extend the ``PATH`` for convenient access to the provided commands::
+Since we installed NPM packages locally, we want to extend the ``PATH`` for convenient access to the installed terminal commands::
 
     export PATH=$PATH:$(pwd)/node_modules/.bin
 
@@ -34,7 +34,7 @@ While ``yo`` runs, you get asked some questions. Answer them as follows:
     - Project name (e.g. my-volto-project) frontend
     - Would you like to add addons? false
 
-Install backend server::
+Install backend server. The backend server provides the actual database and REST endpoints used by Volto::
 
     mkdir backend
     cd backend

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -9,7 +9,7 @@ Install Node version manager (nvm). Volto frontend requires a Node.js server for
 
     wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
 
-Install and use Node.js in the required version. At the time of writing this document, this is 16.x:
+Install and use Node.js in the required version. At the time of writing this document, this is 16.x::
 
     nvm install 16
     nvm use 16

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -3,8 +3,6 @@ How to bootstrap a volto project
 
 Install Node package manager (npm). It is the tool required to install JavaScript packages and libraries::
 
-.. code-block:: sh
-
     sudo apt install npm
 
 Install Node version manager (nvm). Volto frontend requires a Node.js server for resource delivery and server side rendering. Node version manager is a tool which helps running the version of Node.js required by Volto::
@@ -16,23 +14,22 @@ Install and use Node.js in the required version. At the time of writing this doc
     nvm install 16
     nvm use 16
 
-Install npm packages, either globally or local::
+Install npm packages required to bootstrap a Volto project. The installation of the JavaScript packages is done locally, not system wide. This way we avoid potential conflicts if other projects require e.g. a differing set of installed package versions to run.::
 
     npm install --prefix . \
         yarn \
         yo \
         @plone/generator-volto
 
-If installed local, add local node_modules/.bin directory
-to PATH::
+Since we installed NPM packages locally, we want to extend the ``PATH`` for convenient access to the provided commands::
 
     export PATH=$PATH:$(pwd)/node_modules/.bin
 
-Use ``yo`` to call the volto generator::
+Use ``yo`` to call the volto generator. It generates the directory structure for our Volto frontend::
 
     yo @plone/volto
 
-Answer questions:
+While ``yo`` runs, you get asked some questions. Answer them as follows:
 
     - Project name (e.g. my-volto-project) frontend
     - Would you like to add addons? false

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -3,7 +3,7 @@ How to bootstrap a volto project
 
 Install Node package manager (npm). It is the tool required to install JavaScript packages and libraries::
 
-.. code-block:: shell
+.. code-block:: sh
 
     sudo apt install npm
 

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -1,19 +1,23 @@
 How to bootstrap a volto project
 ================================
 
-Install npm::
+Install Node package manager (npm). It is the tool required to install JavaScript packages and libraries::
+
+.. code-block:: shell
 
     sudo apt install npm
 
-Install nvm::
+Install Node version manager (nvm). Volto frontend requires a Node.js server for resource delivery and server side rendering. Node version manager is a tool which helps running the version of Node.js required by Volto::
 
     wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
 
-Install npm packages, either globally or local::
+Install and use Node.js in the required version. At the time of writing this document, this is 16.x:
 
     nvm install 16
     nvm use 16
 
+Install npm packages, either globally or local::
+
     npm install --prefix . \
         yarn \
         yo \

diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -81,3 +81,65 @@ Start frontend node server::
     cd frontend
     yarn install
     yarn start
+
+
+Start Developing
+================
+
+Structure (Points of interest):
+
+- frontend
+    - omlette (-> node_modules/@plone/volto)
+        - Handy link to see how things are done.
+    - src (Containing our react/JS development code)
+    - theme (Includes all CSS, LESS, fonts, etc...)
+        - globals (Not exists initially, contains variables)
+    - public (Static serverd folder, contains robots.txt, favicon)
+
+Examples of theme customization
+-------------------------------
+
+Changing variables
+~~~~~~~~~~~~~~~~~~
+
+Create ``theme/globals/site.variables`` (it is a LESS file) contaning::
+
+     @fontName: 'FreeMono'
+
+.. note::
+
+    Every time you create a file in the themes folder, the frontend server
+    must be restarted.
+
+.. note::
+
+    To get an overview which variables are to be overwritten, take a look
+    at ``omelette/theme/themes/default/globals/site.variables``.
+
+Adding custom styles
+~~~~~~~~~~~~~~~~~~~~
+
+Create ``theme/extras/custom.overrides`` and restart frontend.
+
+These file contains custom LESS code.
+
+
+Replace the logo
+~~~~~~~~~~~~~~~~
+
+In volto, we are able to override virtually every file within ``src`` with a
+custom version. This is called component shadowing.
+
+Files to shadow are best located via the ``omelette`` convenience location.
+
+The logo file we need to override is located at
+``src/components/theme/Logo/Logo.svg``.
+
+Our component shadowing root is ``src/customizations`` where the target
+structure gers replicated with the files we want to override. This works for
+all files types.
+
+So, to finally customize the logo, we create
+``src/customizations/components/theme/Logo/Logo.svg`` with the custom logo
+image we want to use.
+
diff --git a/volto-sandbox.rst b/volto-sandbox.rst
@@ -19,12 +19,12 @@ Install npm packages, either globally or local::
         yo \
         @plone/generator-volto
 
-If installes local, add bin local node modile bin directory
+If installed local, add local node_modules/.bin directory
 to PATH::
 
     export PATH=$PATH:$(pwd)/node_modules/.bin
 
-Use yo to call the volto generator::
+Use ``yo`` to call the volto generator::
 
     yo @plone/volto
 

diff --git a/volto-sandbox → volto-sandbox.rst b/volto-sandbox → volto-sandbox.rst
diff --git a/volto-sandbox b/volto-sandbox
@@ -0,0 +1,83 @@
+How to bootstrap a volto project
+================================
+
+Install npm::
+
+    sudo apt install npm
+
+Install nvm::
+
+    wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
+
+Install npm packages, either globally or local::
+
+    nvm install 16
+    nvm use 16
+
+    npm install --prefix . \
+        yarn \
+        yo \
+        @plone/generator-volto
+
+If installes local, add bin local node modile bin directory
+to PATH::
+
+    export PATH=$PATH:$(pwd)/node_modules/.bin
+
+Use yo to call the volto generator::
+
+    yo @plone/volto
+
+Answer questions:
+
+    - Project name (e.g. my-volto-project) frontend
+    - Would you like to add addons? false
+
+Install backend server::
+
+    mkdir backend
+    cd backend
+    python3 -m venv venv
+    ./venv/bin/pip install https://github.com/mxstack/mxmake/archive/develop.zip
+    ./venv/bin/mxmake init
+
+Choose::
+
+    [?] Include topics: 
+        [X] applications
+        [X] core
+    [?] Include domains from topic "applications": 
+        [X] applications.cookiecutter
+        [X] applications.zope
+    [?] Include domains from topic "core": 
+        [X] core.base
+        [X] core.mxenv
+        [X] core.mxfiles
+        [X] core.packages
+        [ ] core.sources
+
+Hit enter for all defaults.
+
+Create ``requirements.txt``::
+
+    echo "Plone" > requirements.txt
+
+Create an ``instance.yaml`` containing::
+
+    default_context:
+        initial_user_name: 'admin'
+        initial_user_password: 'admin'
+        db_storage: direct
+
+Run make::
+
+    make zope-start
+
+Connect to your zope instance to ``localhost:8080`` and
+create plone Site path ``Plone``.
+
+Start frontend node server::
+
+    cd frontend
+    yarn install
+    yarn start
No results found