From 3da41efa70af845410554f305bb78fd67e9bb889 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Mon, 17 Dec 2012 00:47:30 +0100
Subject: [PATCH] Permission docs

---
 docs/en/reference/dataobject.md | 35 +++++++++++++++++++++++++++++++++
 docs/en/reference/modeladmin.md | 28 ++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/docs/en/reference/dataobject.md b/docs/en/reference/dataobject.md
index 5aea366f3..b9602d308 100644
--- a/docs/en/reference/dataobject.md
+++ b/docs/en/reference/dataobject.md
@@ -192,6 +192,41 @@ To include relations in your summaries, you can use a dot-notation.
 	   );
 	}
 
+## Permissions
+
+Models can be modified in a variety of controllers and user interfaces,
+all of which can implement their own security checks. But often it makes
+sense to centralize those checks on the model, regardless of the used controller.
+
+The API provides four methods for this purpose: 
+`canEdit()`, `canCreate()`, `canView()` and `canDelete()`.
+Since they're PHP methods, they can contain arbitrary logic
+matching your own requirements. They can optionally receive a `$member` argument,
+and default to the currently logged in member (through `Member::currentUser()`).
+
+Example: Check for CMS access permissions
+
+	class MyDataObject extends DataObject {
+	  // ...
+		public function canView($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canEdit($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canDelete($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canCreate($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+	}
+
+**Important**: These checks are not enforced on low-level ORM operations
+such as `write()` or `delete()`, but rather rely on being checked in the invoking code.
+The CMS default sections as well as custom interfaces like
+`[ModelAdmin](/reference/modeladmin)` or `[GridField](/reference/gridfield)`
+already enforce these permissions.
 
 ## API Documentation
 
diff --git a/docs/en/reference/modeladmin.md b/docs/en/reference/modeladmin.md
index 5531e0477..5e122b854 100644
--- a/docs/en/reference/modeladmin.md
+++ b/docs/en/reference/modeladmin.md
@@ -44,6 +44,34 @@ We'll name it `MyAdmin`, but the class name can be anything you want.
 This will automatically add a new menu entry to the CMS, and you're ready to go!
 Try opening http://localhost/admin/products/?flush=all.
 
+## Permissions
+
+Each new `ModelAdmin` subclass creates its own [permission code](/reference/permission),
+for the example above this would be `CMS_ACCESS_MyAdmin`. Users with access to the CMS
+need to have this permission assigned through `admin/security/` in order to gain
+access to the controller (unless they're admins).
+
+The `DataObject` API has more granular permission control, which is enforced in ModelAdmin by default. 
+Available checks are `canEdit()`, `canCreate()`, `canView()` and `canDelete()`.
+Models check for administrator permissions by default. For most cases,
+less restrictive checks make sense, e.g. checking for general CMS access rights.
+
+	:::php
+	class Category extends DataObject {
+	  // ...
+		public function canView($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canEdit($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canDelete($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canCreate($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+
 ## Search Fields
 
 ModelAdmin uses the `[SearchContext](/reference/searchcontext)` class to provide