mirror of
https://github.com/silverstripe/silverstripe-subsites
synced 2024-10-22 11:05:55 +02:00
DOC Update README.md for CMS 5
This commit is contained in:
Guy Sartorelli
parent
f3d7d6c0df
commit
5189a26a39
119
README.md
119
README.md
@ -3,6 +3,12 @@
|
||||
[](https://github.com/silverstripe/silverstripe-subsites/actions/workflows/ci.yml)
|
||||
[](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)
|
||||
|
||||
## Installation
|
||||
|
||||
```sh
|
||||
composer require silverstripe/subsites
|
||||
```
|
||||
|
||||
## Introduction
|
||||
|
||||
The subsites module provides a convenient way of running multiple websites from a single installation of SilverStripe,
|
||||
@ -27,7 +33,7 @@ For user documentation please see:
|
||||
|
||||
## Features & limitations
|
||||
|
||||
### Features:
|
||||
### Features
|
||||
|
||||
* Each subsite appears as a standalone website from a users prospective
|
||||
* No need to duplicate existing code as all subsites use the same codebase as the main site
|
||||
@ -38,7 +44,7 @@ For user documentation please see:
|
||||
* The database is shared between subsites (meaning duplicating content is easy)
|
||||
* When recovering from a disaster it's much easier to bring up a new copy of a single environment with 100 subsites than it is to bring up 100 environments.
|
||||
|
||||
### Limitations:
|
||||
### Limitations
|
||||
|
||||
* Subsites are usually accessed via their own separate domains.
|
||||
In order to allow efficient cross-subsite CMS editing,
|
||||
@ -57,27 +63,13 @@ For user documentation please see:
|
||||
|
||||
If more isolation of code, security, or performance is needed, then consider running multiple separate installations (e.g. on separate servers).
|
||||
|
||||
## Requirements
|
||||
|
||||
* Silverstripe 4.x
|
||||
|
||||
## Installation
|
||||
|
||||
* Create necessary tables by visiting `http://<yoursite>/dev/build` (you should see a `Subsite` table created, among other things). You don't need to run this command for every subsite.
|
||||
* Login to the CMS as an administrator. You should now see a "Subsites" entry on the main menu, access that section now.
|
||||
* Hit the "Add Subsite" button to create a new subsite.
|
||||
* Once you've created a subsite, you'll see a "Create Subsite Domain" button, hit that button to enter a domain or subdomain for your subsite. This will determine the URL of your website. For example, if your site is running on `http://localhost/mysite`, and you set the subdomain to "subsite", then your subsite will be accessible on `http://subsite.localhost/mysite`
|
||||
* Go to the "Pages" section of the CMS. In the top-left above the menu, you'll see a dropdown listing the two subsites - "Main site" is the original site that you had before you installed the subsites module. Select your new subsite, and the site content tree will be changed. It should be empty at this stage.
|
||||
* Add a page - change its title to "Home", and its URL Segment will be changed to "home". Save the page.
|
||||
* Update your DNS and, if necessary, your webserver configuration, so that your subdomain will point to the Silverstripe installation on your webserver. Visit this new subdomain. You should see the new subsite homepage.
|
||||
|
||||
## Usage
|
||||
|
||||
### Strict Subdomain Matching ###
|
||||
### Strict Subdomain Matching
|
||||
|
||||
The module tries to provide sensible defaults, in which it regards `example.com` and `www.example.com` as the same domains. In case you want to distinguish between these variations, set `Subsite::$strict_subdomain_matching` to TRUE. This won't affect wildcard/asterisk checks, but removes the ambiguity about default subdomains.
|
||||
|
||||
### Permissions ###
|
||||
### Permissions
|
||||
|
||||
Groups can be associated with one or more subsites, in which case the granted page- and asset-related permissions
|
||||
only apply to this subsite.
|
||||
@ -108,8 +100,8 @@ theme in the dropdown. Now, this subsite will use a different theme from the ma
|
||||
|
||||
#### Cascading themes
|
||||
|
||||
In Silverstripe 4 themes will resolve theme files by looking through a list of themes (see the documentation on
|
||||
[creating your own theme](https://docs.silverstripe.org/en/4/developer_guides/templates/themes/#developing-your-own-theme)).
|
||||
Themes will resolve theme files by looking through a list of themes (see the documentation on
|
||||
[creating your own theme](https://docs.silverstripe.org/en/developer_guides/templates/themes/#developing-your-own-theme)).
|
||||
Subsites will inherit this configuration for the order of themes. Choosing a theme for a Subsite will set the list of
|
||||
themes to that chosen theme, and all themes that are defined below the chosen theme in priority. For example, with a
|
||||
theme configuration as follows:
|
||||
@ -157,48 +149,52 @@ Not all themes might be suitable or adapted for all subsites. You can optionally
|
||||
|
||||
*mysite/_config.php*
|
||||
|
||||
:::php
|
||||
Subsite::set_allowed_themes(array('blackcandy','mytheme'));
|
||||
```php
|
||||
Subsite::set_allowed_themes(array('blackcandy','mytheme'));
|
||||
```
|
||||
|
||||
### Enable Subsite support on DataObjects
|
||||
To make your DataObject subsite aware, include a SubsiteID on your DataObject. eg:
|
||||
|
||||
*MyDataObject.php*
|
||||
|
||||
:::php
|
||||
private static $has_one = array(
|
||||
'Subsite' => 'Subsite'
|
||||
);
|
||||
```php
|
||||
private static $has_one = [
|
||||
'Subsite' => Subsite::class
|
||||
];
|
||||
```
|
||||
|
||||
Include the current SubsiteID as a hidden field on getCMSFields, or updateCMSFields. eg:
|
||||
|
||||
*MyDataObject.php*
|
||||
|
||||
:::php
|
||||
public function getCMSFields() {
|
||||
$fields = parent::getCMSFields();
|
||||
if(class_exists(Subsite::class)){
|
||||
$fields->push(new HiddenField('SubsiteID','SubsiteID', SubsiteState::singleton()->getSubsiteId()));
|
||||
}
|
||||
return $fields;
|
||||
}
|
||||
```php
|
||||
public function getCMSFields() {
|
||||
$fields = parent::getCMSFields();
|
||||
if (class_exists(Subsite::class)){
|
||||
$fields->push(HiddenField::create('SubsiteID', 'SubsiteID', SubsiteState::singleton()->getSubsiteId()));
|
||||
}
|
||||
return $fields;
|
||||
}
|
||||
```
|
||||
|
||||
To limit your admin gridfields to the current Subsite records, you can do something like this:
|
||||
|
||||
*MyAdmin.php*
|
||||
|
||||
:::php
|
||||
public function getEditForm($id = null, $fields = null){
|
||||
$form = parent::getEditForm($id, $fields);
|
||||
```php
|
||||
public function getEditForm($id = null, $fields = null){
|
||||
$form = parent::getEditForm($id, $fields);
|
||||
|
||||
$gridField = $form->Fields()->fieldByName($this->sanitiseClassName($this->modelClass));
|
||||
if(class_exists(Subsite::class)){
|
||||
$list = $gridField->getList()->filter(['SubsiteID'=>SubsiteState::singleton()->getSubsiteId()]);
|
||||
$gridField->setList($list);
|
||||
}
|
||||
$gridField = $form->Fields()->fieldByName($this->sanitiseClassName($this->modelClass));
|
||||
if(class_exists(Subsite::class)){
|
||||
$list = $gridField->getList()->filter(['SubsiteID'=>SubsiteState::singleton()->getSubsiteId()]);
|
||||
$gridField->setList($list);
|
||||
}
|
||||
|
||||
return $form;
|
||||
}
|
||||
return $form;
|
||||
}
|
||||
```
|
||||
|
||||
### Enable menu support for custom areas in subsites
|
||||
|
||||
@ -206,25 +202,26 @@ Custom admin areas, by default, will not show in the menu of a subsite. Not all
|
||||
|
||||
*mysite/_config.php*
|
||||
|
||||
:::php
|
||||
MyAdmin::add_extension('SubsiteMenuExtension');
|
||||
```php
|
||||
MyAdmin::add_extension('SubsiteMenuExtension');
|
||||
```
|
||||
|
||||
or by defining the subsiteCMSShowInMenu function in your admin:
|
||||
|
||||
*MyAdmin.php*
|
||||
|
||||
:::php
|
||||
public function subsiteCMSShowInMenu(){
|
||||
return true;
|
||||
}
|
||||
```php
|
||||
public function subsiteCMSShowInMenu(){
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
### Using Subsites in combination with Fluent
|
||||
|
||||
When using Subsites in combination with Fluent module, the Subsites module sets the i18n locale to the language defined in the current Subsite. When this behaviour is not desired and you need to use the locale in FluentState use the following setting in your yml config file:
|
||||
|
||||
```yaml
|
||||
SilverStripe\Subsites\Extensions\SiteTreeSubsites:
|
||||
ignore_subsite_locale: true
|
||||
SilverStripe\Subsites\Extensions\SiteTreeSubsites:
|
||||
ignore_subsite_locale: true
|
||||
```
|
||||
|
||||
### Public display of a subsite
|
||||
@ -236,17 +233,21 @@ This is useful to create and check subsites on a live system before publishing t
|
||||
|
||||
Please note that you need to filter for this manually in your own queries:
|
||||
|
||||
$publicSubsites = DataObject::get(
|
||||
'Subsite',
|
||||
Subsite::$check_is_public ? '"IsPublic"=1' : '';
|
||||
);
|
||||
```php
|
||||
$publicSubsites = DataObject::get(
|
||||
'Subsite',
|
||||
Subsite::$check_is_public ? '"IsPublic"=1' : '';
|
||||
);
|
||||
```
|
||||
|
||||
To ensure the logged-in status of a member is carried across to subdomains,
|
||||
you also need to configure PHP session cookies to be set
|
||||
for all subdomains:
|
||||
|
||||
// Example matching subsite1.example.org and www.example.org
|
||||
Session::set_cookie_domain('.example.org');
|
||||
```php
|
||||
// Example matching subsite1.example.org and www.example.org
|
||||
Session::set_cookie_domain('.example.org');
|
||||
```
|
||||
|
||||
## Screenshots
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user