Documenting page types and snippets (#181)

Adds more documentation per issue #3

docs/features/index.rst

@@ -5,7 +5,7 @@ Features
     :maxdepth: 1
 
     classifiers
-    events
     import_export
     mailchimp
-    store_locator
+    page_types/index
+    snippets/index

docs/features/page_types/article_pages.rst

@@ -0,0 +1,33 @@
+Article Pages
+=============
+
+Create a blog
+
+Usage
+-----
+
+First start by creating an "Article Landing Page" and then add any number of "Article Page"s as children of the "Article Landing Page".  Each child page here represents an individual article.  Add content to these pages as you would for a normal "Web Page".
+
+
+Article Landing Page
+--------------------
+
+Layout Tab
+~~~~~~~~~~
+
+* **Show Images**:  If toggled on, this landing page will show the cover images for its children articles.
+* **Show Captions**: If toggled on, this landing page will show the captions for its children articles.
+* **Show Author and Date Info**: If toggled on, this landing page will show the captions for its children articles.
+* **Show Preview Text**: If toggled on, this landing page will show a preview of its childrens content.
+
+
+Article Page
+------------
+
+Content Tab
+~~~~~~~~~~~
+
+* **Caption**: The caption you want to be displayed under your article's title.
+* **Author**: The user you want to tie the article to.
+* **Display Author As**: The name you want the author to appear as.  This will default to the author's name if not defined.
+* **Display Publish Date**: The publish date you want to be shown on your article.  This is separate from the actual publish date which is determined when the page is published.

docs/features/events.rst → docs/features/page_types/event_pages.rst

@@ -1,36 +1,40 @@
-Events
-=============
+Event Pages
+===========
 
 Create a calendar or list of events. Visitors can download ical invitations to their own calendars
 for each event, recurring events, or all events.
 
-
 Usage
 -----
 
-If events are implemented on your site (see instructions below), first start by creating an
-"Event Landing Page" (may be named differently on your specific website). Add content to this
-page as usual. Under the **Layout** tab, you can choose a few options:
+First start by creating an "Event Landing Page" and then add any number of "Event Page"s as children of the "Event Landing Page". Each child page here represents an individual event. Events can be one time, or recurring, similar to Outlook or other calendar software. Add content to these pages as you would for a normal "Web Page".
+
+Event Landing Page
+------------------
+
+Layout Tab
+~~~~~~~~~~
 
-* Show list of child pages: Check this box to show a list of all events.
-* Calendar style: There are several options here. Choose one that fits your needs.
+* **Show list of child pages**: Check this box to show a list of all events.
+* **Calendar style**: There are several options here. Choose one that fits your needs.
 
-Next, save the Event Landing Page. Now create a child page. Each child page here represents
-an individual event. Events can be one time, or recurring, similar to Outlook or other
-calendar software.
+Event Page
+----------
 
-When creating an event page, fill out the relevant information, and click the **+** icon next
-to "Dates and times" to add an event occurrence. You can create multiple occurrences, or set
-an occurrence to repeat.
+Content Tab
+~~~~~~~~~~~
 
+* **Calendar Color**: The color that the event will have on the calendar.
+* **Address**: The address for the event, if applicable.
+* **Occurrences**: This lets you add the date and time information for your event.  Click the **+** icon to add a new date and time rule.
 
-Implementation
---------------
+Developer Implementation
+------------------------
 
 The event functionality is built-in to CodeRed CMS but it is not enabled by default.
 
-There are two abstract pages when dealing with events.  The first ``CoderedEventPage`` holds
-the information regarding the event.  Dates, location, etc. all will fall under this page.  The
+There are two abstract pages available when dealing with events.  The first ``CoderedEventPage`` holds
+the information regarding an event.  Dates, location, etc. all will fall under this page.  The
 ``CoderedEventIndexPage`` will aggregate its children ``CoderedEventPage`` and display them in a
 calendar or list.
 

docs/features/page_types/form_pages.rst

@@ -0,0 +1,41 @@
+Form Pages
+==========
+
+Create a form that can be used to collect information from your users.
+
+Usage
+-----
+
+First start by creating a "Form" (may be named differently on your specific website). Add content to this page as you would for a normal Web Page. 
+
+Content Tab Options
+~~~~~~~~~~~~~~~~~~~
+
+* **Form Fields**: The data you want to collect on the form.  You can add as many fields as required ranging from all form input types like text, files, radio buttons, etc.
+
+**Form Settings**
+
+* **Thank You Page**: The page you want to redirect the user to after they successfully submit a form.
+* **Button Text**: The text you want on the form submit button
+* **Button Style**: The style you want on the form submit button.
+* **Button Size**: The size you want the form submit button.
+* **Button CSS Class**: Additional CSS classes you want to add to the button.
+* **Form CSS Class**: Additional CSS classes you want to add to the form.
+* **Form ID**: The HTML ID you want your Form to have.
+
+**Form Submissions**
+
+* **Save Form Submissions**: Toggles whether the form submissions are saved to your website's database.
+* **Email Form Submissions to**: The email address you want the info you collect from your form to be sent to.
+* **Reply-to Address**: The reply-to address you want the email to contain.
+* **Subject**: The subject you want the email to use.
+
+**Confirmation Emails**
+
+Click the "Add Confirmation Emails" button to add additional emails you want to sent out when a form is submitted.
+
+Settings Tab Options
+~~~~~~~~~~~~~~~~~~~~
+
+* **Form go live date/time**: The optional date/time the form will start appearing on the page.
+* **Form expiry date/time**: The optional date/time the form will stop appearing on the page.

docs/features/page_types/index.rst

@@ -0,0 +1,43 @@
+Page Types
+==========
+
+.. toctree::
+    :maxdepth: 1
+
+    article_pages
+    event_pages
+    form_pages
+    location_pages
+    web_pages
+
+
+Design Philosophy
+-----------------
+
+Pages for your CodeRed CMS site use a "Parent-Child" relationship.  A parent page is any page that is an ancestor of other pages in the site's tree structure.  A child page is any page that is a descendant of another page in the site's tree structure.  A lot of specific site functionality is broken up into these "Parent-Child" relationships.  For example, if you want to add a blog to your site, you would add an "Article Landing Page", which would have your "Article Page"s as descendants.  
+
+.. note::
+    
+    | A site's page struture could look like the following:
+
+        Home Page -> Article Landing Page -> Article Page
+    
+    In this example, Home Page is a direct ancestor/parent of Article Landing Page.  Article Landing Page is a direct descendant/child of Home Page.  Article Landing Page is also a direct ancestor/parent of Article Page.  Article Page is a direct descendant/child of Article Landing Page.
+
+Below is a table of the current possible "Parent-Child" relationships.
+
+===================== ====================================================================================
+Parent Page Type      Child Page Types
+===================== ====================================================================================
+Web Page              Web Page, Article Landing Page, Event Landing Page, Location Landing Page, Form Page
+Article Landing Page  Article Page
+Event Landing Page    Event Page
+Location Landing Page Location Page
+===================== ====================================================================================
+
+To add a new child page to any existing page, navigate to that page in the admin and click on the "Add Child Page" button.
+
+Development Philosophy
+----------------------
+
+When it comes to pages on the site, we strive to keep all the core functionality in Abstract models.  When you create a new CodeRed CMS project, your generated app will come pre-loaded with Concrete implementations of some of these Abstract models.  These concrete models are yours to modify as needed.  But do be advised that changing built in functionality could have untested consequences.  By keeping the core page functionality abstract, migrations are easier to deal with on a per project basis.

docs/features/page_types/location_pages.rst

@@ -0,0 +1,93 @@
+Location Pages
+===================
+
+Create location pages for individual locations. These could be stores, distributors, facilities, etc. Placing these location pages under a location landing page aggregates them using an interactive Google Map.
+
+Usage
+-----
+
+First start by creating a "Location Landing Page" and then add any number of "Location Page"s as children of the "Location Landing Page". Each child page here represents a location that will have its own page and show up in its parent Google map.  Add content to this page as you would for a normal Web Page.
+
+Location Landing Page
+---------------------
+
+Layout Tab
+~~~~~~~~~~
+
+* **Center Latitude**: The latitude you want the Google map to center on.
+* **Center Longitude**: The longitude you want the Google map to center on.
+* **Zoom**: The zoom level you want the Google map to default to.  This requires an API key to use zoom. The zoom values can be between 1-20.  1: World, 5: Landmass continent, 10: City, 15: Streets, 20: Buildings
+
+Next, save the Location Landing Page. Now create a child "Location Page" under your new "Location Landing Page". 
+
+
+Location Page
+-------------
+
+Content Tab
+~~~~~~~~~~~
+
+* **Address**: The address of the location.
+* **Website**: The website for the location, if applicable.
+* **Phone Number**: The phone number of the location, if applicable.
+
+Layout Tab
+~~~~~~~~~~
+
+* **Map Title**: A custom title that will be used for this location's Google map pin.  It will default to the page's normal title if not provided.
+* **Map Description**: A custom description that will be used for this location's Google map pin.
+
+Settings Tab
+~~~~~~~~~~~~
+
+* **Auto Update Latitude and Longitude**: If checked, the latitude and longitude will be calculated whenever the page is saved based off of the provided address.
+* **Latitude**: The latitude that you want this location's Google map pin to be set as.
+* **Longitude**: The longitude that you want this location's Google map pin to be set as.
+
+
+Implementation
+--------------
+
+The store locator is built-in to CodeRed CMS but is not enabled by default. To implement, add
+the following to your ``website/models.py``::
+
+    from coderedcms.models import CoderedLocationIndexPage, CoderedLocationPage
+
+
+    class LocationPage(CoderedLocationPage):
+        """
+        A page that holds a location.  This could be a store, a restaurant, etc.
+        """
+        class Meta:
+            verbose_name = 'Location Page'
+
+        template = 'coderedcms/pages/location_page.html'
+
+        # Only allow LocationIndexPages above this page.
+        parent_page_types = ['website.LocationIndexPage']
+
+
+    class LocationIndexPage(CoderedLocationIndexPage):
+        """
+        A page that holds a list of locations and displays them with a Google Map.
+        This does require a Google Maps API Key that can be defined in Settings > Google API Settings
+        """
+        class Meta:
+            verbose_name = 'Location Landing Page'
+
+        # Override to specify custom index ordering choice/default.
+        index_query_pagemodel = 'website.LocationPage'
+
+        # Only allow LocationPages beneath this page.
+        subpage_types = ['website.LocationPage']
+
+        template = 'coderedcms/pages/location_index_page.html'
+
+Next run ``python manage.py makemigrations website`` and ``python manage.py migrate`` to create
+the new pages in your project.
+
+Now when going to the wagtail admin, you can create a Location Index Page, and child Location Pages.
+Also be sure to add a Google Maps API key under Settings > Google API Settings.
+
+.. note::
+    Before creating or importing location pages, add your Google API key for automatic geolocation.

docs/features/page_types/web_pages.rst

@@ -0,0 +1,63 @@
+Web Pages
+===================
+
+The standard page for your website.  All other page types on the site will share the functionality of this page type.
+
+Usage
+-----
+
+First start by creating a "Web Page".  Each page on your site will have an assortment of tabs that house different types of data/content for that page.
+
+Tabs
+----
+
+In the Wagtail admin, we break up all the fields on a page into seperate tabs to help with readability and to group similar functionality together.  Listed below are the available tabs, what they do, and what fields you can expect to be shown in them.
+
+Content Tab
+~~~~~~~~~~~
+
+The **Content** tab is meant to house all data fields related to the page's content.  You have the following options:
+
+* **Title**: The name of the page.
+* **Cover Image**: The big hero image you want for the page.
+* **Body**: The field your content will live.  This uses a StreamField to allow you to dynamically create a page layout and content.
+
+Classify Tab
+~~~~~~~~~~~~
+
+The **Classify** tab is meant to house all data fields related to the page's classification.  You have the following options:
+
+* **Classifier Terms**: The taxonomies you want assigned to this page.  These taxonomies can be used for certain blocks to control what pages are related to a certain block.  These taxonomies are defined in the Snippets section of the admin.
+* **Tags**: An optional tagging mechanism that can be used by a developer for any reason.
+
+Layout Tab
+~~~~~~~~~~
+
+The **Layout** tab is meant to house all data fields related to the page's layout.  You have the following options:
+
+* **Template**:  The template you want the page to use to render.
+* **Show List of Child Pages**: Toggles whether this parent page should show a list of its children pages.
+* **Number Per Page**: Controls how many children pages you want to show at once.
+* **Order Children Pages by**: Controls how the children pages are sorted on this parent page.
+* **Filter Child Pages by**: Using Classifier terms, control which children pages are shown on the parent page.
+
+SEO Tab
+~~~~~~~
+
+The **SEO** tab is meant to house all data fields related to the page's SEO  settings, like Open Graph tags and Google's structured data.  You have the following options:
+
+* **Slug**: The url path you want the page to exist on.  If not set, it will be automatically generated from this page's title.
+* **Page Title**: The title you want to be shown at the top of your web browser
+* **Search Description**: The description you want to be placed in your site's meta tags.
+* **Open Graph preview image**:  The image you want your site to show when someone shares this page on social media.
+
+* **Structured Data** - Organization: These are numerous fields to construct structured data that Google uses.  Fill this out on your home page and it will apply to all pages on your site.
+
+Settings Tab
+~~~~~~~~~~~~
+
+The **Settings** tab is meant to house different controls for the page rendering.  You have the following options:
+
+* **Go live date/time**: The date/time you want this page to be visible to visitors.
+* **Expiry date/time**: The date/time you want this page to become invisible to visitors.
+* **Content Walls**: This StreamField allows you to select Content Wall snippets that will be displayed to your users before they can access the page.  A common use case is a pop up showing them a limited offer.

docs/features/snippets/carousels.rst

@@ -0,0 +1,30 @@
+Carousels
+=========
+
+A representation of a carousel, slider or similar construct.
+
+Usage
+-----
+
+You define your carousels in the Snippets > Carousel section of the admin.  Once defined, any page with a body streamfield can show that carousel by selecting it with a carousel block.
+
+Fields
+------
+
+Slider
+~~~~~~
+**Name**: A unique name for your carousel.  It can be anything, it is just used as a personal reference to easily tell them apart.
+**Show Controls**: A toggle to determine if the carousel has arrows to control which slide shows.
+**Show Indicators**: A toggle to determine if the carousel will show dots at the bottom to indicate how many slides there are.
+**Animation**: Determines the type of animation that happens when a slide is transitioned.
+
+Slides
+~~~~~~
+
+To add a slide to your carousel, click the "Add Slides" button.
+
+**Image**: The background image you want to use for your slide.  This is optional.  It is recommended to at least set this field or the **Background color** field.
+**Background color**: The background color you want to use for your slide.  This is optional.  It is recommended to at lest set this field or the **Image** field.
+**Custom CSS class**: If you need to add a specific css class for this slide, add it here.
+**Custom ID**: If you need to add a specific ID for this slide, add it here.
+**Content**: A streamfield that contains the content blocks for the slide.

docs/features/snippets/content_walls.rst

@@ -0,0 +1,19 @@
+Content Walls
+=============
+
+A representation of a content wall, pop up, or similar construct.
+
+Usage
+-----
+
+You define your content walls in the Snippets > Carousel section of the admin.  Once defined, you can go to the Settings tab of any page and add any number of your content walls to the page.
+
+When a page is loaded, each content wall will pop up as a Bootstrap modal.
+
+Fields
+------
+
+**Name**: A unique name for your content wall.  It can be anything, it is just used as a personal reference to easily tell them apart.
+**Dismissible**: A toggle to determine if the content wall modal has a close button.
+**Show Once**: A toggle to determine if the content wall will show every time the user loads the page or just the first time.
+**Content**: A streamfield that contains the layout blocks for the content wall.

docs/features/snippets/footers.rst

@@ -0,0 +1,17 @@
+Footers
+=======
+
+A representation of a footer that sits at the bottom of your pages.
+
+Usage
+-----
+
+You define your content walls in the Snippets > Footer section of the admin.  Once defined, your footers will render on your page, stacked on top of each other.
+
+Fields
+------
+
+**Name**: A unique name for your footer.  It can be anything, it is just used as a personal reference to easily tell them apart.
+**Custom CSS class**: If you need to add a specific css class for this footer, add it here.
+**Custom ID**: If you need to add a specific ID for this footer, add it here.
+**Content**: A streamfield that contains the layout blocks for the content wall.

docs/features/snippets/index.rst

@@ -0,0 +1,14 @@
+Snippets
+========
+
+.. toctree::
+    :maxdepth: 1
+
+    carousels
+    classifiers
+    content_walls
+    footers
+    navigation_bars
+    reusable_content
+
+CodeRed CMS follows the Wagtail philosophy when it comes to snippets (viewable here<https://docs.wagtail.io/en/latest/topics/snippets.html>). 

docs/features/snippets/navigation_bars.rst

@@ -0,0 +1,38 @@
+Navigation Bars
+===============
+
+A representation of a navigation bar that sits at the top of your pages.
+
+Usage
+-----
+
+You define your content walls in the Snippets > Navigation Bars section of the admin.  Once defined, your navigation bars will render on your page, stacked on top of each other.
+
+Fields
+------
+
+**Name**: A unique name for your footer.  It can be anything, it is just used as a personal reference to easily tell them apart.
+**Custom CSS class**: If you need to add a specific css class for this footer, add it here.
+**Custom ID**: If you need to add a specific ID for this footer, add it here.
+**Navigation Links**: A list of links to use for the navigation bar.
+
+Navigation Links
+----------------
+
+Navigation links are a streamfield that allows you to craft different types of links in your navigation bar.  All of these link types have the following fields:
+**Display text**: The text you want to use for the link. This is not necessary if you're using an **Image** as the link.
+**Image**: The image you want to use for the link.  This is optional and only really used if you need some special image to be used as the link, something like a paypal donate button.
+**Sub-links**: Optional field to determine any dropdown links attached to this link.
+
+Page Link With Sub-Links
+~~~~~~~~~~~~~~~~~~~~~~~~
+**Page**: The page on your site that you want to link to.
+**Show child pages**: Toggle to determine whether this link should automatically generate a dropdown that lists the **Page** children.
+
+External Link With Sub-Links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**URL**: The URL you want to link to.
+
+Document Link With Sub-Links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Document**: The document you want to link to that will be downloaded.

docs/features/snippets/reusable_content.rst

@@ -0,0 +1,15 @@
+Reusable Content
+================
+
+A representation of content that you would like to repeat often on your pages.
+
+Usage
+-----
+
+You define your content walls in the Snippets > Resusable Content section of the admin.  Once defined, any page with a body streamfield can show the reusable content by selecting it with a reusuable content block.
+
+Fields
+------
+
+**Name**: A unique name for your footer.  It can be anything, it is just used as a personal reference to easily tell them apart.
+**Content**: A streamfield that contains the layout blocks for the resusable content.

docs/features/store_locator.rst

@@ -1,49 +0,0 @@
-Store Locator
-=============
-
-The store locator provides pages for individual locations. These could be stores, distributors,
-facilities, etc. An index page aggregates these location pages using an interactive Google Map.
-
-The store locator is built-in to CodeRed CMS but is not enabled by default. To implement, add
-the following to your ``website/models.py``::
-
-    from coderedcms.models import CoderedLocationIndexPage, CoderedLocationPage
-
-
-    class LocationPage(CoderedLocationPage):
-        """
-        A page that holds a location.  This could be a store, a restaurant, etc.
-        """
-        class Meta:
-            verbose_name = 'Location Page'
-
-        template = 'coderedcms/pages/location_page.html'
-
-        # Only allow LocationIndexPages above this page.
-        parent_page_types = ['website.LocationIndexPage']
-
-
-    class LocationIndexPage(CoderedLocationIndexPage):
-        """
-        A page that holds a list of locations and displays them with a Google Map.
-        This does require a Google Maps API Key that can be defined in Settings > Google API Settings
-        """
-        class Meta:
-            verbose_name = 'Location Landing Page'
-
-        # Override to specify custom index ordering choice/default.
-        index_query_pagemodel = 'website.LocationPage'
-
-        # Only allow LocationPages beneath this page.
-        subpage_types = ['website.LocationPage']
-
-        template = 'coderedcms/pages/location_index_page.html'
-
-Next run ``python manage.py makemigrations website`` and ``python manage.py migrate`` to create
-the new pages in your project.
-
-Now when going to the wagtail admin, you can create a Location Index Page, and child Location Pages.
-Also be sure to add a Google Maps API key under Settings > Google API Settings.
-
-.. note::
-    Before creating or importing location pages, add your Google API key for automatic geolocation.