CMS Blocks Documentation (#363)

Co-authored-by: Roxanna Coldiron <roxanna@coderedcorp.com>

docs/features/blocks/contentblocks/card.rst

@@ -0,0 +1,26 @@
+Card Block
+==========
+
+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; 
+    this Card Block only displays a single card.
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Image** - Select the image to display in the card
+
+* **Title** - The text to show for the title of the card
+
+* **Subtitle** - The text to show for a subtitle, if desired
+
+* **Body** - The text to show for the body of the card
+
+* **Links > Button Link** - The button link to include at the bottom of the card, set to link to a page or external link
+
+Explore `Bootstrap Cards <https://getbootstrap.com/docs/4.0/components/card/>`_ to get an understanding of the
+appearance and function of cards. 

docs/features/blocks/contentblocks/carousel.rst

@@ -0,0 +1,32 @@
+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/download.rst

@@ -0,0 +1,37 @@
+Download Block
+==============
+
+The download block enables users to add documents to the CMS which website 
+visitors can download from the site.
+
+Field Reference
+---------------
+
+* **Button Title** - The text to show on the button. You can insert simple HTML
+  here as well, such as ``Learn <b>More</b>``.
+
+* **Button Style** - The appearance of the button. This is a choice loaded from
+  ``CODERED_FRONTEND_BTN_STYLE_CHOICES`` Django setting and is inserted as a
+  CSS class in the HTML.
+
+* **Button Size** - The size of button. This is a choice loaded from
+  ``CODERED_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 
+
+.. figure:: img/blocks_download.png
+    :alt: A download block and its settings.
+
+    A download block and its settings.
+
+.. figure:: img/blocks_choose_doc.png
+    :alt: Choosing the document 
+
+    The popup for choosing which document you want to upload to the block for download by users
+
+When a website visitor clicks the button, the document is available for download in a new window. 

docs/features/blocks/contentblocks/embedmedia.rst

@@ -0,0 +1,31 @@
+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.
+
+Field Reference
+---------------
+
+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>`_ .
+
+* **Advanced Settings** - Add custom CSS classes or a CSS ID to style the embed with your custom CSS 
+
+.. figure:: img/embedmedia1.png
+    :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. 

docs/features/blocks/contentblocks/googlemap.rst

@@ -0,0 +1,36 @@
+Google Map Block
+================
+
+Allows the user to add a Google Map location and display the location on the map. 
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Search Query** - Address or search term used to find your location on the map.
+
+* **Map Title** - Map title for screen readers, ex: "Map to Simple Sweet Desserts"
+
+* **Google Place ID** - Place IDs uniquely identify a place in the Google Places database and on Google Maps
+
+* **Map Zoom Level** - Requires API key to use zoom. ex: 1: World, 5: Landmass/continent, 10: City, 15: Streets, 20: Buildings
+
+* **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. 
+    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:: img/googlemap_published.png
+    :alt: A published Google Map
+
+    A Google Map of the Public Square offices in Cleveland (where we're located!)
+
+
+

docs/features/blocks/contentblocks/html.rst

@@ -0,0 +1,17 @@
+HTML Block
+==========
+
+The HTML block allows you to add HTML to your page inside of the CMS. This is useful for small bits of
+code that you may want to add without needing to build a custom template or override one that you are using.
+
+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.  
+
+.. figure:: img/blocks_html.png
+    :alt: An HTML block with a little HTML.
+
+    A HTML block with some basic HTML.

docs/features/blocks/contentblocks/image.rst

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,43 @@
+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/contentblocks/index.rst

@@ -0,0 +1,29 @@
+.. _content-blocks:
+
+Content Blocks
+==============
+
+Content blocks are the blocks for adding various types of content to your site.
+
+.. toctree::
+    :maxdepth: 1
+
+    button
+    card
+    carousel
+    download
+    embedmedia
+    googlemap
+    html
+    image
+    imagegallery
+    imagelink
+    latestpages
+    modal
+    pagepreview
+    pricelist
+    reusablecontent
+    quote
+    table
+    text
+    

docs/features/blocks/contentblocks/latestpages.rst

@@ -0,0 +1,32 @@
+Latest Pages Block
+==================
+
+Creates a list of the most recently published pages with a specified length. 
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Parent Page** - Shows a preview of pages that are children of the selected page. Uses ordering specified in the page’s LAYOUT tab.
+
+* **Classified By** - Filters which pages are displayed by the classifier that you selected
+
+* **Show Body Preview** - If selected, shows a preview of what the page contains 
+
+* **Number of Pages to Show** - Limits how many pages are displayed to the number that you selected
+
+.. note::
+    There are also a few built-in templates available for this block under the **Advanced Settings** section.
+
+The pages are displayed as links with a line or so of text if the preview option is selected.
+
+.. figure:: img/latestpages1.png
+    :alt: The Latest Pages block and its settings
+
+    The Latest Pages block and its settings
+
+.. figure:: img/latestpages2.png
+    :alt: The Latest Pages block as displayed on the website
+
+    The Latest Pages block as displayed on the website

docs/features/blocks/contentblocks/modal.rst

@@ -0,0 +1,33 @@
+Modal Block
+===========
+
+Creates a popup box with a header, footer, and the ability to display the body as a block. 
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Button Title** - The text to show on the button. You can insert simple HTML
+  here as well, such as ``Learn <b>More</b>``.
+
+* **Button Style** - The appearance of the button. This is a choice loaded from
+  ``CODERED_FRONTEND_BTN_STYLE_CHOICES`` Django setting and is inserted as a
+  CSS class in the HTML.
+
+* **Button Size** - The size of button. This is a choice loaded from
+  ``CODERED_FRONTEND_BTN_SIZE_CHOICES`` Django setting and is inserted as a CSS
+  class in the HTML.
+
+* **Modal Heading** - The heading, or title, that will display on the modal
+
+* **Content** - Choose from other content blocks for the body of the modal.
+
+* **Modal Footer** - Choose a Simple Text footer or a button link
+
+Once it is published, website visitors can click the button to see the popup message. 
+
+.. figure:: img/cupcake_modal_sample.png
+    :alt: Our cupcake modal
+
+    Our cupcake modal as it appears on the page

docs/features/blocks/contentblocks/pagepreview.rst

@@ -0,0 +1,19 @@
+Page Preview Block
+==================
+
+Shows a preview of a selected Page
+
+Field Reference
+---------------
+
+There is only one field.
+
+**Page to Preview** - Select the page that you want to display a preview
+
+.. figure:: img/pagepreview_edit.png
+    :alt: A Page Preview block and its settings
+
+    A Page Preview block and its settings
+
+It looks very similar in design to the Latest Pages block but only displays the one selected page.
+It shows a link to the page and a few lines of preview text.

docs/features/blocks/contentblocks/pricelist.rst

@@ -0,0 +1,26 @@
+Price List Block
+================
+
+Creates a price list with the name of the items and their prices
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Heading** - The heading (or title) for the price list
+
+* **Items** - The item builder for the price list
+
+* **Image** - The image chooser for a Price List Item
+
+* **Name** - The name of the Price List Item
+
+* **Description** - The description of the Price List Item
+
+* **Price** - The price for the Price List Item as text (add currency symbols as desired)
+
+.. figure:: img/pricelist_sample.png
+    :alt: Our published price list
+
+    Our published price list

docs/features/blocks/contentblocks/quote.rst

@@ -0,0 +1,25 @@
+Quote Block
+===========
+
+Allows the user to enter a quote and an author. 
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Quote Text** - The text for the quote
+
+* **Author** - The author of the quote
+
+* **Advanced Settings** - Add custom CSS classes or a CSS ID to style the block with your custom CSS
+
+.. figure:: img/quoteblock.png
+    :alt: A quote block and its settings.
+
+    A quote block and its settings.
+
+.. figure:: img/quote_published.png
+    :alt: A published quote.
+
+    A published quote.

docs/features/blocks/contentblocks/reusablecontent.rst

@@ -0,0 +1,24 @@
+Reusable Content Block
+======================
+
+Allows the use of reusable content snippets on any page 
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Content** - Chooser for reusable content
+
+.. figure:: img/reusable_content_block.png
+    :alt: The reusable content block
+
+    The reusuable content block in page editor
+
+Reusable Content is created in **Snippets >** :ref:`reusable-content`. Once you have created a block of reusable content,
+you can choose it for any page on your site with the Reusable Content Block.
+
+Reusable content could be anything that you want to reuse across the site. It has layout blocks and content blocks,
+which allows you to make anything from a hero block to a responsive grid row with columns and custom content. 
+The benefit is that if you use a particular style on various pages throughout your website, you only need to create it once -- 
+**Then you can add it via the Reusable Content Block!**

docs/features/blocks/contentblocks/table.rst

@@ -0,0 +1,31 @@
+Table Block
+===========
+
+Allows the user to create a table with row and column headers. 
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Row Header** - If selected, displays the first row in the table as a header
+
+* **Column Header** - If selected, displays the first column in the table as a header
+
+* **Table Caption** - A heading that identifies the overall topic of the table, and is useful for screen reader users
+
+* **Table Content** - A visual table for adding Content
+
+* **Advanced Settings** - Add custom CSS classes or a CSS ID to style the block with your custom CSS 
+
+The default table block is only 3 x 3, as shown here.
+
+.. figure:: img/blocks_table_edit.png
+    :alt: A table block and its settings.
+
+    A table block and its settings.
+
+.. figure:: img/table_published.png
+    :alt: A published table
+
+    A published table

docs/features/blocks/contentblocks/text.rst

@@ -0,0 +1,27 @@
+Text Block
+==========
+
+The text block allows the user to create formatted text with headers, lists, links, and media. 
+
+Field Reference
+---------------
+
+The text block does not have specific fields. It has a space for writing content with formatting options
+in the format bar, such as:
+
+* bold or italic -- font style formatting
+
+* H2, H3, H4 -- titles and subtitles
+
+* numbered list or bullet list
+
+* horizontal line or line break
+
+* embed, link, document, or image -- media content that can be embedded in the block
+
+* undo and redo -- helpful in case you make a mistake or change your mind while writing 
+
+.. figure:: img/textblock.png
+    :alt: A text block with some text.
+
+    A text block with some text.

docs/features/blocks/index.rst

@@ -7,7 +7,7 @@ Blocks
     time before the project reaches an stable 1.0 release.
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
-    button
-    imagelink
+    contentblocks/index
+    layoutblocks/index

docs/features/blocks/layoutblocks/cardgrid.rst

@@ -0,0 +1,35 @@
+.. _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/blocks/layoutblocks/column.rst

@@ -0,0 +1,25 @@
+.. _column-block:
+
+Column Block
+============
+
+Creates columns in the layout
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Column Size** - Sets the size of the columns
+
+* **Content** - Options for the content blocks to display in the columns
+
+* **Advanced Settings** - Add custom CSS classes and IDs, select the breakpoint, and more
+
+Column Size can be set automatically by how many columns you have and the size of the content; however,
+you may want to choose which size to make your columns depending on your layout design. 
+
+Learn more about `Boostrap column sizing <https://getbootstrap.com/docs/4.0/layout/grid/>`_ 
+and `Boostrap breakpoints <https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints>`_.
+
+SEE ALSO: :ref:`content-blocks`

docs/features/blocks/layoutblocks/hero.rst

@@ -0,0 +1,35 @@
+Hero Block
+==========
+
+A banner block with an image and some text, if desired.
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Full Width** - If selected, sets whether the hero spans the entire width of the screen
+
+* **Parallax Effect** - If selected, background images scroll slower than foreground images, creating an illusion of depth.
+
+* **Background Image** - Image chooser for the background image
+
+* **Tile Background** - If selected, background image will be repeated in a tile pattern
+
+* **Background Color** - Sets a background color to display with hexadecimal, RGBA, or CSS color notation (e.g. #ff0011)
+
+* **Text Color** - Sets the color of the text for the entire hero block
+
+* **Content** - Additional layout options such as a Responsive Grid Row, Card Grid, or HTML
+
+.. note::
+    If you want to use a hero block in place of the title/cover image on the web page, click on the LAYOUT tab
+    in the editor and under Visual Design, choose the "Web page without title and cover image" template.
+
+In the **Advanced Settings** you can add CSS classes. In our hero below, we added the Bootstrap class ``py-5`` to give
+the hero image more padding and show more of the image. We also selected the focal point in the Image Editor.
+
+.. figure:: img/hero_block.png 
+    :alt: Hero block published on the page
+
+    Our published hero block with padding

docs/features/blocks/layoutblocks/index.rst

@@ -0,0 +1,12 @@
+Layout Blocks
+==============
+
+Layout blocks are the blocks for building your site in the CMS.
+
+.. toctree::
+    :maxdepth: 1
+
+    cardgrid
+    column
+    hero
+    responsivegridrow

docs/features/blocks/layoutblocks/responsivegridrow.rst

@@ -0,0 +1,23 @@
+Responsive Grid Row Block
+=========================
+
+A block that creates a responsive grid row to hold and organize site content
+
+Field Reference
+---------------
+
+Fields and purposes:
+
+* **Full Width** - If selected, sets whether the row spans the entire width of the screen
+
+* **Content** - Starts with a Column (required) with content block choices
+
+You can add as many columns as you would like; however, a responsive grid row requires at least one column with
+at least one piece of content. 
+
+.. figure:: img/responsive_grid_row1.png
+    :alt: A responsive grid row block
+
+    A responsive grid row block ready to add some content
+
+SEE ALSO: :ref:`column-block`, :ref:`content-blocks`

docs/features/snippets/reusable_content.rst

@@ -1,3 +1,5 @@
+.. _reusable-content:
+
 Reusable Content
 ================