Sweeping documentation updates (#548) (#637)

* Continuing work from #548.
* Update tutorial.
* Update installation docs.
* Move blocks docs up a level.

---------

Co-authored-by: Zachary Svoboda <93960196+Zsvoboda87@users.noreply.github.com>

docs/advanced/advanced01.rst

@@ -1,5 +1,7 @@
-Customizing HTML/CSS in Templates
-==================================
+.. _customizing_templates:
+
+Customizing Templates & CSS
+===========================
 
 Overview
 ---------
@@ -19,8 +21,7 @@ pulling in Wagtail tags to make your template work the way it should.
     at the top of your template. You do, however, need to make sure to use the appropriate template
     tags at the top of the template or your template will not render.
 
-The templates directory inside your ``website`` app is empty by default. Any templates you put
-in here will override the default coderedcms templates if they follow the same name and directory
+The templates directory inside your ``website`` app will override the default coderedcms templates if they follow the same name and directory
 structure. This uses the standard Django template rendering engine. For example, to change the
 formatting of the article page, copy ``coderedcms/templates/coderedcms/pages/article_page.html``
 to ``website/templates/coderedcms/pages/article_page.html`` and modify it.
@@ -38,12 +39,13 @@ by visiting the Wagtail CRX source code here: `navbar.html <https://github.com/c
 Let’s say that you want to have a 2-tiered navbar with the logo on the top tier and the menu items on the
 second tier. The default navbar does not have that as an option, so you will want to override this template.
 
-Look at your folder structure for your project. In the ``website`` folder, you should see another folder
-called ``templates``. In there are two folders as well: ``website`` and ``coderedcms``. The ``coderedcms`` template
-folder is likely empty at this point because the CMS is pulling in the default templates from source, but you can
-add templates to the ``coderedcms`` folder **if you are overriding the default templates**.
+Look at your folder structure for your project. By default, your project starts with a "website" folder (also known as a directory).
+In that directory there will be this path to base.html `templates/coderedcms/pages/base.html.`.  This file is here for your convenience,
+you can add imports (like a google font) and it will override the default ``coderedcms`` base.html template.  In the `website/templates/coderedcms` folder
+you are able override other ``coderedcms`` templates.  To do this, the file structure and name must match the default templates.
+The `source code for built-in templates can be found on GitHub <https://github.com/coderedcorp/coderedcms/blob/main/coderedcms/templates/coderedcms/>`_.
 
-Most of your custom templates will go into your ``website`` folder because they are not overriding the
+Many of your custom templates will go into your ``website`` folder because they are not overriding the
 default templates in the CMS but either extending them or creating completely new ones specific to
 your site.
 
@@ -56,283 +58,111 @@ You can add a new ``website`` folder in ``templates`` (because we will use it in
 but for now, you will want to add a ``snippets`` folder inside the ``templates\coderedcms`` folder
 so that your folder structure looks something like this:
 
-.. figure:: img/advanced_folder_structure1.png
+.. figure:: img/A01/advanced_folder_structure1.png
     :alt: Our folder structure for templates.
 
     Our folder structure for templates within our website app.
 
 The folder structure needs to be the same as the default folder structure in the CMS if you want to
 override the navbar template. Now you should have ``templates\coderedcms\snippets``. Navigate to
-the ``snippets`` folder and create a ``navbar.html`` file inside of that folder.
+the ``snippets`` folder and create a ``navbar.html`` file inside of that folder.  With your server running and the newly created file navbar.html file in place,
+look at your website.  The navbar should be gone.  The empty file is now overriding the default template.
 
 **You are now ready to begin customizing the navbar template!**
 
-1. Examine the default template for the navbar. What code will we want to use from it? You can use
-   what’s there in your customization.
-
-2. We will need the Wagtail tags at the top, so copy those and paste them into
-   your ``navbar.html`` file.
-
-.. code-block:: Django
-
-    {% load wagtailcore_tags wagtailsettings_tags wagtailimages_tags coderedcms_tags i18n %}
-
-3. Next, we need to figure out how to move the logo (aka the ``navbar-brand``) into its own section for
-   the navbar. Maybe we could essentially create two navbars, one that just has the logo and one that has
-   the menu. Hmm, let’s try that!
-
-4. We want to preserve the basic functionality of the navbar, so we should keep the tags for CMS settings
-   and the overall layout inside of a container.
-
-5. The 2-tiered navbar will have two navbars on top of each other but one will only have the
-   ``navbar-brand`` (logo) while the other will allow for adding menu items via the CMS. So, the top
-   navbar is not going to have access to CSS settings in the CMS that are reserved for the main navbar –-
-   which means that you will need to add any custom classes to the top navbar, such as the background
-   color or where you want the logo to be placed. Keep that in mind.
-
-   .. code-block:: Django
-
-      {% load wagtailcore_tags wagtailsettings_tags wagtailimages_tags coderedcms_tags i18n %}
-
-
-      {% if not settings.coderedcms.LayoutSettings.navbar_wrapper_fluid %}
-      <div class="container">
-      {% endif %}
-      <nav class="navbar navbar-header bg-warning">
-
-      {% if not settings.coderedcms.LayoutSettings.navbar_content_fluid %}
-      <div class="container">
-      {% endif %}
-         <div>
-         <a class="navbar-brand" href="/">
-               {% if settings.coderedcms.LayoutSettings.logo %}
-               {% image settings.coderedcms.LayoutSettings.logo original as logo %}
-               <img class="img-fluid" src="{{logo.url}}" alt="{{site.site_name}}" />
-               {% else %}
-               {{site.site_name}}
-               {% endif %}
-         </a>
-         </div>
-      {% if not settings.coderedcms.LayoutSettings.navbar_content_fluid %}
-      </div><!-- /.container -->
-      {% endif %}
-
-      </nav>
-
-   We have set the foundation for the top navbar, which will be the banner section for the logo. Instead of
-   ``<nav class="navbar {% get_navbar_css %}">``, we have added our own Bootstrap classes since this part of the
-   navbar will not be getting its CSS settings from the CMS.
-
-   However, we did keep the ``{% if settings.coderedcms.LayoutSettings.logo %} {% endif %}`` block because we want
-   to show the name of the site **if no logo is uploaded in the CMS**.
-
-6. Now we can include the code block for the normal navbar beneath it. Place this code below the ``</nav>`` in
-   your template. We want to preserve majority of the navbar as-is (without the block for ``navbar-brand``) so that
-   when we add menu items in the CMS, those items will show up as navigation links.
-
-   .. code-block:: Django
-
-      <!--Put this below the previous nav closing tag -->
-
-      <nav class="navbar {% get_navbar_css %}">
-
-      {% if not settings.coderedcms.LayoutSettings.navbar_content_fluid %}
-      <div class="container">
-      {% endif %}
-         <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
-               <span class="navbar-toggler-icon"></span>
-         </button>
-
-         <div class="collapse navbar-collapse" id="navbar">
-         {% get_navbars as navbars %}
-         {% for navbar in navbars %}
-         <ul class="navbar-nav {{navbar.custom_css_class}}"
-               {% if navbar.custom_id %}id="{{navbar.custom_id}}"{% endif %} >
-               {% for item in navbar.menu_items %}
-                  {% include_block item with liclass="nav-item" aclass="nav-link" ga_event_category="Navbar" %}
-               {% endfor %}
-         </ul>
-         {% endfor %}
-         {% if settings.coderedcms.LayoutSettings.navbar_search %}
-         <form class="ml-auto form-inline" action="{% url 'crx_search' %}" method="GET">
-               {% load django_bootstrap5 %}
-               {% get_searchform request as form %}
-               {% bootstrap_form form layout='inline' %}
-               <div class="form-group">
-                  <button class="btn btn-outline-primary ml-2" type="submit">{% trans 'Search' %}</button>
-               </div>
-         </form>
-         {% endif %}
-
-         </div>
-
-      {% if not settings.coderedcms.LayoutSettings.navbar_content_fluid %}
-      </div><!-- /.container -->
-      {% endif %}
-
-      </nav>
-
-      {% if not settings.coderedcms.LayoutSettings.navbar_wrapper_fluid %}
-      </div><!-- /.container -->
-      {% endif %}
-
-      {# Navbar offset #}
-      {% if settings.coderedcms.LayoutSettings.navbar_fixed %}
-         {% if settings.coderedcms.LayoutSettings.logo %}
-         <div class="{{settings.coderedcms.LayoutSettings.navbar_format}}-fixed-img-offset {{settings.coderedcms.LayoutSettings.navbar_collapse_mode}}"></div>
-         {% else %}
-         <div class="{{settings.coderedcms.LayoutSettings.navbar_format}}-fixed-offset {{settings.coderedcms.LayoutSettings.navbar_collapse_mode}}"></div>
-         {% endif %}
-      {% endif %}
-
-   Let's talk about what is happening here. So, we pulled in the code for the navbar a second time, with the removal of
-   ``navbar-brand`` section from the original template, but preserved majority of the default code for this section.
-   The ``if`` statements refer to whether or not some settings are chosen in the CMS and tells the template what to do in those
-   cases. We also needed to close to top-level ``container``.
-
-   Another section that we kept was for the ``navbar-toggler``, which sets the hamburger menu when the screen sizes change.
-   Finally, we also kept the ``{% get_navbar_css %}`` tag in the class for the ``nav`` because we can use CSS classes for this
-   navbar from the CMS.
-
-.. note::
-    To add classes in the CMS, look for the line **Custom CSS Class**, which can be found as a field in sections of
-    the admin for a snippet or page, or in the **Advanced** section of a Layout Block. This is where you would put a class
-    like ``bg-warning`` from Bootstrap or a class that you created yourself, like ``logo-banner``.
-
-Adding Custom CSS to the Navbar
-'''''''''''''''''''''''''''''''
+1. Let's copy and paste the `navbar.html template from github. <https://github.com/coderedcorp/coderedcms/blob/dev/coderedcms/templates/coderedcms/snippets/navbar.html>`_.
 
-If you noticed, we have a few custom classes that are not found in Bootstrap. To style our navbar with these classes,
-we need to include them in our CSS file and set the styles the way we want. Once you've done that and saved your work,
-your navbar is ready to show the world!
+.. figure:: img/A01/navbar_html.jpeg
+    :alt: The code for navbar
 
-CSS files will be found in **website > static > css** in your project folder. Unless you are using SASS, you
-will be editing the ``custom.css`` file. For those using SASS, you will want to create a ``navbar.scss`` file in your ``src``
-folder and add a link to it in your ``custom.scss`` file.
+2. Look at your homepage, and you'll see the navbar is back to normal.
+3. To make a two 2-tiered Navbar lets move the logo <a> tag above the <nav> tag.
+4. In our navbar.html file, Highlight from line 5 to 12. Use control + x to cut the code out of the document.
+5. Move your cursor to the end of line 2, hit enter to create a new line and control + C to paste the code we just cut.
+6. Copy the <nav class="navbar {% get_navbar_css %}"> tag.
+7. Use <nav class="navbar {% get_navbar_css %}"> to wrap the logo <a> tag we just moved.  Remember the closing </nav> tag
+8. We also need to add a Bootstrap class for the logo to be in the center.  Use `justify-content-center` in <nav> wrapper.
 
-.. note::
-    If you want to learn how to use SASS, we really like this tutorial:
-    `SASS Guide <https://sass-lang.com/guide>`_.
+.. figure:: img/A01/navbar_html.jpeg
+    :alt: updated code for navbar
 
-This is the CSS that we used for our navbar:
+9. Be sure to save the template, then refresh your browser.
 
-.. code-block:: CSS
+.. figure:: img/A01/logo_centered.jpeg
+    :alt: preview of navbar
 
-    .navbar .nav-link {
-        font-family: 16px;
-        text-transform: uppercase;
-    }
+.. _adding_custom_css:
 
-As you can see, you may not need to use a lot of custom CSS. Sometimes a Bootstrap class will work perfectly.
-Sometimes all you need to do is customize your template HTML and then add Bootstrap classes as needed. It all
-depends on your use case.
+Adding Custom CSS
+-----------------
 
-For our custom navbar, we needed to un-check the "fixed navbar" option in the CMS via **Settings > CRX Settings** in
-order for it to work. Check out what our 2-tiered navbar looks like:
+Basic installation:
 
-.. figure:: img/advanced_two_tiered_navbar.png
-    :alt: Our 2-tiered navbar.
+If you are using the basic installation version, a custom.css file will be found in **website > static > css** in your project folder.  There you can add custom CSS.
+After you add code, all you need to do is save the file and hard refresh your browser to see the changes.
+This is a great option if are using a built in theme, the default color theme, a purchased theme, or don't want to deal with compiling the sass for every CSS change.
+Once you create a class you can use it anywhere by adding it using the advanced setting on a block and the custom CSS class field.  This is also where you can add any bootstrap class.
+Be Sure to check which bootstrap version your project is on and to look at the correct documentation.  There are a fair number of changes from 4.5 to 5.2.
 
-    Our custom 2-tiered navbar on our website.
+Let's look at adding a CSS class on a basic install version of `coderedcms`.
 
+* First let's make a class.
+* We make a class with text-shadow that can be used anywhere see fit on the site.
+* Open **website > static > css > custom.css** in an editor.  (I'm using VS code, which is free)
+* Add the following code:
 
-Example 2: Footer Customization
--------------------------------
+.. code-block:: CSS
 
-Our footer does not need a customized HTML template; however, we think it does need some custom CSS to make it
-look the way we want. Some of our CSS can easily be done in the CMS -- without even touching our CSS file!
+    .text-shadow {
+        text-shadow: black 1px 1px 12px;
+    }
 
-First, go to the Footer Snippet in the **Snippets > Footers** admin in CMS. We had previously added a Bootstrap
-class of ``bg-warning`` to the Attributes section in the Main Footer, but now we want to add CSS classes to each
-of the Layout Blocks for the footer as well.
+.. figure:: img/A01/css_demo.jpg
+    :alt: screen shot of custom.css
 
-1. All of our footer menu items brush up against the top of the footer block. We can add some padding to
-   the footer using `Bootstrap spacing utilities <https://getbootstrap.com/docs/4.0/utilities/spacing/>`_.
+    A screen shot of custom.css with the above code added. (screen shot in VS code)
 
-2. Let's add the padding class ``pt-5`` (which means "padding-top spacer 5") in the Attributes section of
-   the Main Footer. Save and check it out.
+* Save the file.
+* Open the admin screen for your page.
+* Find where you need the class.
+* Open Advanced Settings and type in the class name.
+* **Save** and **Publish** or **Preview**
 
-   .. figure:: img/advanced_footer_overall_padding.png
-      :alt: We added padding to the Attributes section of footer.
+In this example I made a **Hero Unit** with a **Responsive Grid Row** and put my class on the **Column**.
 
-      Our footer with pt-5 added as a class in Attributes section.
+.. figure:: img/A01/custom_css.jpeg
+    :alt: inserted text-shadow css class
 
-3. We want to change the way that the links look, but it doesn't seem as if there is a Bootstrap class for that.
-   That means that it's time to go into our CSS file.
+.. figure:: img/A01/before.jpeg
+    :alt: hard to read hero block
 
-4. We want our links to be that cherry-red, so we will need to use custom CSS and include it in our CSS file.
-   But we also don't want to make ALL of our links this color. That means we should create a class that can be used
-   to specify the link. For example, we could add a class called ``cherry-links`` and target the ``a`` tag.
+    Before custom css class
 
-   .. code:: CSS
+.. figure:: img/A01/after.jpeg
+    :alt: easy to read hero block
 
-      .cherry-links a {
-      color: #f75990;
-      }
+    After custom css class
 
-   Then we place the ``cherry-links`` class in the **Advanced** section of the Layout Block that contains the text
-   for the links, like this:
+This is a relatively simple example.  You can also use any of the bootstrap utility classes when constructing your site.
 
-   .. figure:: img/advanced_customcss1.png
-      :alt: Adding a custom class to the Layout Block
+Sass installation:
+------------------
 
-      Our custom class added to the Layout Block in CMS
+We used sass for the tutorial. It goes over how to change :ref:`global-sass-colors` in the _variables.scss.
+It also covers adding your own :ref:`custom_css` in the custom.scss file.
+The most important things to remember are compile the sass after changes are made and hard refresh the browser after the sass compiles.
 
-   We add it to every Layout Block that needs it. In this case, we have three blocks with links.
+Here are the steps to compile the sass.  In an activated terminal:
 
-   .. figure:: img/advanced_footer_front.png
-      :alt: Our footer right now
+* Stop the server if it's running (control + c)
+* Compile the sass with this command:
+* ``python manage.py sass website/static/website/src/custom.scss website/static/website/css/custom.css``
+* If there are any errors with compiling fix the errors and re-compile.
+* Once the sass is compiled (it will say "done" in the terminal) restart the server.
+* ``python manage.py runserver``
+* Go back to your browser and hard refresh the page.  (I usually hold control and click the refresh)
 
-      Our footer with the custom classes
 
 .. note::
-    We changed the ``pt-5`` class to ``py-5`` to add padding to the top and bottom. Sometimes you will need to try and
-    see which classes will give you the results that you want.
-
-What else could we do to make the footer look better? Take some time to play around with Bootstrap classes in the
-CMS or create some of your own classes to target elements in the footer.
-
-Making More Drastic CSS Changes Sitewide
-----------------------------------------
-
-**What we did:** So, we went back and changed some of our classes in the HTML template and in the CMS to reflect some
-new classes that we created, such as ``bg-lightyellow`` and ``bg-cherry``.
-
-We've also added some additional padding classes in places where we thought it would look good.
-
-Finally, we decided that our logo needed an update as well. So, we swapped our original logo for one
-that fit our new color scheme.
-
-This is what our website looks like now with all of our customizations and updates:
-
-.. figure:: img/advanced_improved_website1.png
-    :alt: Our customized website so far
-
-    Our updated and customized website so far
-
-And this is our CSS file at the moment:
-
-.. code:: CSS
-
-    /*Navbar */
-    .navbar .nav-link {
-        font-family: 16px;
-        text-transform: uppercase;
-    }
-
-    /* Custom CSS classes */
-    .cherry-links a {
-        color: #f75990;
-    }
-
-    .bg-lightyellow {
-        background-color: #fff685;
-    }
-
-    .bg-cherry {
-        background-color: #f75990;
-    }
-
-With the combination of using Bootstrap classes directly in the CMS and making our own classes, which we can use in the CMS
-and in custom templates, we can quickly update our site with our changes. There's more that we want to do, but now
-we have a good start on a beautiful, customized website!
+    If you want to learn more about SASS, we really like this tutorial:
+    `SASS Guide <https://sass-lang.com/guide>`_

docs/advanced/advanced02.rst

@@ -19,29 +19,23 @@ Prep work for custom pages
 --------------------------
 
 We need to plan our page ahead of time. What fields will our custom page need, and what will we need our page
-to do? Take the time to write down the answer to these questions before you even touch the code. This is what
-we are writing down for Simple Sweet Dessert's custom cupcake page:
+to do? In this example we are going to add a products page and a product landing page.  As we add more products
+they will automatically be included on the landing page like articles.  For this example, we have to decide what fields we need.
 
-**Our Prep Notes**
 
-1. We want our page to page to list the attributes and descriptions of individual cupcakes.
+**Product Page Fields:**
 
-2. We want to be able to display the cupcakes in cards automatically on a landing page.
+* Name of the product (This will be the title of the page in this instance)
 
+* Photo of the product
 
-**Cupcake Page Fields:**
+* Description of the product
 
-* Name of cupcake (This could be the title of the page)
+* Does this product require a prescription.
 
-* Photo of cupcake
+**Product Landing Page Fields:**
 
-* Description of cupcake
-
-* Days when these cupcakes are made
-
-**Cupcake Landing Page Fields:**
-
-* Needs to be the parent page for the cupcake pages
+* Needs to be the parent page for the product pages
 
 Setting up the page models
 --------------------------
@@ -63,7 +57,7 @@ frameworks that we are using.
         CoderedArticleIndexPage,
         CoderedEmail,
         CoderedFormPage,
-        CoderedWebPage
+        CoderedWebPage,
     )
 
 
@@ -71,69 +65,30 @@ frameworks that we are using.
         """
         Article, suitable for news or blog content.
         """
-        class Meta:
-            verbose_name = 'Article'
-            ordering = ['-first_published_at']
-
-        # Only allow this page to be created beneath an ArticleIndexPage.
-        parent_page_types = ['website.ArticleIndexPage']
-
-        template = 'coderedcms/pages/article_page.html'
-        search_template = 'coderedcms/pages/article_page.search.html'
-
-
-    class ArticleIndexPage(CoderedArticleIndexPage):
-        """
-        Shows a list of article sub-pages.
-        """
-        class Meta:
-            verbose_name = 'Article Landing Page'
-
-        # Override to specify custom index ordering choice/default.
-        index_query_pagemodel = 'website.ArticlePage'
-
-        # Only allow ArticlePages beneath this page.
-        subpage_types = ['website.ArticlePage']
-
-        template = 'coderedcms/pages/article_index_page.html'
-
-
-    class FormPage(CoderedFormPage):
-        """
-        A page with an html <form>.
-        """
-        class Meta:
-            verbose_name = 'Form'
-
-        template = 'coderedcms/pages/form_page.html'
 
-
-    class FormPageField(CoderedFormField):
-        """
-        A field that links to a FormPage.
-        """
         class Meta:
-            ordering = ['sort_order']
+            verbose_name = "Article"
+            ordering = ["-first_published_at"]
 
-        page = ParentalKey('FormPage', related_name='form_fields')
+        # Only allow this page to be created beneath an ArticleIndexPage.
+        parent_page_types = ["website.ArticleIndexPage"]
 
+        template = "coderedcms/pages/article_page.html"
+        search_template = "coderedcms/pages/article_page.search.html"
 
-    class FormConfirmEmail(CoderedEmail):
-        """
-        Sends a confirmation email after submitting a FormPage.
-        """
-        page = ParentalKey('FormPage', related_name='confirmation_emails')
 
+    ## OTHER CLASSES
 
     class WebPage(CoderedWebPage):
         """
         General use page with featureful streamfield and SEO attributes.
-        Template renders all Navbar and Footer snippets in existence.
         """
+
         class Meta:
-            verbose_name = 'Web Page'
+            verbose_name = "Web Page"
+
+        template = "coderedcms/pages/web_page.html"
 
-        template = 'coderedcms/pages/web_page.html'
 
 
 Before we begin adding our fields for our new page models, we should add the page class, meta class,
@@ -141,46 +96,47 @@ and template information for our pages.
 
 * We our extending the ``CoderedWebPage`` model which is why it is wrapped in parentheses after we name our page model.
 
-* We are indicating that Cupcake pages are sub-pages of the Cupcake Landing Page.
+* We are indicating that Product pages are sub-pages of the Product Landing Page.
 
-* We are specifying the template files that the page models should use, which should also be created in our ``templates\website\pages`` folder.
+* We are specifying the template files the page models use, these need to be created in the ``templates\website\pages`` folder.
 
 Add this code below the other page models:
 
 .. code:: python
 
-    class CupcakesIndexPage(CoderedWebPage):
+    class ProductIndexPage(CoderedWebPage):
         """
-        Landing page for Cupcakes
+        Landing page for Products
         """
         class Meta:
-            verbose_name = "Cupcakes Landing Page"
+            verbose_name = "Product Landing Page"
 
         # Override to specify custom index ordering choice/default.
-        index_query_pagemodel = 'website.CupcakesPage'
+        index_query_pagemodel = 'website.ProductPage'
 
-        # Only allow CupcakesPages beneath this page.
-        subpage_types = ['website.CupcakesPage']
+        # Only allow ProductPages beneath this page.
+        subpage_types = ['website.ProductPage']
 
-        template = 'website/pages/cupcakes_index_page.html'
+        template = 'website/pages/product_index_page.html'
 
 
-    class CupcakesPage(CoderedWebPage):
+    class ProductPage(CoderedWebPage):
         """
-        Custom page for individual cupcakes
+        Custom page for individual products
         """
 
         class Meta:
-            verbose_name = "Cupcakes Page"
+            verbose_name = "Product Page"
 
-        # Only allow this page to be created beneath an CupcakesIndexPage.
-        parent_page_types = ['website.CupcakesIndexPage']
+        # Only allow this page to be created beneath an ProductIndexPage.
+        parent_page_types = ['website.ProductIndexPage']
 
-        template = "website/pages/cupcakes_page.html"
+        template = "website/pages/product_page.html"
 
 
-At the top of each ``.html`` template page, we want to add these tags so that we have a basic functioning
-template prepared:
+* Create the template pages ``product_page.html`` and ``product_index_page.html`` in the ``templates\website\pages`` folder.
+
+* At the top of these template pages, add these tags to have basic functioning template:
 
 .. code:: Django
 
@@ -188,9 +144,9 @@ template prepared:
     {% load wagtailcore_tags wagtailimages_tags coderedcms_tags %}
 
 
-Now we can turn our attention back to our page models, specifically the CupcakesPage.
-Since the name of the cupcake could just be the title of the page, we don't need to add a custom field
-for that information. We do, however, need a few fields.
+Now we can turn our attention back to our page models, specifically the ProductPage.
+In this example the the name of the product will be the title of the Page.
+We need to add other fields to be be in alignment with the outline we looked at earlier.
 
 .. code:: python
 
@@ -201,23 +157,24 @@ for that information. We do, however, need a few fields.
     from wagtail.images import get_image_model_string
     from wagtail.images.edit_handlers import ImageChooserPanel
 
+    # Update the product page with these fields
 
-    class CupcakesPage(CoderedWebPage):
+    class ProductPage(CoderedWebPage):
         """
-        Custom page for individual cupcakes
+        Custom page for individual products
         """
 
         class Meta:
-            verbose_name = "Cupcakes Page"
+            verbose_name = "Product Page"
 
-        # Only allow this page to be created beneath an CupcakesIndexPage.
-        parent_page_types = ['website.CupcakesIndexPage']
+        # Only allow this page to be created beneath an ProductIndexPage.
+        parent_page_types = ['website.ProductIndexPage']
 
-        template = "website/pages/cupcakes_page.html"
+        template = "website/pages/product_page.html"
 
-        # Cupcakes Page model fields
+        # Product Page model fields
         description = RichTextField(
-            verbose_name="Cupcake Description",
+            verbose_name="Product Description",
             null=True,
             blank=True,
             default=""
@@ -228,85 +185,91 @@ for that information. We do, however, need a few fields.
             blank=True,
             on_delete=models.SET_NULL,
             related_name='+',
-            verbose_name='Cupcake Photo',
-        )
-        DAYS_CHOICES = (
-            ("Weekends Only", "Weekends Only"),
-            ("Monday-Friday", "Monday-Friday"),
-            ("Tuesday/Thursday", "Tuesday/Thursday"),
-            ("Seasonal", "Seasonal"),
-        )
-        days_available = models.CharField(
-            choices = DAYS_CHOICES,
-            max_length=20,
-            default=""
+            verbose_name='Product Photo',
         )
+        need_prescription = models.BooleanField(default=True)
 
         # Add custom fields to the body
         body_content_panels = CoderedWebPage.body_content_panels + [
             FieldPanel("description"),
             FieldPanel("photo"),
-            FieldPanel("days_available"),
+            FieldPanel("need_prescription"),
         ]
 
 
 **What's happening?**
 
-Okay, we had to add some imports at the top to be able to use these field types in our model.
+We had to add some imports at the top to be able to use these field types in our model.
 If we try to makemigrations/migrate without having these imported, it will show an error.
 
-Next, we added the fields we need with the field types that tell it how to function. Our description
-will be a RichTextField which is essentially a text box that allows formatting. Then our photo needs to be
-able to be associated with the page as well as be uploaded via an ImageChooserPanel -- the popup we get when
-we want to add a photo in the CMS.
+Next, we added the necessary fields and their field types that specify functionality.
 
-Finally, we added a field for choosing which days the cupcake is available and we made this a dropdown choice
-panel. We had to set the choices first, then include the choices in our field selector.
+* ``description`` is a RichTextField (essentially a text box) that allows formatting.
+* ``photo`` uses a ForeignKey to reference the image_mode. This allows an image to be uploaded via an ImageChooserPanel -- the popup we get when we want to add a photo in the CMS.
+* ``need_prescription`` is a Boolean value that tells us if the product requires a prescription.
+* ``body_content_panels`` is defining which page builder blocks the editing screen should show. (In this instance, it's using the wagtail-CRX standard blocks, plus the custom fields in the model.)
 
-At the bottom of our model, we are telling it to allow for the standard CMS page builder blocks as well as our custom
-fields.
+These changes to the models have to be migrated in the the database. To do so:
+
+* You need to have an active virtual environment. (See :ref:`installation` notes for help)
+* (if running) Stop your server with ``control + c``
+* Run ``python manage.py makemigrations`` (The makemigrations command uses the models specify changes that are going to be made to the database)
+* Run ``python manage.py migrate`` (The migrate command makes those changes)
 
-Now we can run ``python manage.py makemigrations website`` and ``python manage.py migrate`` to test our work.
 It should migrate successfully. (If not, read what the error says and fix it. A typo can cause huge problems!)
 
-Run the server again with ``python manage.py runserver`` to see how it looks in your CMS admin.
+* Run the server with ``python manage.py runserver`` to see how it looks in your CMS admin.
+
+You should now see Product Landing Page as a page choice.
+
+.. figure:: img/A02/plp_as_child.jpeg
+    :alt: product landing page in the page selector
+
+To be inline with our CRX-pharma design (from the getting started tutorial), we are going to add a **Product Landing Page** as a child of the "Our Products" page **Home > Our Products**.
+Hopefully, if you followed the tutorial this is a pretty basic operation.  As a quick "refresher":
+
+* Click **Pages** in the side menu
+* Use the arrow and click on the "Our Product Page".  ("If you don't have one, just use Home")
+* This opens the page management screen.  Click **Add child page**
+* Choose page type **Product Landing Page**
+* Give it a title (Direct to Consumer Products)
+* (optional) Add a cover image.
 
-You should now see Cupcake Landing Page as a child page choice under Home page. Choose this, add a title and
-publish it. The page does not have a template made; however, it uses the basic CodeRed Web Page so it will display
-something.
+.. figure:: img/A02/plp_editor.jpeg
+    :alt: product landing page editor
 
-Now you can add Cupcake Pages, which are sub-pages of the Cupcake Landing Page. While the fields for this page
-do not currently show up on the published page, you can add content in the editor mode.
+* **Save** and **Publish**
 
 .. note::
-    We have to create a custom page template to display the custom fields on the published page.
+    We still have to work on the templates for both Product Page and Product Landing Page.  They are placeholders to prevent Django from throwing errors.
+
+
+Let's add a Product Page to the project:
+
+* Click **Add child page** on the the Product Landing Page we just published (titled "Direct to Consumer Products")
+
+.. figure:: img/A02/pp_editor.jpeg
+    :alt: product page editor
+
+Look at the fields. The page editor has the standard "CoderedWebPage" fields (Title, Cover image, and Body) plus the ones we added to the model (Product Description, Product Photo, and Need prescription).
+
+* Make 3 or 4 Product pages.
+* Remember to **Save** and **Publish** each page.
 
 
 Building our custom page templates
 ----------------------------------
 
-Since our models are working and we can add content to the fields, we can begin creating our custom page
-template. Navigate to the ``cupcakes_page.html`` file in your project's templates folder. We added the basic
-page tags at the top of the page earlier. In case you need to add them, they are:
+Navigate to ``templates\website\pages\product_page.html``. This code was added earlier:
 
 .. code::
 
     {% extends "coderedcms/pages/web_page.html" %}
     {% load wagtailcore_tags wagtailimages_tags coderedcms_tags %}
 
-Now we want to tell the page to not display the page's title where the cover image would be if there is no cover
-image (because we plan to use the page's title aka the cupcake name elsewhere on the page).
-
-The standard CodeRed Web Page template has an ``{% if %} {% else %}`` statement regarding cover images that says to show the page title when a cover image
-is not available. We will add that same code to our page but remove the ``else`` statement so that it does nothing when a cover image is not available.
-
-We will also set up the basic layout for our page: a two half-sized columns in a row. To pull in our field data,
-we reference the page and then the field, like this ``{{page.title}}`` or ``{{page.description}}``.
+These page tags extend the wagtail-CRX page and gives us access to the data in store in the database for each page.
 
-For the image, we specify what size it should be and give it a shorter reference name for the variable.
-
-We added a few Bootstrap classes and custom classes to change the padding a little and some text colors, as well
-as add a border around the image that is centered within the column.
+Here is our whole template:
 
 **Our template code:**
 
@@ -315,33 +278,46 @@ as add a border around the image that is centered within the column.
     {% extends "coderedcms/pages/web_page.html" %}
     {% load wagtailcore_tags wagtailimages_tags coderedcms_tags %}
 
+
     {% block content_pre_body %}
-        {% if self.cover_image %}
-        {% image page.cover_image fill-2000x1000 as cover_image %}
-        <div class="jumbotron jumotron-fluid" style="height:400px;background-image:url({{cover_image.url}});background-repeat:no-repeat; background-size:cover; background-position:center center;">
+    {% if self.cover_image %}
+    {% image page.cover_image fill-1600x900 format-webp as cover_image %}
+    <div class="hero-bg mb-5" style="background-image:url({{cover_image.url}});">
+    <div class="hero-fg">
+        <div class="container text-center">
+        <h1 class="text-white text-shadow">{{page.title}}</h1>
         </div>
-        {% endif %}
+    </div>
+    </div>
+    {% endif %}
     {% endblock %}
 
-
     {% block content_body %}
     <div class="block-row">
         <div class="container-fluid">
             <div class="row m-4">
                 <div class="col-lg-6">
                     {% if page.photo %}
-                    {% image page.photo fill-300x300 as cupcake %}
+                    {% image page.photo fill-400x400 as product %}
                     <div class="text-center">
-                        <img class="border-cherry" src="{{cupcake.url}}" alt="photo of {{page.title}}">
+                        <img src="{{product.url}}" alt="photo of {{page.title}}">
                     </div>
                     {% endif %}
                 </div>
                 <div class="col-lg-6">
                     <div class="py-lg-5">
-                        <h2>{{page.title}}</h2>
-                        <lead class="text-cherry">{{page.days_available}}</lead>
+                        {% if self.cover_image %}
+                        {% else %}
+                        <h2 class="text-primary fw-bold fs-1 mb-2">{{page.title}}</h2>
+                        {% endif %}
+
                         {% if page.description %}
-                        <p>{{page.description|richtext}}</p>
+                        {{page.description|richtext}}
+                        {% endif %}
+                        {% if page.need_prescription %}
+                        <div class="fs-5"> Call your doctor to see if {{page.title}} is right for you!</div>
+                        {% else %}
+                        <div class="fs-5"> No Prescription Needed!</div>
                         {% endif %}
                     </div>
                 </div>
@@ -350,48 +326,75 @@ as add a border around the image that is centered within the column.
     </div>
     {% endblock %}
 
+The ``{% block content_pre_body %}`` tag overrides part of the standard template.  It uses conditional logic {% if %} to render the page title {{page.title}} in the header if the user
+adds a cover image.  If they don't, the page.title renders in {% block content_body %}.  There is a basic two column, with the image on the left and a description on the right.  It also uses an
+{% if %} {% else %} statement with the {{page.need_prescription}} to render different text based on if the product needs a prescription.
 
-We added some content for a cupcake page in the CMS and published it.
+There is a lot to cover in Django templating. Check out the docs for more info `Django Templates <https://docs.djangoproject.com/en/4.1/topics/templates/>`_
 
-Let's take a look.
+Here's the same template with and without a cover image:
 
-.. figure:: img/cupcake_page_published.png
-    :alt: Our customized cupcake page so far
+.. figure:: img/A02/pp_preview.jpeg
+    :alt: product page preview with out cover image
 
-    Our customized cupcake page so far
+No cover image so the page title renders in the body.
 
+.. figure:: img/A02/pp_preview2.jpeg
+    :alt: product page preview with cover image
 
-It works! Continue to add cupcake pages until you have a decent amount of them --
-five or so would be good.
+With the cover image and the title is centered with a bootstrap class "text-center" in the template.
 
-Building the Cupcake Landing Page
+Building the Product Landing Page
 ---------------------------------
 
 While we could simply use the the default "Show Child Pages" option for the page, a list of links
-is rather boring. We also want the page to automatically update whenever we add a new cupcake to save us lots of time
-and trouble. How can we dynamically update our Cupcake Landing Page?
+is rather boring. We also want the page to automatically update whenever we add a new product to save us lots of time
+and trouble. He is our template:
 
 .. code:: Django
 
     {% extends "coderedcms/pages/web_page.html" %}
     {% load wagtailcore_tags wagtailimages_tags coderedcms_tags %}
 
-    {% block index_content %}
+    {% block content_pre_body %}
+    {% if self.cover_image %}
+    {% image page.cover_image fill-1600x900 format-webp as cover_image %}
+    <div class="hero-bg mb-5" style="background-image:url({{cover_image.url}});">
+    <div class="hero-fg">
+        <div class="d-flex justify-content-center">
+        <h1 class="text-shadow text-white">{{page.title}}</h1>
+        </div>
+    </div>
+    </div>
+    {% else %}
     <div class="container">
-        <div class="row d-flex">
-            {% for cupcake in page.get_children.specific %}
-            <div class="col m-3">
-                <div class="card border-cherry" style="width: 18rem;">
-                    {% if cupcake.photo %}
-                    {% image cupcake.photo fill-300x300 as cupcake_photo %}
-                    <a href="{{cupcake.url}}">
-                        <img class="card-img-top w-100" src="{{cupcake_photo.url}}" alt="{{cupcake.title}}">
+    <h1>{{page.title}}</h1>
+    </div>
+    {% endif %}
+    {% endblock %}
+
+
+    {% block index_content %}
+    <div class="container mb-5">
+        <div class="row row-cols-2 row-cols-md-3 row-cols-xl-4">
+            {% for product in page.get_children.specific %}
+            <div class="col  text-center">
+                <div class="card h-100">
+                    {% if product.photo %}
+                    {% image product.photo fill-300x300 as product_photo %}
+                    <a href="{{product.url}}">
+                        <img class="card-img-top w-100" src="{{product_photo.url}}" alt="{{product.title}}">
                     </a>
                     {% endif %}
                     <div class="card-body">
                     <div class="card-text">
-                        <h3><a class="text-cherry" href="{{cupcake.url}}">{{cupcake.title}}</a></h3>
-                        <p class="lead">{{cupcake.days_available}}</p>
+                        <h5><a href="{{product.url}}">{{product.title}}</a></h5>
+                        {{product.description|richtext}}
+                        {% if page.need_prescription %}
+                        <p> Call your doctor to see if {{page.title}} is right for you!</p>
+                        {% else %}
+                        <p> No Prescription Needed!</p>
+                        {% endif %}
                     </div>
                     </div>
                 </div>
@@ -401,18 +404,17 @@ and trouble. How can we dynamically update our Cupcake Landing Page?
     </div>
     {% endblock %}
 
-
 **What's happening?**
 
-We are using a ``{% block index_content %}`` and a ``{% for cupcake in page.get_children.specific %}`` loop that pulls
-in content from the child/sub-pages. Our new variable for the sub-pages is ``cupcake``, so we reference the fields like so:
-``{{cupcake.title}}``. In the CMS we want to make show that "Show Child Pages" is NOT selected because it will just show
-the list of page links in addition to our custom cards. This is what our published landing page looks like now:
+We are using a ``{% block index_content %}`` and a ``{% for product in page.get_children.specific %}`` loop that pulls
+in content from the child/sub-pages. Our new variable for the sub-pages is ``product``, so we reference the fields like so:
+``{{product.title}}``. The different products are in cards in card-grid, size with different bootstrap breakpoints.
+
+This is what our published landing page looks like now:
 
-.. figure:: img/cupcake_landing_published.png
-    :alt: Our customized landing cupcake page so far
+.. figure:: img/A02/plp_preview.jpeg
+    :alt: product landing page preview
 
-    Our customized cupcake landing page dynamically pulling in child pages as cards
+Product Landing Page on a large screen.
 
 
-Now we can keep customizing our templates until we get the design that we want.

docs/contributing/index.rst

@@ -303,10 +303,10 @@ Output will be in ``docs/_build/html/`` directory.
 Updating Tutorial Documentation
 -------------------------------
 
-From time to time, the documentation for the tutorial will need to be updated. You can work directly in
-the tutorial site by loading the fixture file for its database (read more at :ref:`load-data`).
+.. From time to time, the documentation for the tutorial will need to be updated. You can work directly in
+.. the tutorial site by loading the fixture file for its database (read more at :ref:`load-data`).
 
-However, once you have worked in the tutorial site and gotten new screenshots for the **Getting Started** documentation,
+Once you have worked in the tutorial site and gotten new screenshots for the **Getting Started** documentation,
 you will also need to update the fixture file, which is located in ``tutorial > mysite > website > fixtures``.
 
 **These are the steps for updating the fixture:**
@@ -317,7 +317,7 @@ you will also need to update the fixture file, which is located in ``tutorial >
 
 3. Move the ``database.json`` file into the ``fixtures`` folder.
 
-4. For testing ``loaddata``, please review the steps at  :ref:`load-data`.
+.. 4. For testing ``loaddata``, please review the steps at  :ref:`load-data`.
 
 
 Publishing a New Release

docs/features/blocks/contentblocks/accordion.rst

@@ -1,11 +0,0 @@
-Accordion Block
-===============
-
-Creates a collapsible section with a button to toggle.
-
-Field Reference
----------------
-
-Fields and purposes:
-
-* **Accordion** - Choose a preexisting accordion snippet, created under snippets.

docs/features/blocks/contentblocks/carousel.rst

@@ -1,32 +0,0 @@
-Carousel Block
-==============
-
-Allows the user to create a carousel with image backgrounds and relevant blocks. 
-
-Field Reference
----------------
-
-Fields and purposes:
-
-* **Carousel** - Choose a Carousel
-
-.. figure:: img/carousel_block.png
-    :alt: The carousel block
-
-    The carousel block
-
-If you don't have any carousels already made, you can build a carousel by clicking **Choose A Carousel** and
-clicking on "Why not **create one now**?" in the popup box. This will take you to **Snippets > Carousels** where
-you can create a carousel to add to the page. 
-
-.. figure:: img/carousel_snippet.png
-    :alt: Building a carousel in Snippets
-
-    The edit mode for building a carousel snippet
-
-Now you can select your carousel. Ours is named Cupcakes. 
-
-.. figure:: img/carousel_published.png
-    :alt: Our carousel published on the page
-
-    The carousel published on a page

docs/features/blocks/contentblocks/image.rst

@@ -1,19 +0,0 @@
-Image Block
-===========
-
-Allows the user to add and display an image. Crops the image to a 1:1 (Square) ratio
-
-Field Reference 
----------------
-
-Fields and purposes:
-
-* **Choose an Image** - Choose an image 
-
-When you choose an image, a popup allows you to search for images that you have already uploaded, or you can upload
-a new image. 
-
-.. figure:: img/image_chooser_block.png
-    :alt: The image chooser for the image block
-
-    The image chooser for the image block

docs/features/blocks/contentblocks/imagegallery.rst

@@ -1,43 +0,0 @@
-Image Gallery Block
-===================
-
-Creates and displays a collage of images from a collection. 
-
-Field Reference 
----------------
-
-Fields and purposes:
-
-* **Collection** - Choose the image collection to display as a Gallery
-
-The default collection is ``ROOT`` which will choose all of the images on the site. You can, however, create custom 
-image collections. 
-
-How To Create A Collection
---------------------------
-
-1. Go to **Settings > Collections**.
-
-2. Click the **Add a Collection** button on the top right-hand corner.
-
-3. Name the collection and save it.
-
-4. Go to **Images** and click on each image that you want to add to the collection.
-
-5. Choose the desired collection from the dropdown in the image's **Collection** field. 
-
-6. Save the image. 
-
-Once you have created a Collection, it will become available in the Image Gallery block. 
-
-.. figure:: img/image_gallery_block.png
-    :alt: Our collection choice for the image gallery block
-
-    Our collection choice for the image gallery block
-
-The images will display in a row. When the image is clicked on, it will become a popup image for better viewing.
-
-.. figure:: img/image_gallery_published.png
-    :alt: Our published image gallery
-
-    Our published image gallery

docs/features/blocks/index.rst

@@ -1,13 +0,0 @@
-Blocks
-======
-
-Wagtail CRX includes several blocks which can be used in the StreamField.
-Content blocks are used for actual content (text, images, etc.); Layout blocks
-are used for creating structures that hold other blocks (for example, rows and
-columns).
-
-.. toctree::
-    :maxdepth: 2
-
-    contentblocks/index
-    layoutblocks/index

docs/features/blocks/layoutblocks/cardgrid.rst

@@ -1,35 +0,0 @@
-.. _card-grid:
-
-Card Grid Block
-===============
-
-Creates a card grid layout with content and button options
-
-Field Reference
----------------
-
-Fields and purposes:
-
-* **Full Width** - If selected, sets whether the card grid spans the entire width of the screen
-
-* **Content** - The individual cards in the grid
-
-In your page editor, choose **Card Grid**. Select the **Card** content block within the Card grid block 
-to get started on creating your Card Grid. The grid is designed to automatically create the layout of 
-your cards with an image, title, subtitle, body and button links. Create as many cards as you would 
-like for your card grid. They will be sized based on available space on the screen. 
-
-We have a card grid on the home page of our tutorial site Simple Sweet Desserts. It looks like this:
-
-.. figure:: img/card_grid_example.png
-    :alt: Our sweet card grid on the home page
-
-    Our sweet card grid on the home page of our tutorial site -- no images
-
-We also created another card grid on a Practice Layout Page on our tutorial site that looks like this:
-
-.. figure:: img/card_grid_images.png
-    :alt: Our cupcake card grid with images
-
-    Our cupcake card grid, with images
-

docs/features/contentblocks/accordion.rst

@@ -0,0 +1,46 @@
+.. _accordion-block:
+
+Accordion Block
+===============
+
+Creates a collapsible section with a button to toggle.
+Each Accordion has multiple sections or panels.
+
+`View example live <https://crxpharma.codered.cloud/demo-blocks/accordion-block/>`_
+
+
+Example:
+
+.. figure:: images/accordion_closed.jpeg
+    :alt: demo accordion closed
+
+    Demo accordion closed
+
+.. figure:: images/accordion_open.jpeg
+    :alt: demo accordion with panel open
+
+    Demo accordion with panel open
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Accordion** - Choose a preexisting accordion snippet, created under snippets.
+
+Editor:
+
+.. figure:: images/accordion_demo.jpeg
+    :alt: Editing screen for accordion
+
+    Editing screen for accordion
+
+Each Accordion panel needs a name and content.  After you make a second panel,
+arrows will appear to allow you to change the order of the panels.
+
+.. figure:: images/accordion_arrows.jpeg
+    :alt: arrows on the accordion panels
+
+    Arrows on the accordion panels. They appear after you make a second panel.
+
+Additional Information in the `bootstrap docs <https://getbootstrap.com/docs/5.2/components/accordion/>`_

docs/features/blocks/contentblocks/button.rst → docs/features/contentblocks/button.rst

@@ -4,6 +4,15 @@ Button Block
 The button block renders an HTML anchor styled as a button. This can be used to
 link to pages, documents, or external links.
 
+Example:
+
+.. figure:: images/button_example.jpeg
+    :alt:  default button styles
+
+    default button styles
+
+Note this screen shot was taken using the default bootstrap colors.  If you use a theme or change global colors with sass,
+they will likely be different colors.
 
 Field Reference
 ---------------

docs/features/blocks/contentblocks/card.rst → docs/features/contentblocks/card.rst

@@ -1,12 +1,16 @@
+.. _card-block:
+
 Card Block
 ==========
 
-Allows the user to fill out information to be displayed in a card. Crops the image to a 3:2 ratio. 
+Allows the user to fill out information to be displayed in a card. Crops the image to a 3:2 ratio.
 
 .. note::
-    There is also a :ref:`card-grid` which groups cards into a grid and is a Layout Block; 
+    There is also a :ref:`card-grid` which groups cards into a grid and is a Layout Block;
     this Card Block only displays a single card.
 
+Example: See below.
+
 Field Reference
 ---------------
 
@@ -22,5 +26,14 @@ Fields and purposes:
 
 * **Links > Button Link** - The button link to include at the bottom of the card, set to link to a page or external link
 
+* **Advanced Settings > Template** - Multiple options for Card layouts.  See Below for reference.
+
+Here is the same card, using different templates in the advanced settings:
+
+.. figure:: images/card_layout_options.jpeg
+    :alt: Grid of a card with different layout templates selected
+
+    A Grid of a card with different layout templates selected.
+
 Explore `Bootstrap Cards <https://getbootstrap.com/docs/4.0/components/card/>`_ to get an understanding of the
-appearance and function of cards. 
+appearance and function of cards.

docs/features/contentblocks/carousel.rst

@@ -0,0 +1,79 @@
+.. _carousel-block:
+
+Carousel Block
+==============
+
+Allows the user to create a carousel with image backgrounds and relevant blocks.
+Carousels automatically change slides, but also have arrow controls for the user to advance or return to the previous slide.
+Make a Carousel by going to **Snippets > Carousels** and clicking Add Carousel.
+
+Example:
+    .. figure:: images/carousel_example.jpeg
+        :alt:  default button styles
+
+        default button styles
+
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Carousel** - Choose a Carousel
+
+If you don't have any carousels already made, you can build a carousel by clicking **Choose A Carousel** and
+clicking on "Why not **create one now**?" in the popup box. This will take you to **Snippets > Carousels** where
+you can create a carousel to add to the page.  Here is a carousel editor with three slides; each slide has a caption:
+
+.. figure:: images/carousel_editor.jpeg
+    :alt: Building a carousel in Snippets
+
+    The edit mode for building a carousel snippet
+
+Save your work and now you can select that carousel in a page editor. This one is named Demo.  Here is a preview of for one of our slides:
+
+.. figure:: images/carousel_preview.jpeg
+    :alt: Our carousel published on the page
+
+    The carousel published on a page
+
+You'll notice it's hard to see the caption because the bootstrap default text is white.  Let's look at customizing our carousel two different ways.
+
+First, you can override the CSS class.  If you look at the `bootstrap docs <https://getbootstrap.com/docs/5.2/components/carousel/>`_ or the template.
+You'll find the class for caption is ``carousel-caption``.  For our example, let's add a background-color and border-radius.
+
+.. code:: CSS
+
+        .carousel-caption{
+            background-color: rgba(60, 60, 60, 0.5);
+            border-radius: 10px;
+        }
+
+Add this to your custom.css file (basic installation) or the custom.scss file (sass installation).
+Save the file, compile the sass(sass install only), and hard refresh the browser.  See :ref:`adding_custom_css` for more details.
+
+.. figure:: images/carousel_preview_bg.jpeg
+    :alt: Our carousel published on the page
+
+    The carousel published on a page
+
+The second option would be to alter the template.
+Looking at the `bootstrap docs <https://getbootstrap.com/docs/5.2/components/carousel/>`_ you can find there is a dark variant.
+See :ref:`customizing_templates` for a more detailed tutorial on overriding templates.
+
+* To alter our template you need to copy the template from `github <https://github.com/coderedcorp/coderedcms/blob/dev/coderedcms/templates/coderedcms/blocks/carousel_block.html>`_
+* Paste the file in the correct directory so it overrides the default template. Our file path: **mysite>website>templates>coderedcms>blocks>carousel_block.html**
+* In carousel_block.html on line 4; add carousel-dark to the class attribute.  The line should now look like this:
+
+.. code:: html
+
+    <div id="carousel-{{self.carousel.id}}" class="carousel carousel-dark slide" data-bs-ride="carousel">
+
+* Save the file and refresh the browser.
+
+.. figure:: images/carousel_preview_dark.jpeg
+    :alt: Our carousel published on the page
+
+    The carousel published on a page
+
+(In this example, I removed the custom css for .carousel-caption from the previous example)

docs/features/blocks/contentblocks/download.rst → docs/features/contentblocks/download.rst

@@ -2,7 +2,9 @@ Download Block
 ==============
 
 The download block enables users to add documents to the CMS which website
-visitors can download from the site.
+visitors can download from the site.  The download block is a button and has the same options.
+
+Example: See Button Block.
 
 Field Reference
 ---------------
@@ -18,20 +20,18 @@ Field Reference
   ``CRX_FRONTEND_BTN_SIZE_CHOICES`` Django setting and is inserted as a CSS
   class in the HTML.
 
-* **Auto Download** - Enables automatic download upon click of the button
-
 * **Document Link** - Link to the document, which you will need to upload into the CMS
 
-* **Advanced Settings** - Add custom CSS classes or a CSS ID to style the block with your custom CSS
+* **Advanced Settings** - Add custom CSS classes or a CSS ID
 
-.. figure:: img/blocks_download.png
+.. figure:: images/download_block_editor.jpeg
     :alt: A download block and its settings.
 
     A download block and its settings.
 
-.. figure:: img/blocks_choose_doc.png
-    :alt: Choosing the document
+.. figure:: images/document_selection_modal.jpeg
+    :alt: The document selection modal
 
-    The popup for choosing which document you want to upload to the block for download by users
+    The modal to search current or upload new documents for users to download.
 
 When a website visitor clicks the button, the document is available for download in a new window.

docs/features/blocks/contentblocks/embedmedia.rst → docs/features/contentblocks/embedmedia.rst

@@ -4,6 +4,11 @@ Embed Media Block
 The embed media block allows users to embed media like YouTube videos or SoundCloud with just a link
 to the external media source.
 
+Example:
+  .. figure:: images/embed_media_preview.jpeg
+    :alt: How it displays on the page.
+
+
 Field Reference
 ---------------
 
@@ -12,20 +17,15 @@ Fields and purposes:
 * **URL** - The URL for the external media, whether it's a tweet, Facebook post, YouTube video, etc.
 
 .. note::
-    Add an external media link like this YouTube video about making fancy cupcakes: `<https://youtu.be/eXkyUi5HKpM>`_ .
+    Add an external media link like this YouTube video about a 48 deployment on the CodeRed Hosting platform: `<https://www.youtube.com/watch?v=hzuqZnw4lQ4>`_ .
 
-* **Advanced Settings** - Add custom CSS classes or a CSS ID to style the embed with your custom CSS 
+* **Advanced Settings** - Add custom CSS classes or a CSS ID to style the embed with your custom CSS
 
-.. figure:: img/embedmedia1.png
+.. figure:: images/embed_media_block.jpeg
     :alt: An embed media block with fields.
 
     An embed media block with its fields.
 
-
-.. figure:: img/embedmedia2.png
-    :alt: How it displays on the page.
-
-    How the embedded media would display on the published page.
 .. note::
     You can use Bootstrap utility classes like ``w-50`` on your embeds. The size of the video
-    also changes depending on whether it's in a full-width column or a half-column, etc. 
+    also changes depending on whether it's in a full-width column or a half-column, etc.

docs/features/blocks/contentblocks/googlemap.rst → docs/features/contentblocks/googlemap.rst

@@ -1,7 +1,14 @@
 Google Map Block
 ================
 
-Allows the user to add a Google Map location and display the location on the map. 
+Allows the user to add a Google Map location and display the location on the map.
+
+Example:
+
+.. figure:: images/google_map_preview.jpeg
+    :alt: A published Google Map
+
+    A Google Map of the Public Square offices in Cleveland (where we're located!)
 
 Field Reference
 ---------------
@@ -19,18 +26,14 @@ Fields and purposes:
 * **Advanced Settings** - Add custom CSS classes or a CSS ID to style the block with your custom CSS
 
 .. note::
-    Google Place IDs and Zoom both require a Google API Key. 
+    Google Place IDs and Zoom both require a Google API Key.
     Read more about `Google Maps API Keys <https://developers.google.com/maps/documentation/javascript/get-api-key>`_ .
 
-.. figure:: img/googlemap_settings.png
-    :alt: Our Google Map settings for Public Square, Cleveland, OH
-
-    Our Google Map settings for Public Square, Cleveland, OH
+.. figure:: images/google_map_block.jpeg
+    :alt: Our Google Map settings for 55 Public Square, Cleveland, OH
 
-.. figure:: img/googlemap_published.png
-    :alt: A published Google Map
+    Our Google Map settings for 55 Public Square, Cleveland, OH
 
-    A Google Map of the Public Square offices in Cleveland (where we're located!)
 
 
 

docs/features/blocks/contentblocks/html.rst → docs/features/contentblocks/html.rst

@@ -9,9 +9,9 @@ Field Reference
 
 This block includes a space for adding your custom HTML. Only use this block when you want to add something
 that can't be added with any of the other blocks, or that is not as integral to the page function as what
-would need to be in a template instead.  
+would need to be in a template instead.
 
-.. figure:: img/blocks_html.png
+.. figure:: images/html_block.jpeg
     :alt: An HTML block with a little HTML.
 
-    A HTML block with some basic HTML.
+    A HTML block with some basic HTML.

docs/features/contentblocks/image.rst

@@ -0,0 +1,25 @@
+Image Block
+===========
+
+Allows the user to add and display an image.
+
+Example:
+    .. figure:: images/image_block_preview.jpeg
+        :alt: A web page with an image block.
+
+        A web page with an image block.
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Choose an Image** - Choose an image
+
+When you choose an image, a popup allows you to search for images that you have already uploaded, or you can upload
+a new image.
+
+.. figure:: images/image_block_selection_modal.jpeg
+    :alt: The image chooser for the image block
+
+    The image chooser for the image block

docs/features/contentblocks/imagegallery.rst

@@ -0,0 +1,63 @@
+Image Gallery Block
+===================
+
+Creates and displays a collage of images from a collection.
+Each image in the **Image gallery** is a link that will open a larger version of the image.
+
+Example:
+    .. figure:: images/image_gal_example.jpeg
+        :alt: A web page with an image gallery block.
+
+        A web page with an image gallery block.
+
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Collection** - Choose the image collection to display as a Gallery
+
+The default collection is ``ROOT`` which will choose all of the images on the site. You can, however, create custom
+image collections.
+
+How To Create A Collection
+--------------------------
+
+1. Go to **Settings > Collections**.
+
+2. Click the **Add a Collection** button on the top right-hand corner.
+
+3. Name the collection and click create. (This one is called "Pixabay Images")
+
+.. figure:: images/image_gal_add_collection.jpeg
+
+4. Go to **Images** and click on each image that you want to add to the collection. (We chose all the images we used from `Pixabay <https://pixabay.com/>`_ in the tutorial)
+
+.. figure:: images/image_gal_selected.jpeg
+
+5. Choose **Add to collection** at the bottom of the browser window.  This will redirect you to another page.
+
+6. Choose the collection.
+
+.. figure:: images/image_gal_choose_collection.jpeg
+
+7. Select **Yes, add**.
+
+Once you have created a Collection, it will become available in the Image Gallery block.
+
+.. figure:: images/image_gal_block.jpeg
+    :alt: Our collection choice for the image gallery block
+
+    Our collection choice for the image gallery block
+
+The images will display in a row. When the image is clicked on, it will become a popup image for better viewing.
+
+.. figure:: images/image_gal_preview.jpeg
+    :alt: Our published image gallery
+
+    Our published image gallery
+
+Now you can click on any of the images and it will bring up a large version.
+
+.. figure:: images/image_gal_user_selected.jpeg

docs/features/blocks/contentblocks/imagelink.rst → docs/features/contentblocks/imagelink.rst

@@ -4,6 +4,9 @@ Image Link
 The image link block renders an image as an HTML anchor. This can be used to
 link to pages, documents, or external links.
 
+Example: This looks the same as an image, however a user can
+click on it to invoke an action.  The cursor changes when you hover on it to indicate it's clickable.
+
 
 Field Reference
 ---------------
@@ -15,3 +18,9 @@ Fields and purposes:
 * **Image** - The image to be shown as the content of the anchor.
 
 * **Alt text** - Alternate text to show to search engines and screen readers.
+
+
+.. figure:: images/image_link_editor.jpeg
+    :alt: the image link editor
+
+    the image link editor