Merge pull request #1440 from chrxr/master

Updating editors manual docs for Wagtail 1.0.

docs/README.md

@@ -2,7 +2,7 @@
 
 These are Sphinx docs, automatically built at http://docs.wagtail.io when the master branch is committed to Github. To build them locally, install Wagtail's development requirements (in the root Wagtail directory):
 
-    pip install requirements-dev.txt
+    pip install -r requirements-dev.txt
 
 To build the documentation for browsing, from this directory run: 
 

docs/editor_manual/documents_images_snippets/documents.rst

@@ -14,4 +14,7 @@ Documents such as PDFs can be managed from the Documents interface, available in
 
 * When editing a document you can replace the file associated with that document record. This means you can update documents without having to update the pages on which they are placed. Changing the file will change it on all pages that use the document.
 * Add or remove tags using the Tags field.
-* Save or delete documents using the buttons at the bottom of the interface. **NOTE:** deleted documents cannot be recovered.
+* Save or delete documents using the buttons at the bottom of the interface. 
+
+.. Warning:: 
+	Deleted documents cannot be recovered.

docs/editor_manual/documents_images_snippets/images.rst

@@ -5,9 +5,25 @@ If you want to edit, add or remove images from the CMS outside of the individual
 
 .. image:: ../../_static/images/screen31_images_page.png
 
-* Clicking an image will allow you to edit the data associated with it. This includes the Alt text, the photographers credit, the medium of the subject matter and much more. **NOTE:** changing the alt text here will alter it for all occurrences of the image in carousels, but not in inline images, where the alt text can be set separately.
+* Clicking an image will allow you to edit the data associated with it. This includes the Alt text, the photographers credit, the medium of the subject matter and much more. 
+
+.. Warning:: 
+	Changing the alt text here will alter it for all occurrences of the image in carousels, but not in inline images, where the alt text can be set separately.
 
 .. image:: ../../_static/images/screen32_image_edit_page.png
 
-* When editing an image you can replace the file associated with that image record. This means you can update images without having to update the pages on which they are placed. Changing the file will change it on all pages that use the image.
+Changing the image
+__________________
 
+* When editing an image you can replace the file associated with that image record. This means you can update images without having to update the pages on which they are placed. 
+
+.. Warning::
+	Changing the file will change it on all pages that use the image.
+
+Focal point
+___________
+
+* This interface allows you to select a focal point which can effect how your image displays to visitors on the front-end.
+* If your images are cropped in some way to make them fit to a specific shape, then the focal point will define the centre point from which the image is cropped.
+* To set the focal point, simply a marquee around the most important element of the image.
+* If the feature is set up in your website, then on the front-end you will see the crop of this image focusing on your selection.

docs/editor_manual/documents_images_snippets/snippets.rst

@@ -1,11 +1,38 @@
 Snippets
 ~~~~~~~~
 
-.. note::
-	Documentation currently incomplete and in draft status
+Snippets allow you to create elements on a website once and reuse them in multiple places. Then, if you want to change something on the snippet, you only need to change it once, and it will change across all the occurances of the snippet.
 
-.. UNSURE HOW TO WRITE THIS AS THE ADVERT EXAMPLE IN WAGTAIL DEMO IS NOT A PARTICULARLY HELPFUL USE CASE. 
+How snippets are used can vary widely between websites. Here are a few examples of things Torchbox have used snippets for on our clients websites:
 
-When creating a page on a website, it is a common occurrence to want to add in a piece of content that already exists on another page. An example of this would be a person's contact details, or an advert that you want to simply show on every page of your site, without having to manually apply it.
+* For staff contact details, so that they can be added to many pages but managed in one place
+* For Adverts, either to be applied sitewide or on individual pages
+* To manage links in a global area of the site, for example in the footer
+* For Calls to Action, such as Newsletter signup blocks, that may be consistent across many different pages
 
-Wagtail makes this easy with Snippets. 
+The Snippets menu
+-----------------
+
+.. image:: ../../_static/images/screen33_snippet_menu.png
+
+* You can access the Snippets menu by clicking on the 'Snippets' link in the left-hand menu bar.
+* To add or edit a snippet, click on the snippet type you are interested in (often help text will be included to help you in selecting the right type)
+* Click on an individual snippet to edit, or click 'Add ...' in the top right to add a new snippet
+
+.. Warning::
+	Editing a snippet will change it on all of the pages on which it has been used. In the top-right of the Snippet edit screen you will see a label saying how many times the snippet has been used. Clicking this label will display a listing of all of these pages.
+
+.. image:: ../../_static/images/screen34_snippet_used_times.png
+
+Adding snippets whilst editing a page
+-------------------------------------
+
+If you are editing a page, and you find yourself in need of a new snippet, do not fear! You can create a new one without leaving the page you are editing:
+
+* Whilst editing the page, open the snippets interface in a new tab, either by Ctrl+click (cmd+click on Mac) or by right clicking it and selecting 'Open in new tab' from the resulting menu.
+* Add the snippet in this new tab as you normally would.
+* Return to your existing tab and reopen the Snippet chooser window.
+* You should now see your new snippet, even though you didn't leave the edit page.
+
+.. Note::
+	Even though this is possible, it is worth saving your page as a draft as often as possible, to avoid your changes being lost by navigating away from the edit page accidentally.

docs/editor_manual/new_pages/creating_body_content.rst

@@ -1,13 +1,39 @@
 Creating page body content
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The majority of the body content within a page will be created within text fields.
+Wagtail supports a number of basic fields for creating content, as well as our unique StreamField feature which allows you to construct complex layouts by combining these basic fields in any order.
 
-There are two types of text entry fields you will see when creating a page. Some, like *Page title* are basic text fields come with no formatting options. This is because all titles display the same across a single page type. Others, *Body* for example, require more formatting, and so a set of tools are provided for this purpose. These are referred to as rich text fields. 
+===========
+StreamField
+===========
 
-So, when you click into certain fields, for example the *Body* field, you will be presented with a set of tools which allow you to format and style your text. These tools also allow you to insert links, images, videos clips and links to documents.
+StreamField allows you to create complex layouts of content on a page by combining a number of different arrangements of content, 'blocks', in any order.
 
-.. image:: ../../_static/images/screen11_rich_text_field.png
+.. image:: ../../_static/images/screen11_empty_streamfield.png
+
+When you first edit a page, you will be presented with the empty StreamField area, with the option to choose one of several block types. The block types on your website may be different from the screenshot here, but the principles are the same.
+
+Click the block type, and the options will disappear, revealing the entry field for that block.
+
+Depending on the block you chose, the field will display differently, and there might even be more than one field! There are a few common field types though that we will talk about here.
+
+* Basic text field
+* Rich text field
+* Image field
+
+Basic text field
+================
+
+Basic text fields have no formatting options. How these display will be determined by the style of the page in which they are being inserted. Just click into the field and type!
+
+Rich text fields
+================
+
+Most of the time though, you need formatting options to create beautiful looking pages. So some fields, like the fields in the 'Paragraph block' shown in the screenshot, have many of the options you would expect from a word processor. These are referred to as rich text fields. 
+
+So, when you click into one of these fields, you will be presented with a set of tools which allow you to format and style your text. These tools also allow you to insert links, images, videos clips and links to documents.
+
+.. image:: ../../_static/images/screen11.1.5_streamfield_richtext.png
 
 Below is a summary of what the different buttons represent:
 
@@ -37,4 +63,25 @@ Below is a summary of what the different buttons represent:
 
 .. image:: ../../_static/images/screen11.7_links_docs.png
 
-**Insert link / document:** Allows you to insert a link or a document into the rich text field. See Inserting links and Inserting documents for more details. See `Inserting links section <inserting_links.html>`.
+**Insert link / document:** Allows you to insert a link or a document into the rich text field. See Inserting links and Inserting documents for more details. See `Inserting links section <inserting_links.html>`.
+
+Adding further blocks in StreamField
+==============================================
+
+.. image:: ../../_static/images/screen11.8_adding_new_blocks.png
+
+* To add new blocks, click the '+' icons above or below the existing blocks.
+* You'll then be presented once again with the different blocks from which you may choose.
+* You can cancel the addition of a new block by clicking the cross at the top of the block selection interface.
+
+Reordering and deleting content in StreamField
+==============================================
+
+.. image:: ../../_static/images/screen11.9_streamfield_reordering.png
+
+* Click the arrows on the right-hand side of each block to move blocks up and down in the StreamField order of content.
+* The blocks will be displayed in the front-end in the order that they are placed in this interface.
+* Click the rubbish bin on the far right to delete a field
+
+.. Warning::
+	Once a StreamField field is deleted it cannot be retrieved if the page has not been saved. Save your pages regularly so that if you acidentally delete a field you can reload the page to undo your latest edit.

docs/editor_manual/new_pages/inserting_documents.rst

@@ -3,7 +3,7 @@ Inserting links to documents into body text
 
 .. image:: ../../_static/images/screen27_docs_icon.png
 
-It is possible to insert links to documents held in the CMS into the body text of a web page by clicking the button above in the Body field.
+It is possible to insert links to documents held in the CMS into the body text of a web page by clicking the button above in the rich text field.
 
 The process for doing this is the same as when inserting an image. You are given the choice of either choosing a document from the CMS, or uploading a new document.
 

docs/editor_manual/new_pages/inserting_images.rst

@@ -1,28 +1,16 @@
 Inserting images and videos in a page
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There will obviously be many instances in which you will want to add images to a page. There may be multiple ways in which to add an image to a page, depending on the setup of the site that you work on. For example, the Wagtail demo standard page type has two ways to insert images.
+There will obviously be many instances in which you will want to add images to a page. There are two main ways to add images to pages, either via a specific image chooser field, or via the rich text field image button. Which of these you use will be dependent on the individual setup of your site.
 
-* In the main carousel, or…
-* Within the body of the page
+Inserting images using the image chooser field
+______________________________________________
 
-Inserting images into the carousel
-__________________________________
+Often a specific image field will be used for a main image on a page, or for an image to be used when sharing the page on social media. For the standard page on Torchbox.com, the former is used.
 
-The carousel is where the main, featured images and videos associated with a page should be displayed.
+.. image:: ../../_static/images/screen14_add_main_image.png
 
-.. image:: ../../_static/images/screen14_add_carousel_button.png
-
-* To insert a carousel item click the Add carousel content link in the Carousel content section.
-
-.. image:: ../../_static/images/screen15_carousel_form.png
-
-* You can then insert an image by clicking the *Choose an image* button.
-* It is also possible to add videos to a carousel. Simply copy and paste the web address for the video (either YouTube or Vimeo) into the *Embed URL* field and click Insert. A poster image for the video can also be uploaded or selected from the CMS. This is the image displayed before a user has clicked play on the video.
-* The *Caption* field allows you to enter a caption to be displayed with your image. This caption also acts as the 'Alternative text' or Alt text for your image. This is a small piece of invisible code that is used by screen readers that enable visually impaired users to hear a description of the image.
-* The external link field allows you to enter a web address for pages not within your website.
-* Or you can select an internal page using the page chooser (see below for info on the page chooser).
-* You can add more items into the same carousel by clicking the Add carousel content link again. Please see Adding multiple items section below for help with removing or ordering carousel items.
+* You insert an image by clicking the *Choose an image* button.
 
 Choosing an image to insert
 ___________________________
@@ -53,20 +41,24 @@ The image below demonstrates finding and  inserting an image that is already pre
 #. This *Tags* allows you to associate tags with the image you are uploading. This allows them to be more easily found when searching. Each tag should be separated by a space. Good practice for creating multiple word tags is to use an underscore between each word (e.g. western_yellow_wagtail).
 #. Click *Upload* to insert the uploaded image into the carousel. The image will also be added to the main CMS image library for reuse in other content.
 
-Inserting images into the body text
-___________________________________
+Inserting images using the rich text field
+__________________________________________
 
-Images can also be inserted into the body text of a page. When editing the Body field of a standard page, click the image illustrated above. You will then be presented with the same options as for inserting images into the main carousel.
+.. image:: ../../_static/images/screen11.6.5_images.png
 
-In addition, the Wagtail Demo site allows you to chose an alignment for you image.
+Images can also be inserted into the body text of a page via the rich text editor. When working in a rich text field, click the image illustrated above. You will then be presented with the same options as for inserting images into the main carousel.
+
+In addition, Wagtail allows you to chose an alignment for you image.
 
 .. image:: ../../_static/images/screen18_image_alignment.png
 
 #. You can select how the image is displayed by selecting one of the format options.
-#. In the Wagtail Demo site, images inserted into the body text do not have embedded captions (these should be added as regular body text). However you must still provide specific alt text for your image.
+#. You must provide specific alt text for your image.
 
 The alignments available are described below:
 
 * **Full width:** Image will be inserted using the full width of the text area.
 * **Half-width left/right aligned:** Inserts the image at half the width of the text area. If inserted in a block of text the text will wrap around the image. If two half-width images are inserted together they will display next to each other.
 
+.. Note::
+	The display of images aligned in this way is dependent on your implementation of Wagtail, so you may get slightly different results.

docs/editor_manual/new_pages/the_promote_tab.rst

@@ -3,14 +3,14 @@ The Promote tab
 
 A common feature of the *Edit* pages for all page types is the two tabs at the top of the screen. The first, Content, is where you build the content of the page itself.
 
-The second, *Promote*, is where you can set all the 'metadata' (data about data!) for the page. Below is a description of all the possible fields in the promote tab and what they do.
+The second, *Promote*, is where you can set all the 'metadata' (data about data!) for the page. Below is a description of all default fields in the promote tab and what they do.
 
-* **Page title:** An optional, search-engine friendly page title. This is the title that appears in the tab of your browser window. It is also the title that would appear in a search engine if the page was returned as part of a set of search results.
 * **Slug:** The last part of the web address for the page. E.g. the slug for a blog page called 'The best things on the web' would be the-best-things-on-the-web (``www.example.com/blog/the-best-things-on-the-web``). This is automatically generated from the main page title set in the Content tab. This can be overridden by adding a new slug into the field. Slugs should be entirely lowercase, with words separated by hyphens (-).
+* **Page title:** An optional, search-engine friendly page title. This is the title that appears in the tab of your browser window. It is also the title that would appear in a search engine if the page was returned as part of a set of search results.
 * **Show in menus:** Ticking this box will ensure that the page is included in automatically generated menus on your site. Note: Pages will only display in menus if all of its parent pages also have *Show in menus* ticked.
 * **Search description:** This field allows you to add text that will be displayed if the page appears in search results. This is especially useful to distinguish between similarly named pages.
-* **Feed image:** This is the image displayed in content feeds, such as the thumbnails on the blog listing page. This optional image is most often used when the primary image on a page is in a format that would not display well in a content feed.
 
-..  ^^ CHECK THAT THIS IS RELEVANT FOR WAGTAIL DEMO >>
+.. image:: ../../_static/images/screen26.5_promote_tab.png
 
-..  ADD IN IMAGE OF PROMOTE TAB >>
+.. Note::
+	You may see more fields than this in your promote tab. These are just the default fields, but you are free to add other fields to this section as necessary.