SS4 documentation updates

This commit is contained in:
Franco Springveldt 2017-09-20 12:15:19 +12:00
parent de0e8e0100
commit 8e3729de51
16 changed files with 47 additions and 41 deletions

BIN
docs/en/_images/blog-post-management.png Executable file → Normal file

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 125 KiB

View File

@ -11,6 +11,6 @@ If you'd rather display your posts within the SiteTree, you can do so using Silv
In mysite/_config/settings.yml
```yaml
BlogPost:
SilverStripe\Blog\Model\BlogPost:
show_in_sitetree: true
```

View File

@ -2,38 +2,38 @@
By default the blog module user and author selection form fields include all users in your website as
candidates for writers, editors and contributors. Additionally, when adding a blog post, again all users are selectable.
This can cause issue with websites that store a large number of users in the database.
This can cause issues with websites that store a large number of users in the database.
In this case you may need to restrict the number of user accounts that are elegable to be selected.
The module has some useful configuration options for this that can be added to your projects config.yml
In this case you may need to restrict the number of user accounts that are eligible for selection.
This module has some useful configuration options for this that can be added to your projects config.yml
## Restricting blog managers to a permission setting
Default is to list all users and when one is selected, they are added to a `blog-users` group with `CMS_ACCESS_CMSMain` permissions.
To only include those already having these permissions you can set in your `config.yml`:
```yaml
Blog:
SilverStripe\Blog\Model\Blog:
grant_user_access: false
```
Note: depending on the incusion order of your config.yml you may need to clear the condifg setting
before updating it. In this case use the folling in yout `mysite/_config.php`:
Note: depending on the incusion order of your config.yml you may need to clear the config setting
before updating it. In this case use the following in your `mysite/_config.php`:
```php
Config::inst()->remove('Blog', 'grant_user_access');
SilverStripe\Core\Config\Config::inst()->remove(SilverStripe\Blog\Model\Blog::class, 'grant_user_access');
```
If you create your own permission and want to ensure the pool of possible selectable users includes
If you create your own permissions and want to ensure the pool of possible selectable users includes
those with this permission you can set the checked permission in `config.yml` with:
```yaml
Blog:
grant_user_permission: SOME_PERMISSION_here
SilverStripe\Blog\Model\Blog:
grant_user_permission: SOME_PERMISSION_HERE
```
## Restricting blog post authors selection to a known group
In a blog post when selecting an author it will default to you (the logged in person creating the post),
however you may be posting on behalf of another person. In this case the slection form field will offer
however you may be posting on behalf of another person. In this case the selection form field will offer
all users as potential blog authors. Again for large websites with many thousands of users this can cause
the site to be slow or non-responsive. We can turn on a filter so that authors need to be in a defined
user group to be able to be selected as an author.
@ -41,31 +41,35 @@ user group to be able to be selected as an author.
Enable this in your `config.yml` by adding a group code:
```yaml
BlogPost:
SilverStripe\Blog\Model\BlogPost:
restrict_authors_to_group: 'group_code'
```
## Extension points in Blog and BlogPost users and how to use
Both Blog and BlogPost have methods which return the list of candidate users or authors. If the previously
mentioned mothods of reducing this list are not suitable or you wish to roll your own, you can utilise a
DataExtension to get the controll you require.
mentioned methods of reducing this list are not suitable or you wish to roll your own, you can utilise a
DataExtension to get the controller you require.
For example in BlogPost:
```php
protected function getCandidateAuthors() {
if($this->config()->get('restrict_authors_to_group')) {
return Group::get()->filter('Code', $this->config()->get('restrict_authors_to_group'))->first()->Members();
protected function getCandidateAuthors()
{
if ($restrictedGroup = $this->config()->get('restrict_authors_to_group')) {
if ($group = $Group::get()->filter('Code', $restrictedGroup)->first()) {
return $group->Members();
}
} else {
$list = Member::get();
$this->extend('updateCandidateAuthors', $list);
return $list;
}
}
}
```
Note the line `$this->extend('updateCandidateAuthors', $list);` which allows you to call a
`updateCandidateAuthors` method in a DataExtension to the Blog Post class if you have not set a `restrict_authors_to_group` config, further filter the passed
`updateCandidateAuthors` method in a DataExtension to the Blog Post class if you have not set a
`restrict_authors_to_group` config, further filter the passed
in Member list before it gets sent back to the form field.
See the documentation on [DataExtension](https://docs.silverstripe.org/en/developer_guides/extending/extensions/) for further implementation notes.

View File

@ -2,14 +2,16 @@
## Configuring whether notifications will send to authors of blogs if comments are spam
Default behaviour using the `silverstripe/comment-notifications` module is to send notification to authors of comments occuring regardless if they are spam or not.
Default behaviour using the `silverstripe/comment-notifications` module is to send notifications of comments to
authors regardless of whether they are spam or not.
In some cases you may wish to not send a notification email to an author if the comment is spam, this is a configurable option.
In some cases you may wish to not send a notification email to an author if the comment is spam,
this is a configurable option.
Add the following into your yaml config:
```
BlogPostNotifications:
SilverStripe\Blog\Model\BlogPostNotifications:
notification_on_spam: false
```

View File

@ -1,4 +1,5 @@
# Configuring pagination
To customise the look and feel of the pagination component, simply override the template located at `/blog/templates/Includes/Pagination.ss`
To customise the look and feel of the pagination component, simply override the template located
at `/blog/templates/Includes/Pagination.ss`
If you have comments enabled, comment pagination is configurable via the [SilverStripe Comments Module configuration](https://github.com/silverstripe/silverstripe-comments/blob/master/docs/en/Configuration.md).

View File

@ -1,16 +1,18 @@
# Configuring Widgets
The blog module comes bundled with some useful widgets. To take advantage of them, you'll need to install the [SilverStripe widgets module](https://github.com/silverstripe/silverstripe-widgets). Widgets are totally optional - so your blog will work just fine without having widgets installed.
The blog module comes bundled with some useful widgets. To take advantage of them, you'll need to install the
[SilverStripe widgets module](https://github.com/silverstripe/silverstripe-widgets). Widgets are totally optional -
so your blog will work just fine without having widgets installed.
You can enable the widgets by adding the following YML config:
```yaml
Blog:
SilverStripe\Blog\Model\Blog:
extensions:
- WidgetPageExtension
BlogPost:
- SilverStripe\Widgets\Extensions\WidgetPageExtension
SilverStripe\Blog\Model\BlogPost:
extensions:
- WidgetPageExtension
- SilverStripe\Widgets\Extensions\WidgetPageExtension
```
Once you have widgets installed you'll see the "Widgets" tab in the content section of your blog.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 98 KiB

After

Width:  |  Height:  |  Size: 326 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 208 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 83 KiB

After

Width:  |  Height:  |  Size: 326 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 125 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 161 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 89 KiB

After

Width:  |  Height:  |  Size: 275 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 88 KiB

After

Width:  |  Height:  |  Size: 260 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 114 KiB

View File

@ -1,11 +1,8 @@
title: Adding a blog post
summary: How to add a new blog post.
# Adding a blog post
## Creating a new blog
On the top of the Contents pane, you will find a button marked "Create." Click it, and a drop-down menu will show up. Select "Blog", then hit the "Go" button.
On the top of the Contents pane, you will find a button marked "Add new." Click it, and a drop-down menu will show up. Select "Blog" from the STEP 2, then hit the "Create" button.
You will notice that a new blog page has been created, with the name of "New Blog". Rename this to "Blog" (or whatever you wish to call this page) and then you can later reorder where this is in your website tree.
@ -21,10 +18,10 @@ To create a blog post, click on your Blog page in the Page Tree in the site-tree
Fill out your blog post content as you would any page in the CMS.
You can also include a banner images and a custom summary description (if this is omitted the first 15 words of your post content will be used when displaying your posts's abstract).
You can also include a banner images and a custom summary description (if this is omitted the first 30 words of your post content will be used when displaying your posts's abstract).
![Banner image and summary](_images/blogging-banner-summary.png)
There is a new right hand panel where you can set a publish date, categories, tags and authors.
From the tab labelled 'Post Options' you can set a publish date, categories, tags and authors.
![Setting blog options](_images/blogging-options.png)