Merge pull request #227 from mandrew/1.2

DOCS: Moved user docs into userguide folder to display on userhelp site

README.md

@@ -21,8 +21,8 @@ permissions" will imply that the person will likely be able to escalate his/her
 
 For user documentation please see:
 
- 1. [Setting up subsites](docs/en/set_up.md)
- 1. [Working with subsites](docs/en/working_with.md)
+ 1. [Setting up subsites](docs/en/userhelp/set_up.md)
+ 1. [Working with subsites](docs/en/userhelp/working_with.md)
 
 ## Features & limitations
 
@@ -41,7 +41,7 @@ For user documentation please see:
 
  * Each subsite domain name has to be set up on the server first, and DNS records need to be updated as appropriate.
  * A subsite cannot use a different codebase as the main site, they are intrinsically tied
- 	* However, you can remove page types from a subsite when creating the subsite - [see the setup documentation for further details](set_up.md)
+ 	* However, you can remove page types from a subsite when creating the subsite - [see the setup documentation for further details](docs/en/userhelp/set_up.md)
  * The only code a developer can edit between subsites is the theme
  * The separation between subsites in the CMS needs to be seen as cosmetic, and mostly applicable to the "Pages" and "Files" sections of the CMS.
  * All subsites run in the same process space and data set. Therefore if an outage affects one subsite it will affect all subsites, and if bad code or hardware corrupts one subsite's data, it's very likely that it has corrupted all subsite data. 

docs/en/introduction.md

@@ -1,84 +1,9 @@
-## Introduction
+# Subsites
 
-Subsites is a module to allow you manage multiple related sites from a single CMS interface.
-
-When Subsites is installed your existing site is defined as the main site, you will be then be able to create related subsites under the main site. 
-
-One of the benefits of subsites is that it is easy to copy pages between the subsites and you have access to all of 
-the assets across all of the subsites.
-
-Subsites is not for running unrelated websites on a single SilverStripe instance so if 2 sites have different vhosts
-you will not be able to run them with Subsites on a single SilverStripe instance.
-
-With Subsites you can set up users to have access to all subsites or just a selection of subsites.
-
-## When to use the Subsites module
-
-* You have a clear parent/main website and a set of subsites associated with it. 
-* You have a group of simple, commonly themed websites
-* Your websites contain some overlapping content, and you want to avoid the redundancy of making the same update to content that exists on multiple CMS installations. 
-* You have simple content websites that use the same templates and modules, and are managed by the same team, but have different themes.  
-* Content editing of the subsites is through the same team, so there is no problem around editors having access to all the files for each subsite, nor around having CMS admin(s) who control access to all the sites.
-
-## When to avoid the Subsites module
-
-* You have constraints on what content CMS editors can and cannot view between subsites.
-* You have a business critical website, and adding complexity around changes and releases for subsites creates unwanted risk. 
-* There is a significant security risk around putting the websites into the same CMS installation. This could be the risk of content bleeding between sites, or the risk of an editor on one site gaining access to content on the other site. 
-* Websites that are distinct and use customised modules and/or bespoke code 
-* Websites that are owned by different business units and/or managed by different development and web teams. (not technical, it just organisational complexity). 
-
-It is important to remember that the only unique trait each site can have is its theme (look and feel), whilst all the other building blocks of the site — the code, database, and modules — are shared. Therefore, one of the biggest drawbacks to using subsites is exposure to a single point of failure. If there is a bug in code that is only used on one subsite, it nevertheless affects all other subsites, because they share a codebase. Similarly, if the database becomes corrupt, all subsites are affected. Further, it is not possible to create or restore backups of any given subsite. Backups must represent and replace the entire collection of sites.
-
-## Access
-
-Access to certain subsites can be limited to administrators based on the groups they are in.
-So for example if you had a couple of subsites you could create a group for each subsite and then specify that the 
-group had access to all subsites or just a specific subsites.
-To access this functionality go to
-
-
-Security -> Groups
-
-![alt text](_images/subsite-admin-security-group.png "Groups")
-
-Select the group you want to modify and then go to the Subsites tab
-
-You can also limit the page types that are available for a subsite (but not the main site).
-This can be done via accessing the particular subsite you want to amend via the Subsite admin section, underneath the
-Subsite theme will be a link called 'Disallow page types?' clicking on that link will display a list of checkboxes for
-all of the page types which can be selected to disable that page type for the subsite you are editing.
-This is useful when you create a content editor and you do not want them to be able to add certain page types.
-
-## Theme
-A theme is group of templates, images and CSS for the look of a website.
-When you are using Subsites you may have different themes installed for your site so you could apply different
-themes for each subsite.
-
-## Page types
-Page types refer to the type of pages that can be set up on a site.
-A page type will have certain features and functionality some examples on SilverStripe would be 'Page', 'HomePage'
-and 'ErrorPage' these all differ to each other in what they would be used for so you would use Page for any pages
-underneath the HomePage.
-
-
-You would only have one HomePage for your site and you may have some logic to only allow you to create one of these
-pages, ErrorPage would only be used for error pages and would be designed to be very minimal to work in situations
-where the site is experiencing difficulties like no DB access.
-
-
-You can set up a Subsite to only work with certain page types so you may have a page type with a contact form for a 
-particular department so you may set up a new subsite and not allow that page type to be used on a particular subsite.
-You will not be able to filter Page Types for the main site.
-
-## Assets
-Assets are files that have been uploaded via the CMS.
-It is suggested to use a naming convention for files designated to be used on a particular subsite or to create folders
-for each subsite to help organise them.
+[User guide](userguide/index.md)
 
 ## FAQ
 
-
 ### How can I restrict a content author to a particular subsite?
 
 

docs/en/userguide/index.md

@@ -0,0 +1,48 @@
+title: Working with multiple websites
+summary: Setting up and editing multiple websites using SilverStripe
+
+# Working with multiple sites
+
+## In this section:
+
+* Understand subsites
+* Learn how to create and delete subsites
+* Learn how to manage subsite permissions
+* Enable/Disable public access to subsites
+* Learn how to create and use subsite templates
+* Learn how to edit existing subsites
+* Sharing content between the main site and subsites
+
+## Before we begin:
+
+* Make sure you have the SilverStripe [Subsites](http://addons.silverstripe.org/add-ons/silverstripe/subsites) module installed.
+* Make sure you are in the "Subsites" section on the Navigation Tabs. 
+* Make sure you have full administrative rights on your site.
+
+## Understanding subsites
+
+Subsites is a module to allow you manage multiple related sites from a single CMS interface. Because all sites run on a single installation of SilverStripe, they can share users, content and assets. They can all use the same templates, or each use different ones.
+
+When Subsites is installed your existing site is defined as the main site, you will be then be able to create related subsites under the main site. 
+
+So for example you may have an international presence and you want to create a subsite for a country where you do business which is geared just for that market. You could create a subsite for this and have all information related to that country kept under this subsite, you can also set up a subdomain for this site.
+
+One of the benefits of subsites is that it is easy to copy pages between the subsites and you have access to all of the assets across all of the subsites.
+
+Subsites is not for running unrelated websites on a single SilverStripe instance so if two sites have different vhosts you will not be able to run them with Subsites on a single SilverStripe instance.
+
+With Subsites you can set up users to have access to all subsites or just a selection of subsites.
+
+## Common subsite uses
+
+Subsites can be used for various different reasons here are some of the common ones:
+
+* Setting up a subsite for a small campaign so for example a clothing company may set up a summer or winter subsite to market just that season of clothing.
+* Locking down a particular subsite you may create a particular department like recruitment who would have access to create and edit pages for their particular subsite but they would not be able to modify the main website.
+* Running sub-domains on a single SilverStripe instance, with subsites if a sub-domain is pointing to the same instance and has been setup correctly you can manage this via a single CMS instance.
+* Subsites can not be used to run multiple websites on a single instance. Subsites does not allow you to run multiple domains/vhosts on a single instance.
+
+## Documentation
+
+* [Set up](set_up.md)
+* [Working with subsites](working_with.md)

docs/en/userguide/set_up.md

@@ -2,44 +2,42 @@
 
 ## Creating subsites
 
-To view, edit and create subsites, go to the *Subsite* section of the CMS. Click *Search* to view a list of all
-existing subsites.
+To view, edit and create subsites, go to the *Subsite* section of the CMS. Click *Search* to view a list of all existing subsites.
 
 ![View subsites](_images/view-subsites.jpg)
 
-Click on a subsite name to edit its details. Click the red X to delete a subsite (you will be asked for confirmation.)
-To create a new subsite, click *Add Subsite*. This opens the *Subsite configuration* subsection.
+Click on a subsite name to edit its details. To create a new subsite, click *Add Subsite*. This opens the *Subsite configuration* subsection.
+
+## Deleting a subsite
+
+Click the red X to delete a subsite (you will be asked for confirmation.)
+
+## Subsite configuration
 
 ![Subsite configuration](_images/subsite-configuration.jpg)
 
 You can configure the following details for a subsite:
 
  * *Name of subsite:* This is the display name for the site in the CMS (not public-facing)
- * *Domains for this subsite:* Lets you add one or more domains for this subsite, e.g., subsite.co.nz, subsite.org.nz,
-subsite.com
+ * *Domains for this subsite:* Lets you add one or more domains for this subsite, e.g., subsite.co.nz, subsite.org.nz, subsite.com
  * *Language:* Sets the language for the subsite. This affects the spellchecker (not the CMS interface language)
  * *Default site:* If your site is accessed by a domain not listed in any subsites, this subsite is shown as default.
  * *Enable public access:* Enables/disables the subsite. Corresponds to the *Active Subsite* column.
- * *Theme:* Shows the list of available themes that exist in the themes directory. The subsite will use the templates
-and styles from the selected theme.
- * *Disallow page types:* Lets you mark some page types to prevent being used within this subsite.
- * *Copy structure from:* Gives you the option to select an existing subsite from which to copy pages and files (see
- "Copying subsites" for more information about this)
+ * *Theme:* Shows the list of available themes that exist in the themes directory. The subsite will use the templates and styles from the selected theme.
+ * *Disallow page types:* Lets you mark some page types to prevent them being used within this subsite (but not the main site). Clicking on that link will display a list of checkboxes for all of the page types which can be selected to disable that page type for the subsite you are editing. This is useful when you create a content editor and you do not want them to be able to add certain page types.
+ * *Copy structure from:* Gives you the option to select an existing subsite from which to copy pages and files (see "Copying subsites" for more information about this)
 
 ## Roles
 
 When creating roles, you can assign the following subsite-specific permissions:
 
- * *Access to 'Subsites' section:* Shows the *Subsite* section in the CMS, allowing you to manage subsites for your
-site (ie, create, edit, view.)
+ * *Access to 'Subsites' section:* Shows the *Subsite* section in the CMS, allowing you to manage subsites for your site (ie, create, edit, view.)
  * *Manage subsites for groups:* Ability to limit the permissions for a group to one or more subsites.
- * *Manage assets for subsites:* Ability to select the subsite to which an asset folder belongs (also requires access to
-*Files* section)
+ * *Manage assets for subsites:* Ability to select the subsite to which an asset folder belongs (also requires access to *Files* section)
 
 ## Groups
 
-Groups can have access to all sites, or to one or more specific subsites. If you have different staff in charge of each
-subsite, you probably want to create a separate group for each subsite.
+Groups can have access to all sites, or to one or more specific subsites. If you have different staff in charge of each subsite, you probably want to [create](#creating-groups) a separate group for each subsite.
 
 The dropdown in the upper left corner of the CMS indicates which subsite you are currently on. 
 
@@ -50,7 +48,19 @@ these subsites* to reveal a checklist of all available sites.
 
 ![Group subsites access](_images/group-subsites-access.png)
 
+### Creating groups
+
+Access to certain subsites can be limited to administrators based on the groups they are in.
+So for example if you had a couple of subsites you could create a group for each subsite and then specify that the group had access to all subsites or just a specific subsites.
+
+To access this functionality go to Security -> Groups
+
+![Creating Groups](_images/subsite-admin-security-group.png "Groups")
+
+Select the group you want to modify and then go to the Subsites tab
+
 ## Copying subsites
+
 Duplicating subsites can be useful if you want to create several subsites based on the same general site structure. You can set up a collection of pages, files, and images and use it as a template. When you create a new subsite, instead of starting from scratch you can copy it all from your existing subsite. This will copy all pages, files and images from that subsite into your new subsite.
 
 To create a new subsite template, create a new subsite described above under "Creating subsites" but don't add any domains. Add a name that will make it easy to see that it is a template. Select the new template from the subsites dropdown in the upper right and create the pages and add the files and images you'd like to become part of the
@@ -60,7 +70,14 @@ When you create a new subsite, you can now choose to Copy structure from your te
 
 ![Copy subsite structure](_images/copy-structure.jpg)
 
-## Disable particular page types from a subsite
+## Page types
+Page types refer to the type of pages that can be set up on a site. A page type will have certain features and functionality some examples on SilverStripe would be 'Page', 'HomePage' and 'ErrorPage' these all differ to each other in what they would be used for so you would use Page for any pages
+underneath the HomePage.
+
+You would only have one HomePage for your site and you may have some logic to only allow you to create one of these pages, ErrorPage would only be used for error pages and would be designed to be very minimal to work in situations where the site is experiencing difficulties (like no database access).
+
+### Disable particular page types from a subsite
+
 Sometimes, you will have two or more websites that are very similar, but have some small differences. For example, a head office and its 3 satellite offices may have 4 subsites, but only the head office site will have a "Company News" section on the site. In this instance, you can still use the subsites module, and use the 'Disallow page types' ability to remove certain page types from being created on subsites.
 
 1. Create a new subsite as you normally would via the Subsites section in the CMS
@@ -69,7 +86,7 @@ Sometimes, you will have two or more websites that are very similar, but have so
 4. Select the page types that you wish to forbid from this subsite.
 5. Click the Save button at the bottom of the section.
 
-Note that this process is exactly the same when editing an existing subsite, you just select the subsite you want to remove page types from instead of creating a new subsite.
+*Note:* This process is exactly the same when editing an existing subsite, you just select the subsite you want to remove page types from instead of creating a new subsite. Also you cannot not filter Page Types for the main site.
 
 ![Disallow page types screenshot](_images/disallow-page-types.png)
 
@@ -79,4 +96,10 @@ Now, whenever someone wants to create a new page on the subsite (the 'London Bra
 
 The page type blacklist applies only to future pages, not existing ones. If an administrator blacklists a defined page type on a subsite, existing pages of that type will remain on the subsite. The administrator (or another user) can later change it to a type that is not blacklisted after the page is published; however, once a user does that, that "grandfathered" pagetype will no longer be available to the published page.
 
-For example, say a subsite user publishes a new Company Page before it was forbidden by an administrator. Later, a user with full administrative rights decides to disallow Company Pages from being created on the subsite. This restriction will only apply to all future pages that are published, but not to existing Company Pages. The full administrator (or any user with sufficient publishing rights) will have to manually convert any published Company Pages on the subsite to that of another allowed type.
+For example, say a subsite user publishes a new Company Page before it was forbidden by an administrator. Later, a user with full administrative rights decides to disallow Company Pages from being created on the subsite. This restriction will only apply to all future pages that are published, but not to existing Company Pages. The full administrator (or any user with sufficient publishing rights) will have to manually convert any published Company Pages on the subsite to that of another allowed type.
+
+## Themes
+A theme is group of templates, images and CSS for the look of a website. When you are using Subsites you may have different themes installed for your site so you could apply different themes for each subsite.
+
+## Assets 
+Assets are files that have been uploaded via the CMS. It is suggested to use a naming convention for files designated to be used on a particular subsite or to create folders for each subsite to help organise them.

docs/en/userguide/working_with.md

@@ -2,11 +2,11 @@
 
 ## Managing content across subsites
 
-Select a subsite from the dropdown in the upper left to display the content for that site in the site tree.
+To edit a particular subsite, choose the subsite from the dropdown menu in the left-hand menu.
 
 ![Subsites dropdown](_images/subsites-dropdown.png)
 
-## Subsites virtual pages
+### Subsites virtual pages
 
 You can pull in the content from a page that resides on another subsite by creating a page of the type **Subsites
 Virtual Page**. Pick the subsite from which you want to pull the content, then select the page. As with regular virtual
@@ -15,7 +15,7 @@ the original content changes.
 
 ![Subsites virtual page](_images/subsites-virtual-page.jpg)
 
-## Duplicating pages from the main site
+### Duplicating pages from the main site
 
 If you have an existing page on the main site that you would like to copy to a subsite, all you need to do is: