From 50c8a02bffdb6c22af2311bdd2da068e610e4d27 Mon Sep 17 00:00:00 2001 From: Aaron Carlino Date: Mon, 7 Aug 2017 15:11:17 +1200 Subject: [PATCH] remove tabs --- .../01_Installation/03_Windows.md | 8 +- .../01_Installation/05_Common_Problems.md | 25 +- docs/en/00_Getting_Started/02_Composer.md | 34 +- .../03_Environment_Management.md | 4 +- .../01_Tutorials/01_Building_A_Basic_Site.md | 146 ++--- .../01_Tutorials/02_Extending_A_Basic_Site.md | 431 +++++++-------- docs/en/01_Tutorials/04_Site_Search.md | 148 ++--- .../00_Model/01_Data_Model_and_ORM.md | 420 +++++++-------- .../00_Model/02_Relations.md | 390 +++++++------- .../02_Developer_Guides/00_Model/03_Lists.md | 70 +-- .../00_Model/04_Data_Types_and_Casting.md | 184 +++---- .../00_Model/05_Extending_DataObjects.md | 98 ++-- .../00_Model/06_SearchFilters.md | 40 +- .../00_Model/07_Permissions.md | 44 +- .../00_Model/08_SQL_Select.md | 200 +++---- .../00_Model/09_Validation.md | 32 +- .../00_Model/10_Versioning.md | 198 +++---- .../00_Model/11_Scaffolding.md | 304 +++++------ .../00_Model/12_Indexes.md | 46 +- .../How_Tos/Dynamic_Default_Fields.md | 42 +- .../How_Tos/Grouping_DataObject_Sets.md | 172 +++--- .../01_Templates/01_Syntax.md | 324 +++++------ .../01_Templates/02_Common_Variables.md | 134 ++--- .../01_Templates/03_Requirements.md | 28 +- .../01_Templates/05_Template_Inheritance.md | 26 +- .../01_Templates/07_Caching.md | 22 +- .../01_Templates/08_Translations.md | 2 +- .../01_Templates/09_Casting.md | 62 +-- .../How_Tos/01_Navigation_Menu.md | 4 +- .../01_Templates/How_Tos/02_Pagination.md | 17 +- .../How_Tos/03_Disable_Anchor_Links.md | 16 +- .../02_Controllers/01_Introduction.md | 154 +++--- .../02_Controllers/03_Access_Control.md | 242 ++++----- .../02_Controllers/04_Redirection.md | 26 +- .../03_Forms/03_Form_Templates.md | 48 +- .../03_Forms/04_Form_Security.md | 22 +- .../03_Forms/05_Form_Transformations.md | 38 +- .../03_Forms/06_Tabbed_Forms.md | 20 +- .../03_Forms/Field_types/02_DateField.md | 72 +-- .../Field_types/03_HTMLEditorField.md | 174 +++--- .../03_Forms/Field_types/04_GridField.md | 310 +++++------ .../03_Forms/How_Tos/01_Encapsulate_Forms.md | 250 ++++----- .../03_Forms/How_Tos/02_Lightweight_Form.md | 44 +- .../04_Create_a_GridField_ActionProvider.md | 112 ++-- .../How_Tos/05_Simple_Contact_Form.md | 142 ++--- .../04_Configuration/00_Configuration.md | 154 +++--- .../04_Configuration/01_SiteConfig.md | 58 +- .../05_Extending/01_Extensions.md | 226 ++++---- .../05_Extending/04_Shortcodes.md | 134 ++--- .../05_Extending/05_Injector.md | 246 ++++----- .../05_Extending/06_Aspects.md | 154 +++--- .../How_Tos/01_Publish_a_Module.md | 50 +- .../02_Create_a_Google_Maps_Shortcode.md | 34 +- .../How_Tos/03_Track_member_logins.md | 78 +-- .../06_Testing/00_Unit_Testing.md | 150 +++--- .../06_Testing/01_Functional_Testing.md | 34 +- .../06_Testing/04_Fixtures.md | 302 +++++------ .../How_Tos/00_Write_a_SapphireTest.md | 56 +- .../How_Tos/01_Write_a_FunctionalTest.md | 58 +- .../06_Testing/How_Tos/02_FixtureFactories.md | 48 +- .../06_Testing/How_Tos/03_Testing_Email.md | 22 +- .../07_Debugging/00_Environment_Types.md | 56 +- .../07_Debugging/03_Template_debugging.md | 12 +- .../02_Developer_Guides/07_Debugging/index.md | 3 +- .../08_Performance/00_Partial_Caching.md | 168 +++--- .../08_Performance/01_Caching.md | 2 +- .../08_Performance/02_HTTP_Cache_Headers.md | 4 +- .../08_Performance/05_Resource_Usage.md | 8 +- .../09_Security/00_Member.md | 104 ++-- .../09_Security/03_Authentication.md | 6 +- .../09_Security/04_Secure_Coding.md | 438 +++++++-------- docs/en/02_Developer_Guides/10_Email/index.md | 36 +- .../11_Integration/00_CSV_Import.md | 264 ++++----- .../11_Integration/02_RSSFeed.md | 212 ++++---- .../Import_CSV_through_a_Controller.md | 106 ++-- .../How_Tos/custom_csvbulkloader.md | 120 ++--- .../11_Integration/How_Tos/embed_rss.md | 60 +-- .../12_Search/01_Searchcontext.md | 256 ++++----- .../12_Search/02_FulltextSearch.md | 52 +- docs/en/02_Developer_Guides/13_i18n/index.md | 182 +++---- .../14_Files/01_File_Management.md | 26 +- .../02_Developer_Guides/14_Files/02_Images.md | 96 ++-- .../14_Files/03_File_Security.md | 8 +- .../01_ModelAdmin.md | 320 +++++------ .../02_CMS_Architecture.md | 391 +++++++------- .../03_CMS_Layout.md | 16 +- .../04_Preview.md | 72 +-- .../05_Typography.md | 10 +- .../06_Javascript_Development.md | 506 +++++++++--------- .../07_ReactJS_Redux_and_GraphQL.md | 194 +++---- .../How_Tos/CMS_Alternating_Button.md | 120 ++--- .../How_Tos/CMS_Formfield_Help_Text.md | 24 +- .../How_Tos/Customise_CMS_Menu.md | 72 +-- .../How_Tos/Customise_CMS_Pages_List.md | 86 +-- .../How_Tos/Customise_CMS_Tree.md | 64 +-- .../How_Tos/Customise_React_Components.md | 2 +- .../How_Tos/Customise_Site_Reports.md | 54 +- .../How_Tos/Extend_CMS_Interface.md | 146 ++--- .../Extending_An_Existing_ModelAdmin.md | 24 +- .../16_Execution_Pipeline/01_Flushable.md | 74 +-- docs/en/02_Developer_Guides/17_CLI/index.md | 68 +-- .../18_Cookies_And_Sessions/01_Cookies.md | 64 +-- .../18_Cookies_And_Sessions/02_Sessions.md | 40 +- docs/en/03_Upgrading/index.md | 4 +- docs/en/04_Changelogs/2.3.0.md | 11 +- docs/en/04_Changelogs/2.3.2.md | 8 +- docs/en/04_Changelogs/2.4.0.md | 4 +- docs/en/04_Changelogs/3.1.19.md | 10 +- docs/en/04_Changelogs/3.2.4.md | 10 +- docs/en/04_Changelogs/3.3.2.md | 10 +- docs/en/04_Changelogs/4.0.0.md | 144 ++--- docs/en/05_Contributing/01_Code.md | 12 +- docs/en/05_Contributing/04_Release_Process.md | 18 +- docs/en/05_Contributing/06_Documentation.md | 18 +- .../05_Contributing/08_Translation_Process.md | 44 +- .../14_PHP_Coding_Conventions.md | 90 ++-- 116 files changed, 6046 insertions(+), 6032 deletions(-) diff --git a/docs/en/00_Getting_Started/01_Installation/03_Windows.md b/docs/en/00_Getting_Started/01_Installation/03_Windows.md index 739e441e2..2427611d4 100644 --- a/docs/en/00_Getting_Started/01_Installation/03_Windows.md +++ b/docs/en/00_Getting_Started/01_Installation/03_Windows.md @@ -66,10 +66,10 @@ Due to some changes to `mod_dir` in [Apache 2.4](http://httpd.apache.org/docs/cu ``` - # Turn off index.php handling requests to the homepage fixes issue in apache >=2.4 - - DirectoryIndex disabled - + # Turn off index.php handling requests to the homepage fixes issue in apache >=2.4 + + DirectoryIndex disabled + # ------ # ``` diff --git a/docs/en/00_Getting_Started/01_Installation/05_Common_Problems.md b/docs/en/00_Getting_Started/01_Installation/05_Common_Problems.md index 1176cc1b1..ff9a1cd6a 100644 --- a/docs/en/00_Getting_Started/01_Installation/05_Common_Problems.md +++ b/docs/en/00_Getting_Started/01_Installation/05_Common_Problems.md @@ -15,10 +15,11 @@ If you can log-in to the CMS as an administrator, append `?isDev=1` to any URL t "dev mode". If you can't log-in in the first place because of the error, add this directive to your `mysite/_config/config.yml` (don't forget to remove it afterwards!): - :::php +```yml Director: # temporary debugging statement environment_type: 'dev' +```
On "live" environments, the `?isDev=1` solution is preferred, as it means that your other visitors don't see ugly @@ -31,10 +32,10 @@ Due to some changes to `mod_dir` in [Apache 2.4](http://httpd.apache.org/docs/cu ``` - # Turn off index.php handling requests to the homepage fixes issue in apache >=2.4 - - DirectoryIndex disabled - + # Turn off index.php handling requests to the homepage fixes issue in apache >=2.4 + + DirectoryIndex disabled + # ------ # ``` @@ -109,16 +110,16 @@ $path = dirname(__FILE__); $files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($path), RecursiveIteratorIterator::SELF_FIRST); $matched = false; foreach($files as $name => $file){ - if($file->getExtension() != 'php') continue; - if(preg_match('/thirdparty|vendor/',$file->getPathname())) continue; + if($file->getExtension() != 'php') continue; + if(preg_match('/thirdparty|vendor/',$file->getPathname())) continue; $content = file_get_contents($file->getPathname()); if(preg_match('/^[[:blank:]]+<\?' . 'php/', $content)) { - echo sprintf("%s: Space before opening bracket\n", $file->getPathname()); - $matched = true; - } + echo sprintf("%s: Space before opening bracket\n", $file->getPathname()); + $matched = true; + } if(preg_match('/^\?' . '>\n?[[:blank:]]+/m', $content)) { - echo sprintf("%s: Space after closing bracket\n", $file->getPathname()); - $matched = true; + echo sprintf("%s: Space after closing bracket\n", $file->getPathname()); + $matched = true; } } ``` diff --git a/docs/en/00_Getting_Started/02_Composer.md b/docs/en/00_Getting_Started/02_Composer.md index c57485994..437399cb3 100644 --- a/docs/en/00_Getting_Started/02_Composer.md +++ b/docs/en/00_Getting_Started/02_Composer.md @@ -180,23 +180,23 @@ Full example of composer.json with the SSAutoGitIgnore installed and enabled ```json { - "name": "silverstripe/installer", - "description": "The SilverStripe Framework Installer", - "require": { - "php": ">=5.5.0", - "silverstripe/cms": "^4.0", - "silverstripe/framework": "^4.0", - "silverstripe-themes/simple": "~3.2.0" - }, - "require-dev": { - "silverstripe/docsviewer": "^3.0", - "gdmedia/ss-auto-git-ignore": "^1.0" - }, - "scripts": { - "post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go" - }, - "minimum-stability": "dev", - "prefer-stable": true + "name": "silverstripe/installer", + "description": "The SilverStripe Framework Installer", + "require": { + "php": ">=5.5.0", + "silverstripe/cms": "^4.0", + "silverstripe/framework": "^4.0", + "silverstripe-themes/simple": "~3.2.0" + }, + "require-dev": { + "silverstripe/docsviewer": "^3.0", + "gdmedia/ss-auto-git-ignore": "^1.0" + }, + "scripts": { + "post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go" + }, + "minimum-stability": "dev", + "prefer-stable": true } ``` diff --git a/docs/en/00_Getting_Started/03_Environment_Management.md b/docs/en/00_Getting_Started/03_Environment_Management.md index b56a8bcd6..05946a051 100644 --- a/docs/en/00_Getting_Started/03_Environment_Management.md +++ b/docs/en/00_Getting_Started/03_Environment_Management.md @@ -48,9 +48,9 @@ database credentials could be the same. To do this, you can add this snippet to ```php try { - (new \Dotenv\Dotenv('/path/to/env/'))->load(); + (new \Dotenv\Dotenv('/path/to/env/'))->load(); } catch (\Dotenv\Exception\InvalidPathException $e) { - // no file found + // no file found } ``` diff --git a/docs/en/01_Tutorials/01_Building_A_Basic_Site.md b/docs/en/01_Tutorials/01_Building_A_Basic_Site.md index 0eff4b428..9a4404a54 100644 --- a/docs/en/01_Tutorials/01_Building_A_Basic_Site.md +++ b/docs/en/01_Tutorials/01_Building_A_Basic_Site.md @@ -112,27 +112,27 @@ for a template file in the *simple/templates* folder, with the name `` Open *themes/simple/templates/Page.ss*. It uses standard HTML apart from these exceptions: ```ss - <% base_tag %> + <% base_tag %> ``` The base_tag variable is replaced with the HTML [base element](http://www.w3.org/TR/html401/struct/links.html#h-12.4). This ensures the browser knows where to locate your site's images and css files. ```ss - $Title - $SiteConfig.Title + $Title + $SiteConfig.Title ``` These two variables are found within the html `` tag, and are replaced by the "Page Name" and "Settings -> Site Title" fields in the CMS. ```ss - $MetaTags + $MetaTags ``` The MetaTags variable will add meta tags, which are used by search engines. You can define your meta tags in the tab fields at the bottom of the content editor in the CMS. ```ss - $Layout + $Layout ``` The Layout variable is replaced with the contents of a template file with the same name as the page type we are using. @@ -140,7 +140,7 @@ The Layout variable is replaced with the contents of a template file with the sa Open *themes/simple/templates/Layout/Page.ss*. You will see more HTML and more SilverStripe template replacement tags and variables. ```ss - $Content + $Content ``` The Content variable is replaced with the content of the page currently being viewed. This allows you to make all changes to @@ -151,7 +151,7 @@ browser and are either prefixed with a dollar sign ($) or placed between SilverStripe template tags: ```ss - <% %> + <% %> ``` **Flushing the cache** @@ -169,7 +169,7 @@ Open up *themes/simple/templates/Includes/Navigation.ss* The Menu for our site is created using a **loop**. Loops allow us to iterate over a data set, and render each item using a sub-template. ```ss - <% loop $Menu(1) %> + <% loop $Menu(1) %> ``` returns a set of first level menu items. We can then use the template variable @@ -179,13 +179,13 @@ returns a set of first level menu items. We can then use the template variable ```ss - <ul> - <% loop $Menu(1) %> - <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> - <a href="$Link" title="$Title.XML">$MenuTitle.XML</a> - </li> - <% end_loop %> - </ul> + <ul> + <% loop $Menu(1) %> + <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> + <a href="$Link" title="$Title.XML">$MenuTitle.XML</a> + </li> + <% end_loop %> + </ul> ``` Here we've created an unordered list called *Menu1*, which *themes/simple/css/layout.css* will style into the menu. @@ -204,15 +204,15 @@ A useful feature is highlighting the current page the user is looking at. We can For example, if you were here: "Home > Company > Staff > Bob Smith", you may want to highlight 'Company' to say you are in that section. ```ss - <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> - <a href="$Link" title="$Title.XML">$MenuTitle.XML</a> - </li> + <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> + <a href="$Link" title="$Title.XML">$MenuTitle.XML</a> + </li> ``` you will then be able to target a section in css (*simple/css/layout.css*), e.g.: ```css - .section { background:#ccc; } + .section { background:#ccc; } ``` ## A second level of navigation @@ -235,16 +235,16 @@ Great, we now have a hierarchical site structure! Let's look at how this is crea Adding a second level menu is very similar to adding the first level menu. Open up */themes/simple/templates/Includes/Sidebar.ss* template and look at the following code: ```ss - <ul> - <% loop $Menu(2) %> - <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> - <a href="$Link" title="Go to the $Title.XML page"> - <span class="arrow">→</span> - <span class="text">$MenuTitle.XML</span> - </a> - </li> - <% end_loop %> - </ul> + <ul> + <% loop $Menu(2) %> + <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> + <a href="$Link" title="Go to the $Title.XML page"> + <span class="arrow">→</span> + <span class="text">$MenuTitle.XML</span> + </a> + </li> + <% end_loop %> + </ul> ``` This should look very familiar. It is the same idea as our first menu, except the loop block now uses *Menu(2)* instead of *Menu(1)*. @@ -257,20 +257,20 @@ Look again in the *Sidebar.ss* file and you will see that the menu is surrounded like this: ```ss - <% if $Menu(2) %> - ... - <ul> - <% loop $Menu(2) %> - <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> - <a href="$Link" title="Go to the $Title.XML page"> - <span class="arrow">→</span> - <span class="text">$MenuTitle.XML</span> - </a> - </li> - <% end_loop %> - </ul> - ... - <% end_if %> + <% if $Menu(2) %> + ... + <ul> + <% loop $Menu(2) %> + <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> + <a href="$Link" title="Go to the $Title.XML page"> + <span class="arrow">→</span> + <span class="text">$MenuTitle.XML</span> + </a> + </li> + <% end_loop %> + </ul> + ... + <% end_if %> ``` The if block only includes the code inside it if the condition is true. In this case, it checks for the existence of @@ -282,11 +282,11 @@ Now that we have two levels of navigation, it would also be useful to include so Open up */themes/simple/templates/Includes/BreadCrumbs.ss* template and look at the following code: ```ss - <% if $Level(2) %> - <div id="Breadcrumbs"> - $Breadcrumbs - </div> - <% end_if %> + <% if $Level(2) %> + <div id="Breadcrumbs"> + $Breadcrumbs + </div> + <% end_if %> ``` Breadcrumbs are only useful on pages that aren't in the top level. We can ensure that we only show them if we aren't in @@ -295,7 +295,7 @@ the top level with another if statement. The *Level* page control allows you to get data from the page's parents, e.g. if you used *Level(1)*, you could use: ```ss - $Level(1).Title + $Level(1).Title ``` to get the top level page title. In this case, we merely use it to check the existence of a second level page: if one exists then we include breadcrumbs. @@ -309,25 +309,25 @@ Feel free to experiment with the if and loop statements. For example, you could The following example runs an if statement and a loop on *Children*, checking to see if any sub-pages exist within each top level navigation item. You will need to come up with your own CSS to correctly style this approach. ```ss - <ul> - <% loop $Menu(1) %> - <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> - <a href="$Link" title="$Title.XML">$MenuTitle.XML</a> - <% if $Children %> - <ul> - <% loop $Children %> - <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> - <a href="$Link" title="Go to the $Title.XML page"> - <span class="arrow">→</span> - <span class="text">$MenuTitle.XML</span> - </a> - </li> - <% end_loop %> - </ul> - <% end_if %> - </li> - <% end_loop %> - </ul> + <ul> + <% loop $Menu(1) %> + <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> + <a href="$Link" title="$Title.XML">$MenuTitle.XML</a> + <% if $Children %> + <ul> + <% loop $Children %> + <li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"> + <a href="$Link" title="Go to the $Title.XML page"> + <span class="arrow">→</span> + <span class="text">$MenuTitle.XML</span> + </a> + </li> + <% end_loop %> + </ul> + <% end_if %> + </li> + <% end_loop %> + </ul> ``` @@ -393,21 +393,21 @@ To create a new template layout, create a copy of *Page.ss* (found in *themes/si First, we don't need the breadcrumbs and the secondary menu for the homepage. Let's remove them: ```ss - <% include SideBar %> + <% include SideBar %> ``` We'll also replace the title text with an image. Find this line: ```ss - <h1>$Title</h1> + <h1>$Title</h1> ``` and replace it with: ```ss - <div id="Banner"> - <img src="http://www.silverstripe.org/assets/SilverStripe-200.png" alt="Homepage image" /> - </div> + <div id="Banner"> + <img src="http://www.silverstripe.org/assets/SilverStripe-200.png" alt="Homepage image" /> + </div> ``` Your Home page should now look like this: diff --git a/docs/en/01_Tutorials/02_Extending_A_Basic_Site.md b/docs/en/01_Tutorials/02_Extending_A_Basic_Site.md index 3a15258ec..12451c9f8 100644 --- a/docs/en/01_Tutorials/02_Extending_A_Basic_Site.md +++ b/docs/en/01_Tutorials/02_Extending_A_Basic_Site.md @@ -68,21 +68,21 @@ We'll start with the *ArticlePage* page type. First we create the model, a class **mysite/code/ArticlePage.php** ```php - use Page; + use Page; - class ArticlePage extends Page - { - - } + class ArticlePage extends Page + { + + } ``` **mysite/code/ArticlePageController.php** ```php - use PageController; + use PageController; - class ArticlePageController extends PageController - { - - } + class ArticlePageController extends PageController + { + + } ``` @@ -95,21 +95,21 @@ Let's create the *ArticleHolder* page type. **mysite/code/ArticleHolder.php** ```php - use Page; + use Page; - class ArticleHolder extends Page - { - private static $allowed_children = ['ArticlePage']; - } + class ArticleHolder extends Page + { + private static $allowed_children = ['ArticlePage']; + } ``` **mysite/code/ArticleHolderController.php** -```php - use PageController; +```php + use PageController; - class ArticleHolderController extends PageController - { - - } + class ArticleHolderController extends PageController + { + + } ``` Here we have done something interesting: the *$allowed_children* field. This is one of a number of static fields we can define to change the properties of a page type. The *$allowed_children* field is an array of page types that are allowed @@ -132,17 +132,17 @@ the $db array to add extra fields to the database. It would be nice to know when it. Add a *$db* property definition in the *ArticlePage* class: ```php - use Page; + use Page; - class ArticlePage extends Page - { - private static $db = [ - 'Date' => 'Date', - 'Author' => 'Text' - ]; - - // ..... - } + class ArticlePage extends Page + { + private static $db = [ + 'Date' => 'Date', + 'Author' => 'Text' + ]; + + // ..... + } ``` Every entry in the array is a *key => value* pair. The **key** is the name of the field, and the **value** is the type. See ["data types and casting"](/developer_guides/model/data_types_and_casting) for a complete list of types. @@ -157,33 +157,33 @@ When we rebuild the database, we will see that the *ArticlePage* table has been To add our new fields to the CMS we have to override the *getCMSFields()* method, which is called by the CMS when it creates the form to edit a page. Add the method to the *ArticlePage* class. ```php - use Page; + use Page; - class ArticlePage extends Page - { - // ... - - public function getCMSFields() - { - $fields = parent::getCMSFields(); - - $dateField = new DateField('Date'); - $dateField->setConfig('showcalendar', true); - $fields->addFieldToTab('Root.Main', $dateField, 'Content'); - $fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content'); - - return $fields; - } - } - - // ... + class ArticlePage extends Page + { + // ... + + public function getCMSFields() + { + $fields = parent::getCMSFields(); + + $dateField = new DateField('Date'); + $dateField->setConfig('showcalendar', true); + $fields->addFieldToTab('Root.Main', $dateField, 'Content'); + $fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content'); + + return $fields; + } + } + + // ... ``` Let's walk through this method. ```php - $fields = parent::getCMSFields(); + $fields = parent::getCMSFields(); ``` @@ -191,8 +191,8 @@ Firstly, we get the fields from the parent class; we want to add fields, not rep returned is a [FieldList](api:SilverStripe\Forms\FieldList) object. ```php - $fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content'); - $fields->addFieldToTab('Root.Main', new DateField('Date'), 'Content'); + $fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content'); + $fields->addFieldToTab('Root.Main', new DateField('Date'), 'Content'); ``` @@ -208,7 +208,7 @@ We have added two fields: A simple [TextField](api:SilverStripe\Forms\TextField) There are many more fields available in the default installation, listed in ["form field types"](/developer_guides/forms/field_types/common_subclasses). ```php - return $fields; + return $fields; ``` @@ -227,50 +227,50 @@ To make the date field a bit more user friendly, you can add a dropdown calendar the date field will have the date format defined by your locale. ```php - use Page; + use Page; - class ArticlePage extends Page - { - - // ..... - - public function getCMSFields() - { - $fields = parent::getCMSFields(); - - $dateField = new DateField('Date', 'Article Date (for example: 20/12/2010)'); - $dateField->setConfig('showcalendar', true); - $dateField->setConfig('dateformat', 'dd/MM/YYYY'); - - $fields->addFieldToTab('Root.Main', $dateField, 'Content'); - $fields->addFieldToTab('Root.Main', new TextField('Author', 'Author Name'), 'Content'); + class ArticlePage extends Page + { + + // ..... + + public function getCMSFields() + { + $fields = parent::getCMSFields(); + + $dateField = new DateField('Date', 'Article Date (for example: 20/12/2010)'); + $dateField->setConfig('showcalendar', true); + $dateField->setConfig('dateformat', 'dd/MM/YYYY'); + + $fields->addFieldToTab('Root.Main', $dateField, 'Content'); + $fields->addFieldToTab('Root.Main', new TextField('Author', 'Author Name'), 'Content'); - return $fields; - } + return $fields; + } ``` Let's walk through these changes. ```php - $dateField = new DateField('Date', 'Article Date (for example: 20/12/2010)'); + $dateField = new DateField('Date', 'Article Date (for example: 20/12/2010)'); ``` *$dateField* is declared in order to change the configuration of the DateField. ```php - $dateField->setConfig('showcalendar', true); + $dateField->setConfig('showcalendar', true); ``` By enabling *showCalendar* you show a calendar overlay when clicking on the field. ```php - $dateField->setConfig('dateformat', 'dd/MM/YYYY'); + $dateField->setConfig('dateformat', 'dd/MM/YYYY'); ``` *dateFormat* allows you to specify how you wish the date to be entered and displayed in the CMS field. See the [DBDateField](api:SilverStripe\ORM\FieldType\DBDateField) documentation for more configuration options. ```php - $fields->addFieldToTab('Root.Main', new TextField('Author', 'Author Name'), 'Content'); + $fields->addFieldToTab('Root.Main', new TextField('Author', 'Author Name'), 'Content'); ``` By default the field name *'Date'* or *'Author'* is shown as the title, however this might not be that helpful so to change the title, add the new title as the second argument. @@ -289,19 +289,19 @@ First, the template for displaying a single article: **themes/simple/templates/Layout/ArticlePage.ss** - :::ss - <% include SideBar %> - <div class="content-container unit size3of4 lastUnit"> - <article> - <h1>$Title</h1> - <div class="news-details"> - <p>Posted on $Date.Nice by $Author</p> - </div> - <div class="content">$Content</div> - </article> - $Form - </div> - +```ss + <% include SideBar %> + <div class="content-container unit size3of4 lastUnit"> + <article> + <h1>$Title</h1> + <div class="news-details"> + <p>Posted on $Date.Nice by $Author</p> + </div> + <div class="content">$Content</div> + </article> + $Form + </div> +``` Most of the code is just like the regular Page.ss, we include an informational div with the date and the author of the Article. @@ -322,24 +322,24 @@ We'll now create a template for the article holder. We want our news section to **themes/simple/templates/Layout/ArticleHolder.ss** - :::ss - <% include SideBar %> - <div class="content-container unit size3of4 lastUnit"> - <article> - <h1>$Title</h1> - $Content - <div class="content">$Content</div> - </article> - <% loop $Children %> - <article> - <h2><a href="$Link" title="Read more on "{$Title}"">$Title</a></h2> - <p>$Content.FirstParagraph</p> - <a href="$Link" title="Read more on "{$Title}"">Read more >></a> - </article> - <% end_loop %> - $Form - </div> - +```ss + <% include SideBar %> + <div class="content-container unit size3of4 lastUnit"> + <article> + <h1>$Title</h1> + $Content + <div class="content">$Content</div> + </article> + <% loop $Children %> + <article> + <h2><a href="$Link" title="Read more on "{$Title}"">$Title</a></h2> + <p>$Content.FirstParagraph</p> + <a href="$Link" title="Read more on "{$Title}"">Read more >></a> + </article> + <% end_loop %> + $Form + </div> +``` Here we use the page control *Children*. As the name suggests, this control allows you to iterate over the children of a page. In this case, the children are our news articles. The *$Link* variable will give the address of the article which we can use to create a link, and the *FirstParagraph* function of the [DBHTMLText](api:SilverStripe\ORM\FieldType\DBHTMLText) field gives us a nice summary of the article. The function strips all tags from the paragraph extracted. @@ -356,38 +356,39 @@ Cut the code between "loop Children" in *ArticleHolder.ss** and replace it with **themes/simple/templates/Layout/ArticleHolder.ss** - :::ss - ... - <% loop $Children %> - <% include ArticleTeaser %> - <% end_loop %> - ... - +```ss + ... + <% loop $Children %> + <% include ArticleTeaser %> + <% end_loop %> + ... +``` Paste the code that was in ArticleHolder into a new include file called ArticleTeaser.ss: **themes/simple/templates/Includes/ArticleTeaser.ss** - :::ss - <article> - <h2><a href="$Link" title="Read more on "{$Title}"">$Title</a></h2> - <p>$Content.FirstParagraph</p> - <a href="$Link" title="Read more on "{$Title}"">Read more >></a> - </article> - +```ss + <article> + <h2><a href="$Link" title="Read more on "{$Title}"">$Title</a></h2> + <p>$Content.FirstParagraph</p> + <a href="$Link" title="Read more on "{$Title}"">Read more >></a> + </article> +``` + ### Changing the icons of pages in the CMS Now let's make a purely cosmetic change that nevertheless helps to make the information presented in the CMS clearer. Add the following field to the *ArticleHolder* and *ArticlePage* classes: - :::php - private static $icon = "cms/images/treeicons/news-file.gif"; - +```php + private static $icon = "cms/images/treeicons/news-file.gif"; +``` And this one to the *HomePage* class: - :::php - private static $icon = "cms/images/treeicons/home-file.png"; - +```php + private static $icon = "cms/images/treeicons/home-file.png"; +``` This will change the icons for the pages in the CMS. @@ -404,12 +405,12 @@ It would be nice to greet page visitors with a summary of the latest news when t **mysite/code/HomePage.php** ```php - // ... - public function LatestNews($num=5) - { - $holder = ArticleHolder::get()->First(); - return ($holder) ? ArticlePage::get()->filter('ParentID', $holder->ID)->sort('Date DESC')->limit($num) : false; - } + // ... + public function LatestNews($num=5) + { + $holder = ArticleHolder::get()->First(); + return ($holder) ? ArticlePage::get()->filter('ParentID', $holder->ID)->sort('Date DESC')->limit($num) : false; + } ``` This function simply runs a database query that gets the latest news articles from the database. By default, this is five, but you can change it by passing a number to the function. See the [Data Model and ORM](/developer_guides/model/data_model_and_orm) documentation for details. We can reference this function as a page control in our *HomePage* template: @@ -417,12 +418,12 @@ This function simply runs a database query that gets the latest news articles fr **themes/simple/templates/Layout/Homepage.ss** ```ss - <!-- ... --> - <div class="content">$Content</div> - </article> - <% loop $LatestNews %> - <% include ArticleTeaser %> - <% end_loop %> + <!-- ... --> + <div class="content">$Content</div> + </article> + <% loop $LatestNews %> + <% include ArticleTeaser %> + <% end_loop %> ``` When SilverStripe comes across a variable or page control it doesn't recognize, it first passes control to the controller. If the controller doesn't have a function for the variable or page control, it then passes control to the data object. If it has no matching functions, it then searches its database fields. Failing that it will return nothing. @@ -440,15 +441,15 @@ An RSS feed is something that no news section should be without. SilverStripe ma **mysite/code/ArticleHolder.php** ```php - private static $allowed_actions = [ - 'rss' - ]; + private static $allowed_actions = [ + 'rss' + ]; - public function rss() - { - $rss = new RSSFeed($this->Children(), $this->Link(), "The coolest news around"); - return $rss->outputToBrowser(); - } + public function rss() + { + $rss = new RSSFeed($this->Children(), $this->Link(), "The coolest news around"); + return $rss->outputToBrowser(); + } ``` Ensure that when you have input the code to implement an RSS feed; flush the webpage afterwards @@ -465,11 +466,11 @@ Now all we need is to let the user know that our RSS feed exists. Add this funct **mysite/code/ArticleHolder.php** ```php - public function init() - { - RSSFeed::linkToFeed($this->Link() . "rss"); - parent::init(); - } + public function init() + { + RSSFeed::linkToFeed($this->Link() . "rss"); + parent::init(); + } ``` This automatically generates a link-tag in the header of our template. The *init* function is then called on the parent class to ensure any initialization the parent would have done if we hadn't overridden the *init* function is still called. Depending on your browser, you can see the RSS feed link in the address bar. @@ -481,25 +482,25 @@ Now that we have a complete news section, let's take a look at the staff section **mysite/code/StaffHolder.php** ```php - use Page; + use Page; - class StaffHolder extends Page - { - private static $db = []; - private static $has_one = []; - private static $allowed_children = [StaffPage::class]; - } + class StaffHolder extends Page + { + private static $db = []; + private static $has_one = []; + private static $allowed_children = [StaffPage::class]; + } ``` **mysite/code/StaffHolderController.php** ```php - use PageController; + use PageController; - class StaffHolderController extends PageController - { - - } + class StaffHolderController extends PageController + { + + } ``` Nothing here should be new. The *StaffPage* page type is more interesting though. Each staff member has a portrait image. We want to make a permanent connection between this image and the specific *StaffPage* (otherwise we could simply insert an image in the *$Content* field). @@ -507,37 +508,37 @@ Nothing here should be new. The *StaffPage* page type is more interesting though **mysite/code/StaffPage.php** ```php - use SilverStripe\AssetAdmin\Forms\UploadField; - use SilverStripe\Assets\Image; + use SilverStripe\AssetAdmin\Forms\UploadField; + use SilverStripe\Assets\Image; - class StaffPage extends Page - { - private static $db = []; + class StaffPage extends Page + { + private static $db = []; - private static $has_one = [ - 'Photo' => Image::class - ]; - - public function getCMSFields() - { - $fields = parent::getCMSFields(); - - $fields->addFieldToTab("Root.Images", new UploadField('Photo')); - - return $fields; - } - } + private static $has_one = [ + 'Photo' => Image::class + ]; + + public function getCMSFields() + { + $fields = parent::getCMSFields(); + + $fields->addFieldToTab("Root.Images", new UploadField('Photo')); + + return $fields; + } + } ``` **mysite/code/StaffPageController.php** ```php - use PageController; - - class StaffPageController extends PageController - { - - } + use PageController; + + class StaffPageController extends PageController + { + + } ``` Instead of adding our *Image* as a field in *$db*, we have used the *$has_one* array. This is because an *Image* is not a simple database field like all the fields we have seen so far, but has its own database table. By using the *$has_one* array, we create a relationship between the *StaffPage* table and the *Image* table by storing the id of the respective *Image* in the *StaffPage* table. @@ -561,23 +562,23 @@ The staff section templates aren't too difficult to create, thanks to the utilit **themes/simple/templates/Layout/StaffHolder.ss** ```ss - <% include SideBar %> - <div class="content-container unit size3of4 lastUnit"> - <article> - <h1>$Title</h1> - $Content - <div class="content">$Content</div> - </article> - <% loop $Children %> - <article> - <h2><a href="$Link" title="Read more on "{$Title}"">$Title</a></h2> - $Photo.ScaleWidth(150) - <p>$Content.FirstParagraph</p> - <a href="$Link" title="Read more on "{$Title}"">Read more >></a> - </article> - <% end_loop %> - $Form - </div> + <% include SideBar %> + <div class="content-container unit size3of4 lastUnit"> + <article> + <h1>$Title</h1> + $Content + <div class="content">$Content</div> + </article> + <% loop $Children %> + <article> + <h2><a href="$Link" title="Read more on "{$Title}"">$Title</a></h2> + $Photo.ScaleWidth(150) + <p>$Content.FirstParagraph</p> + <a href="$Link" title="Read more on "{$Title}"">Read more >></a> + </article> + <% end_loop %> + $Form + </div> ``` @@ -592,16 +593,16 @@ The *StaffPage* template is also very straight forward. **themes/simple/templates/Layout/StaffPage.ss** ```ss - <% include SideBar %> - <div class="content-container unit size3of4 lastUnit"> - <article> - <h1>$Title</h1> - <div class="content"> - $Photo.ScaleWidth(433) - $Content</div> - </article> - $Form - </div> + <% include SideBar %> + <div class="content-container unit size3of4 lastUnit"> + <article> + <h1>$Title</h1> + <div class="content"> + $Photo.ScaleWidth(433) + $Content</div> + </article> + $Form + </div> ``` Here we use the *ScaleWidth* method to get a different sized image from the same source image. You should now have diff --git a/docs/en/01_Tutorials/04_Site_Search.md b/docs/en/01_Tutorials/04_Site_Search.md index 6dbf77a81..6d3f87537 100644 --- a/docs/en/01_Tutorials/04_Site_Search.md +++ b/docs/en/01_Tutorials/04_Site_Search.md @@ -19,7 +19,7 @@ To enable the search engine you need to include the following code in your `mysi This will enable fulltext search on page content as well as names of all files in the `/assets` folder. ```php - FulltextSearchable::enable(); + FulltextSearchable::enable(); ``` After including that in your `_config.php` you will need to rebuild the database by visiting [http://localhost/your_site_name/dev/build](http://localhost/your_site_name/dev/build) in your web browser (replace localhost/your_site_name with a domain if applicable). This will add fulltext search columns. @@ -36,14 +36,14 @@ To add the search form, we can add `$SearchForm` anywhere in our templates. In t **themes/simple/templates/Includes/Header.ss** ```ss - ... - <% if $SearchForm %> - <span class="search-dropdown-icon">L</span> - <div class="search-bar"> - $SearchForm - </div> - <% end_if %> - <% include Navigation %> + ... + <% if $SearchForm %> + <span class="search-dropdown-icon">L</span> + <div class="search-bar"> + $SearchForm + </div> + <% end_if %> + <% include Navigation %> ``` This displays as: @@ -58,22 +58,22 @@ is applied via `FulltextSearchable::enable()` **cms/code/search/ContentControllerSearchExtension.php** ```php - use SilverStripe\Core\Extension; + use SilverStripe\Core\Extension; - class ContentControllerSearchExtension extends Extension - { - ... - - public function results($data, $form, $request) - { - $data = [ - 'Results' => $form->getResults(), - 'Query' => $form->getSearchQuery(), - 'Title' => _t('SearchForm.SearchResults', 'Search Results') - ]; - return $this->owner->customise($data)->renderWith(['Page_results', 'Page']); - } - } + class ContentControllerSearchExtension extends Extension + { + ... + + public function results($data, $form, $request) + { + $data = [ + 'Results' => $form->getResults(), + 'Query' => $form->getSearchQuery(), + 'Title' => _t('SearchForm.SearchResults', 'Search Results') + ]; + return $this->owner->customise($data)->renderWith(['Page_results', 'Page']); + } + } ``` @@ -105,56 +105,56 @@ class. *themes/simple/templates/Layout/Page_results.ss* ```ss - <div id="Content" class="searchResults"> - <h1>$Title</h1> - - <% if $Query %> - <p class="searchQuery"><strong>You searched for "{$Query}"</strong></p> - <% end_if %> - - <% if $Results %> - <ul id="SearchResults"> - <% loop $Results %> - <li> - <a class="searchResultHeader" href="$Link"> - <% if $MenuTitle %> - $MenuTitle - <% else %> - $Title - <% end_if %> - </a> - <p>$Content.LimitWordCountXML</p> - <a class="readMoreLink" href="$Link" - title="Read more about "{$Title}"" - >Read more about "{$Title}"...</a> - </li> - <% end_loop %> - </ul> - <% else %> - <p>Sorry, your search query did not return any results.</p> - <% end_if %> - - <% if $Results.MoreThanOnePage %> - <div id="PageNumbers"> - <% if $Results.NotLastPage %> - <a class="next" href="$Results.NextLink" title="View the next page">Next</a> - <% end_if %> - <% if $Results.NotFirstPage %> - <a class="prev" href="$Results.PrevLink" title="View the previous page">Prev</a> - <% end_if %> - <span> - <% loop $Results.Pages %> - <% if $CurrentBool %> - $PageNum - <% else %> - <a href="$Link" title="View page number $PageNum">$PageNum</a> - <% end_if %> - <% end_loop %> - </span> - <p>Page $Results.CurrentPage of $Results.TotalPages</p> - </div> - <% end_if %> - </div> + <div id="Content" class="searchResults"> + <h1>$Title</h1> + + <% if $Query %> + <p class="searchQuery"><strong>You searched for "{$Query}"</strong></p> + <% end_if %> + + <% if $Results %> + <ul id="SearchResults"> + <% loop $Results %> + <li> + <a class="searchResultHeader" href="$Link"> + <% if $MenuTitle %> + $MenuTitle + <% else %> + $Title + <% end_if %> + </a> + <p>$Content.LimitWordCountXML</p> + <a class="readMoreLink" href="$Link" + title="Read more about "{$Title}"" + >Read more about "{$Title}"...</a> + </li> + <% end_loop %> + </ul> + <% else %> + <p>Sorry, your search query did not return any results.</p> + <% end_if %> + + <% if $Results.MoreThanOnePage %> + <div id="PageNumbers"> + <% if $Results.NotLastPage %> + <a class="next" href="$Results.NextLink" title="View the next page">Next</a> + <% end_if %> + <% if $Results.NotFirstPage %> + <a class="prev" href="$Results.PrevLink" title="View the previous page">Prev</a> + <% end_if %> + <span> + <% loop $Results.Pages %> + <% if $CurrentBool %> + $PageNum + <% else %> + <a href="$Link" title="View page number $PageNum">$PageNum</a> + <% end_if %> + <% end_loop %> + </span> + <p>Page $Results.CurrentPage of $Results.TotalPages</p> + </div> + <% end_if %> + </div> ``` Then finally add ?flush=1 to the URL and you should see the new template. diff --git a/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md b/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md index 68dcc240f..32a854c77 100644 --- a/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md +++ b/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md @@ -20,18 +20,18 @@ Let's look at a simple example: **mysite/code/Player.php** ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $db = [ - 'PlayerNumber' => 'Int', - 'FirstName' => 'Varchar(255)', - 'LastName' => 'Text', - 'Birthday' => 'Date' - ]; - } + private static $db = [ + 'PlayerNumber' => 'Int', + 'FirstName' => 'Varchar(255)', + 'LastName' => 'Text', + 'Birthday' => 'Date' + ]; + } ``` @@ -79,18 +79,18 @@ system. Instead, it will generate a new `ID` by adding 1 to the current maximum **mysite/code/Player.php** ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $db = [ - 'PlayerNumber' => 'Int', - 'FirstName' => 'Varchar(255)', - 'LastName' => 'Text', - 'Birthday' => 'Date' - ]; - } + private static $db = [ + 'PlayerNumber' => 'Int', + 'FirstName' => 'Varchar(255)', + 'LastName' => 'Text', + 'Birthday' => 'Date' + ]; + } ``` @@ -115,13 +115,13 @@ Generates the following `SQL`. A new instance of a [DataObject](api:SilverStripe\ORM\DataObject) can be created using the `new` syntax. ```php - $player = new Player(); + $player = new Player(); ``` Or, a better way is to use the `create` method. ```php - $player = Player::create(); + $player = Player::create(); ``` <div class="notice" markdown='1'> @@ -133,22 +133,22 @@ Database columns and properties can be set as class properties on the object. Th of the values through a custom `__set()` method. ```php - $player->FirstName = "Sam"; - $player->PlayerNumber = 07; + $player->FirstName = "Sam"; + $player->PlayerNumber = 07; ``` To save the `DataObject` to the database, use the `write()` method. The first time `write()` is called, an `ID` will be set. ```php - $player->write(); + $player->write(); ``` For convenience, the `write()` method returns the record's ID. This is particularly useful when creating new records. ```php - $player = Player::create(); - $id = $player->write(); + $player = Player::create(); + $id = $player->write(); ``` ## Querying Data @@ -157,28 +157,28 @@ With the `Player` class defined we can query our data using the `ORM` or Object- shortcuts and methods for fetching, sorting and filtering data from our database. ```php - $players = Player::get(); - // returns a `DataList` containing all the `Player` objects. + $players = Player::get(); + // returns a `DataList` containing all the `Player` objects. - $player = Player::get()->byID(2); - // returns a single `Player` object instance that has the ID of 2. + $player = Player::get()->byID(2); + // returns a single `Player` object instance that has the ID of 2. - echo $player->ID; - // returns the players 'ID' column value + echo $player->ID; + // returns the players 'ID' column value - echo $player->dbObject('LastEdited')->Ago(); - // calls the `Ago` method on the `LastEdited` property. + echo $player->dbObject('LastEdited')->Ago(); + // calls the `Ago` method on the `LastEdited` property. ``` The `ORM` uses a "fluent" syntax, where you specify a query by chaining together different methods. Two common methods are `filter()` and `sort()`: ```php - $members = Player::get()->filter([ - 'FirstName' => 'Sam' - ])->sort('Surname'); + $members = Player::get()->filter([ + 'FirstName' => 'Sam' + ])->sort('Surname'); - // returns a `DataList` containing all the `Player` records that have the `FirstName` of 'Sam' + // returns a `DataList` containing all the `Player` records that have the `FirstName` of 'Sam' ``` @@ -194,27 +194,27 @@ It's smart enough to generate a single efficient query at the last moment in tim result set in PHP. In `MySQL` the query generated by the ORM may look something like this ```php - $players = Player::get()->filter([ - 'FirstName' => 'Sam' - ]); + $players = Player::get()->filter([ + 'FirstName' => 'Sam' + ]); - $players = $players->sort('Surname'); + $players = $players->sort('Surname'); - // executes the following single query - // SELECT * FROM Player WHERE FirstName = 'Sam' ORDER BY Surname + // executes the following single query + // SELECT * FROM Player WHERE FirstName = 'Sam' ORDER BY Surname ``` This also means that getting the count of a list of objects will be done with a single, efficient query. ```php - $players = Player::get()->filter([ - 'FirstName' => 'Sam' - ])->sort('Surname'); - - // This will create an single SELECT COUNT query - // SELECT COUNT(*) FROM Player WHERE FirstName = 'Sam' - echo $players->Count(); + $players = Player::get()->filter([ + 'FirstName' => 'Sam' + ])->sort('Surname'); + + // This will create an single SELECT COUNT query + // SELECT COUNT(*) FROM Player WHERE FirstName = 'Sam' + echo $players->Count(); ``` @@ -223,21 +223,21 @@ This also means that getting the count of a list of objects will be done with a `get()` returns a `DataList` instance. You can loop over `DataList` instances in both PHP and templates. ```php - $players = Player::get(); + $players = Player::get(); - foreach($players as $player) { - echo $player->FirstName; - } + foreach($players as $player) { + echo $player->FirstName; + } ``` Notice that we can step into the loop safely without having to check if `$players` exists. The `get()` call is robust, and will at worst return an empty `DataList` object. If you do want to check if the query returned any records, you can use the `exists()` method, e.g. ```php - $players = Player::get(); + $players = Player::get(); - if($players->exists()) { - // do something here - } + if($players->exists()) { + // do something here + } ``` See the [Lists](lists) documentation for more information on dealing with [SS_List](api:SilverStripe\ORM\SS_List) instances. @@ -248,16 +248,16 @@ There are a couple of ways of getting a single DataObject from the ORM. If you k can use `byID($id)`: ```php - $player = Player::get()->byID(5); + $player = Player::get()->byID(5); ``` `get()` returns a [DataList](api:SilverStripe\ORM\DataList) instance. You can use operations on that to get back a single record. ```php - $players = Player::get(); + $players = Player::get(); - $first = $players->first(); - $last = $players->last(); + $first = $players->first(); + $last = $players->last(); ``` ## Sorting @@ -265,38 +265,38 @@ can use `byID($id)`: If would like to sort the list by `FirstName` in a ascending way (from A to Z). ```php - // Sort can either be Ascending (ASC) or Descending (DESC) - $players = Player::get()->sort('FirstName', 'ASC'); + // Sort can either be Ascending (ASC) or Descending (DESC) + $players = Player::get()->sort('FirstName', 'ASC'); - // Ascending is implied - $players = Player::get()->sort('FirstName'); + // Ascending is implied + $players = Player::get()->sort('FirstName'); ``` To reverse the sort ```php - $players = Player::get()->sort('FirstName', 'DESC'); + $players = Player::get()->sort('FirstName', 'DESC'); - // or.. - $players = Player::get()->sort('FirstName', 'ASC')->reverse(); + // or.. + $players = Player::get()->sort('FirstName', 'ASC')->reverse(); ``` However you might have several entries with the same `FirstName` and would like to sort them by `FirstName` and `LastName` ```php - $players = Players::get()->sort([ - 'FirstName' => 'ASC', - 'LastName'=>'ASC' - ]); + $players = Players::get()->sort([ + 'FirstName' => 'ASC', + 'LastName'=>'ASC' + ]); ``` You can also sort randomly. Using the `DB` class, you can get the random sort method per database type. ```php - $random = DB::get_conn()->random(); - $players = Player::get()->sort($random) + $random = DB::get_conn()->random(); + $players = Player::get()->sort($random) ``` ## Filtering Results @@ -304,9 +304,9 @@ You can also sort randomly. Using the `DB` class, you can get the random sort me The `filter()` method filters the list of objects that gets returned. ```php - $players = Player::get()->filter([ - 'FirstName' => 'Sam' - ]); + $players = Player::get()->filter([ + 'FirstName' => 'Sam' + ]); ``` @@ -319,29 +319,29 @@ value that you want to filter to. So, this would return only those players called "Sam Minnée". ```php - $players = Player::get()->filter([ - 'FirstName' => 'Sam', - 'LastName' => 'Minnée', - ]); + $players = Player::get()->filter([ + 'FirstName' => 'Sam', + 'LastName' => 'Minnée', + ]); - // SELECT * FROM Player WHERE FirstName = 'Sam' AND LastName = 'Minnée' + // SELECT * FROM Player WHERE FirstName = 'Sam' AND LastName = 'Minnée' ``` There is also a shorthand way of getting Players with the FirstName of Sam. ```php - $players = Player::get()->filter('FirstName', 'Sam'); + $players = Player::get()->filter('FirstName', 'Sam'); ``` Or if you want to find both Sam and Sig. ```php - $players = Player::get()->filter( - 'FirstName', ['Sam', 'Sig'] - ); + $players = Player::get()->filter( + 'FirstName', ['Sam', 'Sig'] + ); - // SELECT * FROM Player WHERE FirstName IN ('Sam', 'Sig') + // SELECT * FROM Player WHERE FirstName IN ('Sam', 'Sig') ``` @@ -349,10 +349,10 @@ You can use [SearchFilters](searchfilters) to add additional behavior to your `f exact match. ```php - $players = Player::get()->filter([ - 'FirstName:StartsWith' => 'S' - 'PlayerNumber:GreaterThan' => '10' - ]); + $players = Player::get()->filter([ + 'FirstName:StartsWith' => 'S' + 'PlayerNumber:GreaterThan' => '10' + ]); ``` @@ -361,37 +361,37 @@ exact match. Use the `filterAny()` method to match multiple criteria non-exclusively (with an "OR" disjunctive), ```php - $players = Player::get()->filterAny([ - 'FirstName' => 'Sam', - 'Age' => 17, - ]); + $players = Player::get()->filterAny([ + 'FirstName' => 'Sam', + 'Age' => 17, + ]); - // SELECT * FROM Player WHERE ("FirstName" = 'Sam' OR "Age" = '17') + // SELECT * FROM Player WHERE ("FirstName" = 'Sam' OR "Age" = '17') ``` You can combine both conjunctive ("AND") and disjunctive ("OR") statements. ```php - $players = Player::get() - ->filter([ - 'LastName' => 'Minnée' - ]) - ->filterAny([ - 'FirstName' => 'Sam', - 'Age' => 17, - ]); - // SELECT * FROM Player WHERE ("LastName" = 'Minnée' AND ("FirstName" = 'Sam' OR "Age" = '17')) + $players = Player::get() + ->filter([ + 'LastName' => 'Minnée' + ]) + ->filterAny([ + 'FirstName' => 'Sam', + 'Age' => 17, + ]); + // SELECT * FROM Player WHERE ("LastName" = 'Minnée' AND ("FirstName" = 'Sam' OR "Age" = '17')) ``` You can use [SearchFilters](searchfilters) to add additional behavior to your `filterAny` command. ```php - $players = Player::get()->filterAny([ - 'FirstName:StartsWith' => 'S' - 'PlayerNumber:GreaterThan' => '10' - ]); + $players = Player::get()->filterAny([ + 'FirstName:StartsWith' => 'S' + 'PlayerNumber:GreaterThan' => '10' + ]); ``` @@ -406,19 +406,19 @@ For instance, the below code will select only values that do not match the given ```php - $players = Player::get()->filter('FirstName:not', 'Sam'); - // ... WHERE "FirstName" != 'Sam' OR "FirstName" IS NULL - // Returns rows with any value (even null) other than Sam + $players = Player::get()->filter('FirstName:not', 'Sam'); + // ... WHERE "FirstName" != 'Sam' OR "FirstName" IS NULL + // Returns rows with any value (even null) other than Sam ``` If null values should be excluded, include the null in your check. ```php - $players = Player::get()->filter('FirstName:not', ['Sam', null]); - // ... WHERE "FirstName" != 'Sam' AND "FirstName" IS NOT NULL - // Only returns non-null values for "FirstName" that aren't Sam. - // Strictly the IS NOT NULL isn't necessary, but is included for explicitness + $players = Player::get()->filter('FirstName:not', ['Sam', null]); + // ... WHERE "FirstName" != 'Sam' AND "FirstName" IS NOT NULL + // Only returns non-null values for "FirstName" that aren't Sam. + // Strictly the IS NOT NULL isn't necessary, but is included for explicitness ``` @@ -426,9 +426,9 @@ It is also often useful to filter by all rows with either empty or null for a gi ```php - $players = Player::get()->filter('FirstName', [null, '']); - // ... WHERE "FirstName" == '' OR "FirstName" IS NULL - // Returns rows with FirstName which is either empty or null + $players = Player::get()->filter('FirstName', [null, '']); + // ... WHERE "FirstName" == '' OR "FirstName" IS NULL + // Returns rows with FirstName which is either empty or null ``` @@ -437,17 +437,17 @@ It is also often useful to filter by all rows with either empty or null for a gi You can use aggregate expressions in your filters, as well. ```php - // get the teams that have more than 10 players - $teams = Team::get()->filter('Players.Count():GreaterThan', 10); + // get the teams that have more than 10 players + $teams = Team::get()->filter('Players.Count():GreaterThan', 10); - // get the teams with at least one player who has scored 5 or more points - $teams = Team::get()->filter('Players.Min(PointsScored):GreaterThanOrEqual', 5); + // get the teams with at least one player who has scored 5 or more points + $teams = Team::get()->filter('Players.Min(PointsScored):GreaterThanOrEqual', 5); - // get the teams with players who are averaging more than 15 points - $teams = Team::get()->filter('Players.Avg(PointsScored):GreaterThan', 15); + // get the teams with players who are averaging more than 15 points + $teams = Team::get()->filter('Players.Avg(PointsScored):GreaterThan', 15); - // get the teams whose players have scored less than 300 points combined - $teams = Team::get()->filter('Players.Sum(PointsScored):LessThan', 300); + // get the teams whose players have scored less than 300 points combined + $teams = Team::get()->filter('Players.Sum(PointsScored):LessThan', 300); ``` ### filterByCallback @@ -467,9 +467,9 @@ for each record, if the callback returns true, this record will be added to the The below example will get all `Players` aged over 10. ```php - $players = Player::get()->filterByCallback(function($item, $list) { - return ($item->Age() > 10); - }); + $players = Player::get()->filterByCallback(function($item, $list) { + return ($item->Age() > 10); + }); ``` ### Exclude @@ -477,49 +477,49 @@ The below example will get all `Players` aged over 10. The `exclude()` method is the opposite to the filter in that it removes entries from a list. ```php - $players = Player::get()->exclude('FirstName', 'Sam'); + $players = Player::get()->exclude('FirstName', 'Sam'); - // SELECT * FROM Player WHERE FirstName != 'Sam' + // SELECT * FROM Player WHERE FirstName != 'Sam' ``` Remove both Sam and Sig.. ```php - $players = Player::get()->exclude( - 'FirstName', ['Sam','Sig'] - ); + $players = Player::get()->exclude( + 'FirstName', ['Sam','Sig'] + ); ``` `Exclude` follows the same pattern as filter, so for removing only Sam Minnée from the list: ```php - $players = Player::get()->exclude([ - 'FirstName' => 'Sam', - 'Surname' => 'Minnée', - ]); + $players = Player::get()->exclude([ + 'FirstName' => 'Sam', + 'Surname' => 'Minnée', + ]); ``` And removing Sig and Sam with that are either age 17 or 43. ```php - $players = Player::get()->exclude([ - 'FirstName' => ['Sam', 'Sig'], - 'Age' => [17, 43] - ]); + $players = Player::get()->exclude([ + 'FirstName' => ['Sam', 'Sig'], + 'Age' => [17, 43] + ]); - // SELECT * FROM Player WHERE ("FirstName" NOT IN ('Sam','Sig) OR "Age" NOT IN ('17', '43')); + // SELECT * FROM Player WHERE ("FirstName" NOT IN ('Sam','Sig) OR "Age" NOT IN ('17', '43')); ``` You can use [SearchFilters](searchfilters) to add additional behavior to your `exclude` command. ```php - $players = Player::get()->exclude([ - 'FirstName:EndsWith' => 'S' - 'PlayerNumber:LessThanOrEqual' => '10' - ]); + $players = Player::get()->exclude([ + 'FirstName:EndsWith' => 'S' + 'PlayerNumber:LessThanOrEqual' => '10' + ]); ``` @@ -528,18 +528,18 @@ You can use [SearchFilters](searchfilters) to add additional behavior to your `e You can subtract entries from a [DataList](api:SilverStripe\ORM\DataList) by passing in another DataList to `subtract()` ```php - $sam = Player::get()->filter('FirstName', 'Sam'); - $players = Player::get(); + $sam = Player::get()->filter('FirstName', 'Sam'); + $players = Player::get(); - $noSams = $players->subtract($sam); + $noSams = $players->subtract($sam); ``` Though for the above example it would probably be easier to use `filter()` and `exclude()`. A better use case could be when you want to find all the members that does not exist in a Group. ```php - // ... Finding all members that does not belong to $group. - $otherMembers = Member::get()->subtract($group->Members()); + // ... Finding all members that does not belong to $group. + $otherMembers = Member::get()->subtract($group->Members()); ``` ### Limit @@ -547,7 +547,7 @@ when you want to find all the members that does not exist in a Group. You can limit the amount of records returned in a DataList by using the `limit()` method. ```php - $members = Member::get()->limit(5); + $members = Member::get()->limit(5); ``` `limit()` accepts two arguments, the first being the amount of results you want returned, with an optional second @@ -555,8 +555,8 @@ parameter to specify the offset, which allows you to tell the system where to st offset, if not provided as an argument, will default to 0. ```php - // Return 10 members with an offset of 4 (starting from the 5th result). - $members = Member::get()->sort('Surname')->limit(10, 4); + // Return 10 members with an offset of 4 (starting from the 5th result). + $members = Member::get()->sort('Surname')->limit(10, 4); ``` <div class="alert"> @@ -573,11 +573,11 @@ For instance, the below model will be stored in the table name `BannerImage` ```php - namespace SilverStripe\BannerManager; - class BannerImage extends \DataObject - { - private static $table_name = 'BannerImage'; - } + namespace SilverStripe\BannerManager; + class BannerImage extends \DataObject + { + private static $table_name = 'BannerImage'; + } ``` Note that any model class which does not explicitly declare a `table_name` config option will have a name @@ -608,14 +608,14 @@ table and column. ```php - public function countDuplicates($model, $fieldToCheck) - { - $table = DataObject::getSchema()->tableForField($model, $field); - $query = new SQLSelect(); - $query->setFrom("\"{$table}\""); - $query->setWhere(["\"{$table}\".\"{$field}\"" => $model->$fieldToCheck]); - return $query->count(); - } + public function countDuplicates($model, $fieldToCheck) + { + $table = DataObject::getSchema()->tableForField($model, $field); + $query = new SQLSelect(); + $query->setFrom("\"{$table}\""); + $query->setWhere(["\"{$table}\".\"{$field}\"" => $model->$fieldToCheck]); + return $query->count(); + } ``` ### Raw SQL @@ -635,7 +635,7 @@ you need it to, you may also consider extending the ORM with new data types or f You can specify a WHERE clause fragment (that will be combined with other filters using AND) with the `where()` method: ```php - $members = Member::get()->where("\"FirstName\" = 'Sam'") + $members = Member::get()->where("\"FirstName\" = 'Sam'") ``` #### Joining Tables @@ -647,12 +647,12 @@ You can specify a join with the `innerJoin` and `leftJoin` methods. Both of the * An optional alias. ```php - // Without an alias - $members = Member::get() - ->leftJoin("Group_Members", "\"Group_Members\".\"MemberID\" = \"Member\".\"ID\""); + // Without an alias + $members = Member::get() + ->leftJoin("Group_Members", "\"Group_Members\".\"MemberID\" = \"Member\".\"ID\""); - $members = Member::get() - ->innerJoin("Group_Members", "\"Rel\".\"MemberID\" = \"Member\".\"ID\"", "Rel"); + $members = Member::get() + ->innerJoin("Group_Members", "\"Rel\".\"MemberID\" = \"Member\".\"ID\"", "Rel"); ``` <div class="alert" markdown="1"> @@ -666,15 +666,15 @@ Define the default values for all the `$db` fields. This example sets the "Statu whenever a new object is created. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $defaults = [ - "Status" => 'Active', - ]; - } + private static $defaults = [ + "Status" => 'Active', + ]; + } ``` @@ -693,20 +693,20 @@ time. For example, suppose we have the following set of classes: ```php - use SilverStripe\CMS\Model\SiteTree; - use Page; + use SilverStripe\CMS\Model\SiteTree; + use Page; - class Page extends SiteTree - { + class Page extends SiteTree + { - } - class NewsPage extends Page - { + } + class NewsPage extends Page + { - private static $db = [ - 'Summary' => 'Text' - ]; - } + private static $db = [ + 'Summary' => 'Text' + ]; + } ``` @@ -714,26 +714,26 @@ The data for the following classes would be stored across the following tables: ```yml - SiteTree: - - ID: Int - - ClassName: Enum('SiteTree', 'Page', 'NewsPage') - - Created: Datetime - - LastEdited: Datetime - - Title: Varchar - - Content: Text - NewsPage: - - ID: Int - - Summary: Text + SiteTree: + - ID: Int + - ClassName: Enum('SiteTree', 'Page', 'NewsPage') + - Created: Datetime + - LastEdited: Datetime + - Title: Varchar + - Content: Text + NewsPage: + - ID: Int + - Summary: Text ``` Accessing the data is transparent to the developer. ```php - $news = NewsPage::get(); + $news = NewsPage::get(); - foreach($news as $article) { - echo $article->Title; - } + foreach($news as $article) { + echo $article->Title; + } ``` The way the ORM stores the data is this: diff --git a/docs/en/02_Developer_Guides/00_Model/02_Relations.md b/docs/en/02_Developer_Guides/00_Model/02_Relations.md index 64e1babf8..47304c52d 100644 --- a/docs/en/02_Developer_Guides/00_Model/02_Relations.md +++ b/docs/en/02_Developer_Guides/00_Model/02_Relations.md @@ -16,26 +16,26 @@ A 1-to-1 relation creates a database-column called "`<relationship-name>`ID", in "TeamID" on the "Player"-table. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { + class Team extends DataObject + { - private static $db = [ - 'Title' => 'Varchar' - ]; + private static $db = [ + 'Title' => 'Varchar' + ]; - private static $has_many = [ - 'Players' => 'Player' - ]; - } - class Player extends DataObject - { + private static $has_many = [ + 'Players' => 'Player' + ]; + } + class Player extends DataObject + { - private static $has_one = [ - "Team" => "Team", - ]; - } + private static $has_one = [ + "Team" => "Team", + ]; + } ``` @@ -45,24 +45,24 @@ and provides a short syntax for accessing the related object. At the database level, the `has_one` creates a `TeamID` field on `Player`. A `has_many` field does not impose any database changes. It merely injects a new method into the class to access the related records (in this case, `Players()`) ```php - $player = Player::get()->byId(1); + $player = Player::get()->byId(1); - $team = $player->Team(); - // returns a 'Team' instance. + $team = $player->Team(); + // returns a 'Team' instance. - echo $player->Team()->Title; - // returns the 'Title' column on the 'Team' or `getTitle` if it exists. + echo $player->Team()->Title; + // returns the 'Title' column on the 'Team' or `getTitle` if it exists. ``` The relationship can also be navigated in [templates](../templates). ```ss - <% with $Player %> - <% if $Team %> - Plays for $Team.Title - <% end_if %> - <% end_with %> + <% with $Player %> + <% if $Team %> + Plays for $Team.Title + <% end_if %> + <% end_with %> ``` ## Polymorphic has_one @@ -77,30 +77,30 @@ To specify that a has_one relation is polymorphic set the type to 'DataObject'. Ideally, the associated has_many (or belongs_to) should be specified with dot notation. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { - private static $has_many = [ - "Fans" => "Fan.FanOf" - ]; - } - class Team extends DataObject - { - private static $has_many = [ - "Fans" => "Fan.FanOf" - ]; - } + class Player extends DataObject + { + private static $has_many = [ + "Fans" => "Fan.FanOf" + ]; + } + class Team extends DataObject + { + private static $has_many = [ + "Fans" => "Fan.FanOf" + ]; + } - // Type of object returned by $fan->FanOf() will vary - class Fan extends DataObject - { + // Type of object returned by $fan->FanOf() will vary + class Fan extends DataObject + { - // Generates columns FanOfID and FanOfClass - private static $has_one = [ - "FanOf" => "DataObject" - ]; - } + // Generates columns FanOfID and FanOfClass + private static $has_one = [ + "FanOf" => "DataObject" + ]; + } ``` @@ -122,26 +122,26 @@ available on both ends. </div> ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { + class Team extends DataObject + { - private static $db = [ - 'Title' => 'Varchar' - ]; + private static $db = [ + 'Title' => 'Varchar' + ]; - private static $has_many = [ - 'Players' => 'Player' - ]; - } - class Player extends DataObject - { + private static $has_many = [ + 'Players' => 'Player' + ]; + } + class Player extends DataObject + { - private static $has_one = [ - "Team" => "Team", - ]; - } + private static $has_one = [ + "Team" => "Team", + ]; + } ``` @@ -149,40 +149,40 @@ Much like the `has_one` relationship, `has_many` can be navigated through the `O you will get an instance of [HasManyList](api:SilverStripe\ORM\HasManyList) rather than the object. ```php - $team = Team::get()->first(); + $team = Team::get()->first(); - echo $team->Players(); - // [HasManyList] + echo $team->Players(); + // [HasManyList] - echo $team->Players()->Count(); - // returns '14'; + echo $team->Players()->Count(); + // returns '14'; - foreach($team->Players() as $player) { - echo $player->FirstName; - } + foreach($team->Players() as $player) { + echo $player->FirstName; + } ``` To specify multiple `$has_many` to the same object you can use dot notation to distinguish them like below: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Person extends DataObject - { + class Person extends DataObject + { - private static $has_many = [ - "Managing" => "Company.Manager", - "Cleaning" => "Company.Cleaner", - ]; - } - class Company extends DataObject - { + private static $has_many = [ + "Managing" => "Company.Manager", + "Cleaning" => "Company.Cleaner", + ]; + } + class Company extends DataObject + { - private static $has_one = [ - "Manager" => "Person", - "Cleaner" => "Person" - ]; - } + private static $has_one = [ + "Manager" => "Person", + "Cleaner" => "Person" + ]; + } ``` @@ -191,14 +191,14 @@ named. If you're using the default scaffolded form fields with multiple `has_one` relationships, you will end up with a CMS field for each relation. If you don't want these you can remove them by their IDs: - :::php +```php public function getCMSFields() { $fields = parent::getCMSFields(); $fields->removeByName(array('ManagerID', 'CleanerID')); return $fields; } - +``` ## belongs_to @@ -211,22 +211,22 @@ Similarly with `$has_many`, dot notation can be used to explicitly specify the ` This is not mandatory unless the relationship would be otherwise ambiguous. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { - - private static $has_one = [ - 'Coach' => 'Coach' - ]; - } - class Coach extends DataObject - { - - private static $belongs_to = [ - 'Team' => 'Team.Coach' - ]; - } + class Team extends DataObject + { + + private static $has_one = [ + 'Coach' => 'Coach' + ]; + } + class Coach extends DataObject + { + + private static $belongs_to = [ + 'Team' => 'Team.Coach' + ]; + } ``` @@ -246,10 +246,10 @@ The only difference being you will get an instance of [ManyManyList](api:SilverS [ManyManyThroughList](api:SilverStripe\ORM\ManyManyThroughList) rather than the object. ```php - $team = Team::get()->byId(1); + $team = Team::get()->byId(1); - $supporters = $team->Supporters(); - // returns a 'ManyManyList' instance. + $supporters = $team->Supporters(); + // returns a 'ManyManyList' instance. ``` ### Automatic many_many table @@ -263,26 +263,26 @@ config to add extra columns. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { - private static $many_many = [ - "Supporters" => "Supporter", - ]; - private static $many_many_extraFields = [ - 'Supporters' => [ - 'Ranking' => 'Int' - ] - ]; - } - class Supporter extends DataObject - { + class Team extends DataObject + { + private static $many_many = [ + "Supporters" => "Supporter", + ]; + private static $many_many_extraFields = [ + 'Supporters' => [ + 'Ranking' => 'Int' + ] + ]; + } + class Supporter extends DataObject + { - private static $belongs_many_many = [ - "Supports" => "Team", - ]; - } + private static $belongs_many_many = [ + "Supports" => "Team", + ]; + } ``` ### many_many through relationship joined on a separate DataObject @@ -308,35 +308,35 @@ or child record. The syntax for `belongs_many_many` is unchanged. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { - private static $many_many = [ - "Supporters" => [ - 'through' => 'TeamSupporter', - 'from' => 'Team', - 'to' => 'Supporter', - ] - ]; - } - class Supporter extends DataObject - { - private static $belongs_many_many = [ - "Supports" => "Team", - ]; - } - class TeamSupporter extends DataObject - { - private static $db = [ - 'Ranking' => 'Int', - ]; - - private static $has_one = [ - 'Team' => 'Team', - 'Supporter' => 'Supporter' - ]; - } + class Team extends DataObject + { + private static $many_many = [ + "Supporters" => [ + 'through' => 'TeamSupporter', + 'from' => 'Team', + 'to' => 'Supporter', + ] + ]; + } + class Supporter extends DataObject + { + private static $belongs_many_many = [ + "Supports" => "Team", + ]; + } + class TeamSupporter extends DataObject + { + private static $db = [ + 'Ranking' => 'Int', + ]; + + private static $has_one = [ + 'Team' => 'Team', + 'Supporter' => 'Supporter' + ]; + } ``` In order to filter on the join table during queries, you can use the class name of the joining table @@ -344,8 +344,8 @@ for any sql conditions. ```php - $team = Team::get()->byId(1); - $supporters = $team->Supporters()->where(['"TeamSupporter"."Ranking"' => 1]); + $team = Team::get()->byId(1); + $supporters = $team->Supporters()->where(['"TeamSupporter"."Ranking"' => 1]); ``` Note: ->filter() currently does not support joined fields natively due to the fact that the @@ -359,11 +359,11 @@ The joined record can be accessed via `Join` or `TeamSupporter` property (many_m ```ss - <% with $Supporter %> - <% loop $Supports %> - Supports $Title <% if $TeamSupporter %>(rank $TeamSupporter.Ranking)<% end_if %> - <% end_if %> - <% end_with %> + <% with $Supporter %> + <% loop $Supports %> + Supports $Title <% if $TeamSupporter %>(rank $TeamSupporter.Ranking)<% end_if %> + <% end_if %> + <% end_with %> ``` You can also use `$Join` in place of the join class alias (`$TeamSupporter`), if your template @@ -379,24 +379,24 @@ distinguish them like below: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Category extends DataObject - { - - private static $many_many = [ - 'Products' => 'Product', - 'FeaturedProducts' => 'Product' - ]; - } - class Product extends DataObject - { - - private static $belongs_many_many = [ - 'Categories' => 'Category.Products', - 'FeaturedInCategories' => 'Category.FeaturedProducts' - ]; - } + class Category extends DataObject + { + + private static $many_many = [ + 'Products' => 'Product', + 'FeaturedProducts' => 'Product' + ]; + } + class Product extends DataObject + { + + private static $belongs_many_many = [ + 'Categories' => 'Category.Products', + 'FeaturedInCategories' => 'Category.FeaturedProducts' + ]; + } ``` @@ -413,15 +413,15 @@ encapsulated by [HasManyList](api:SilverStripe\ORM\HasManyList) and [ManyManyLis and `remove()` method. ```php - $team = Team::get()->byId(1); + $team = Team::get()->byId(1); - // create a new supporter - $supporter = new Supporter(); - $supporter->Name = "Foo"; - $supporter->write(); + // create a new supporter + $supporter = new Supporter(); + $supporter->Name = "Foo"; + $supporter->write(); - // add the supporter. - $team->Supporters()->add($supporter); + // add the supporter. + $team->Supporters()->add($supporter); ``` ## Custom Relations @@ -432,20 +432,20 @@ You can use the ORM to get a filtered result list without writing any SQL. For e See [DataObject::$has_many](api:SilverStripe\ORM\DataObject::$has_many) for more info on the described relations. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { + class Team extends DataObject + { - private static $has_many = [ - "Players" => "Player" - ]; - - public function ActivePlayers() - { - return $this->Players()->filter('Status', 'Active'); - } - } + private static $has_many = [ + "Players" => "Player" + ]; + + public function ActivePlayers() + { + return $this->Players()->filter('Status', 'Active'); + } + } ``` diff --git a/docs/en/02_Developer_Guides/00_Model/03_Lists.md b/docs/en/02_Developer_Guides/00_Model/03_Lists.md index c812c4190..369bea6c5 100644 --- a/docs/en/02_Developer_Guides/00_Model/03_Lists.md +++ b/docs/en/02_Developer_Guides/00_Model/03_Lists.md @@ -12,32 +12,32 @@ modify. [SS_List](api:SilverStripe\ORM\SS_List) implements `IteratorAggregate`, allowing you to loop over the instance. ```php - $members = Member::get(); + $members = Member::get(); - foreach($members as $member) { - echo $member->Name; - } + foreach($members as $member) { + echo $member->Name; + } ``` Or in the template engine: ```ss - <% loop $Members %> - <!-- --> - <% end_loop %> + <% loop $Members %> + <!-- --> + <% end_loop %> ``` ## Finding an item by value. ```php - // $list->find($key, $value); + // $list->find($key, $value); - // - $members = Member::get(); + // + $members = Member::get(); - echo $members->find('ID', 4)->FirstName; - // returns 'Sam' + echo $members->find('ID', 4)->FirstName; + // returns 'Sam' ``` ## Maps @@ -45,35 +45,35 @@ Or in the template engine: A map is an array where the array indexes contain data as well as the values. You can build a map from any list ```php - $members = Member::get()->map('ID', 'FirstName'); - - // $members = array( - // 1 => 'Sam' - // 2 => 'Sig' - // 3 => 'Will' - // ); + $members = Member::get()->map('ID', 'FirstName'); + + // $members = array( + // 1 => 'Sam' + // 2 => 'Sig' + // 3 => 'Will' + // ); ``` This functionality is provided by the [Map](api:SilverStripe\ORM\Map) class, which can be used to build a map around any `SS_List`. ```php - $members = Member::get(); - $map = new Map($members, 'ID', 'FirstName'); + $members = Member::get(); + $map = new Map($members, 'ID', 'FirstName'); ``` ## Column ```php - $members = Member::get(); + $members = Member::get(); - echo $members->column('Email'); + echo $members->column('Email'); - // returns array( - // 'sam@silverstripe.com', - // 'sig@silverstripe.com', - // 'will@silverstripe.com' - // ); + // returns array( + // 'sam@silverstripe.com', + // 'sig@silverstripe.com', + // 'will@silverstripe.com' + // ); ``` @@ -82,15 +82,15 @@ This functionality is provided by the [Map](api:SilverStripe\ORM\Map) class, whi [ArrayList](api:SilverStripe\ORM\ArrayList) exists to wrap a standard PHP array in the same API as a database backed list. ```php - $sam = Member::get()->byId(5); - $sig = Member::get()->byId(6); + $sam = Member::get()->byId(5); + $sig = Member::get()->byId(6); - $list = new ArrayList(); - $list->push($sam); - $list->push($sig); + $list = new ArrayList(); + $list->push($sam); + $list->push($sig); - echo $list->Count(); - // returns '2' + echo $list->Count(); + // returns '2' ``` diff --git a/docs/en/02_Developer_Guides/00_Model/04_Data_Types_and_Casting.md b/docs/en/02_Developer_Guides/00_Model/04_Data_Types_and_Casting.md index 324b28287..e7faf71f5 100644 --- a/docs/en/02_Developer_Guides/00_Model/04_Data_Types_and_Casting.md +++ b/docs/en/02_Developer_Guides/00_Model/04_Data_Types_and_Casting.md @@ -14,18 +14,18 @@ In the `Player` example, we have four database columns each with a different dat **mysite/code/Player.php** ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $db = [ - 'PlayerNumber' => 'Int', - 'FirstName' => 'Varchar(255)', - 'LastName' => 'Text', - 'Birthday' => 'Date' - ]; - } + private static $db = [ + 'PlayerNumber' => 'Int', + 'FirstName' => 'Varchar(255)', + 'LastName' => 'Text', + 'Birthday' => 'Date' + ]; + } ``` @@ -55,21 +55,21 @@ For complex default values for newly instantiated objects see [Dynamic Default V For simple values you can make use of the `$defaults` array. For example: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Car extends DataObject - { - - private static $db = [ - 'Wheels' => 'Int', - 'Condition' => 'Enum(array("New","Fair","Junk"))' - ]; - - private static $defaults = [ - 'Wheels' => 4, - 'Condition' => 'New' - ]; - } + class Car extends DataObject + { + + private static $db = [ + 'Wheels' => 'Int', + 'Condition' => 'Enum(array("New","Fair","Junk"))' + ]; + + private static $defaults = [ + 'Wheels' => 4, + 'Condition' => 'New' + ]; + } ``` @@ -88,17 +88,17 @@ For enum values, it's the second parameter. For example: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Car extends DataObject - { - - private static $db = [ - 'Wheels' => 'Int(4)', - 'Condition' => 'Enum(array("New","Fair","Junk"), "New")', - 'Make' => 'Varchar(["default" => "Honda"]), - ); - } + class Car extends DataObject + { + + private static $db = [ + 'Wheels' => 'Int(4)', + 'Condition' => 'Enum(array("New","Fair","Junk"), "New")', + 'Make' => 'Varchar(["default" => "Honda"]), + ); + } ``` @@ -113,34 +113,34 @@ object we can control the formatting and it allows us to call methods defined fr **mysite/code/Player.php** ```php - use SilverStripe\ORM\FieldType\DBField; - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\FieldType\DBField; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - .. + .. - public function getName() - { - return DBField::create_field('Varchar', $this->FirstName . ' '. $this->LastName); - } - } + public function getName() + { + return DBField::create_field('Varchar', $this->FirstName . ' '. $this->LastName); + } + } ``` Then we can refer to a new `Name` column on our `Player` instances. In templates we don't need to use the `get` prefix. ```php - $player = Player::get()->byId(1); + $player = Player::get()->byId(1); - echo $player->Name; - // returns "Sam Minnée" + echo $player->Name; + // returns "Sam Minnée" - echo $player->getName(); - // returns "Sam Minnée"; + echo $player->getName(); + // returns "Sam Minnée"; - echo $player->getName()->LimitCharacters(2); - // returns "Sa.." + echo $player->getName()->LimitCharacters(2); + // returns "Sa.." ``` ## Casting @@ -148,20 +148,20 @@ Then we can refer to a new `Name` column on our `Player` instances. In templates Rather than manually returning objects from your custom functions. You can use the `$casting` property. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $casting = [ - "Name" => 'Varchar', - ]; - - public function getName() - { - return $this->FirstName . ' '. $this->LastName; - } - } + private static $casting = [ + "Name" => 'Varchar', + ]; + + public function getName() + { + return $this->FirstName . ' '. $this->LastName; + } + } ``` @@ -173,14 +173,14 @@ On the most basic level, the class can be used as simple conversion class from o number. ```php - DBField::create_field('Double', 1.23456)->Round(2); // results in 1.23 + DBField::create_field('Double', 1.23456)->Round(2); // results in 1.23 ``` Of course that's much more verbose than the equivalent PHP call. The power of [DBField](api:SilverStripe\ORM\FieldType\DBField) comes with its more sophisticated helpers, like showing the time difference to the current date: ```php - DBField::create_field('Date', '1982-01-01')->TimeDiff(); // shows "30 years ago" + DBField::create_field('Date', '1982-01-01')->TimeDiff(); // shows "30 years ago" ``` ## Casting ViewableData @@ -189,26 +189,26 @@ Most objects in SilverStripe extend from [ViewableData](api:SilverStripe\View\Vi context. Through a `$casting` array, arbitrary properties and getters can be casted: ```php - use SilverStripe\View\ViewableData; + use SilverStripe\View\ViewableData; - class MyObject extends ViewableData - { - - private static $casting = [ - 'MyDate' => 'Date' - ]; + class MyObject extends ViewableData + { + + private static $casting = [ + 'MyDate' => 'Date' + ]; - public function getMyDate() - { - return '1982-01-01'; - } - } + public function getMyDate() + { + return '1982-01-01'; + } + } - $obj = new MyObject; - $obj->getMyDate(); // returns string - $obj->MyDate; // returns string - $obj->obj('MyDate'); // returns object - $obj->obj('MyDate')->InPast(); // returns boolean + $obj = new MyObject; + $obj->getMyDate(); // returns string + $obj->MyDate; // returns string + $obj->obj('MyDate'); // returns object + $obj->obj('MyDate')->InPast(); // returns boolean ``` @@ -231,19 +231,19 @@ The following example will use the result of `getStatus` instead of the 'Status' database column using `dbObject`. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $db = [ - "Status" => "Enum(array('Active', 'Injured', 'Retired'))" - ]; + private static $db = [ + "Status" => "Enum(array('Active', 'Injured', 'Retired'))" + ]; - public function getStatus() - { - return (!$this->obj("Birthday")->InPast()) ? "Unborn" : $this->dbObject('Status')->Value(); - } + public function getStatus() + { + return (!$this->obj("Birthday")->InPast()) ? "Unborn" : $this->dbObject('Status')->Value(); + } ``` diff --git a/docs/en/02_Developer_Guides/00_Model/05_Extending_DataObjects.md b/docs/en/02_Developer_Guides/00_Model/05_Extending_DataObjects.md index 4745b0ae9..0d60a1898 100644 --- a/docs/en/02_Developer_Guides/00_Model/05_Extending_DataObjects.md +++ b/docs/en/02_Developer_Guides/00_Model/05_Extending_DataObjects.md @@ -19,39 +19,39 @@ a `ModelAdmin` record. Example: Disallow creation of new players if the currently logged-in player is not a team-manager. ```php - use SilverStripe\Security\Security; - use SilverStripe\ORM\DataObject; + use SilverStripe\Security\Security; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $has_many = [ - "Teams"=>"Team" - ]; - - public function onBeforeWrite() - { - // check on first write action, aka "database row creation" (ID-property is not set) - if(!$this->isInDb()) { - $currentPlayer = Security::getCurrentUser(); + private static $has_many = [ + "Teams"=>"Team" + ]; + + public function onBeforeWrite() + { + // check on first write action, aka "database row creation" (ID-property is not set) + if(!$this->isInDb()) { + $currentPlayer = Security::getCurrentUser(); - if(!$currentPlayer->IsTeamManager()) { - user_error('Player-creation not allowed', E_USER_ERROR); - exit(); - } - } - - // check on every write action - if(!$this->record['TeamID']) { - user_error('Cannot save player without a valid team', E_USER_ERROR); - exit(); - } - - // CAUTION: You are required to call the parent-function, otherwise - // SilverStripe will not execute the request. - parent::onBeforeWrite(); - } - } + if(!$currentPlayer->IsTeamManager()) { + user_error('Player-creation not allowed', E_USER_ERROR); + exit(); + } + } + + // check on every write action + if(!$this->record['TeamID']) { + user_error('Cannot save player without a valid team', E_USER_ERROR); + exit(); + } + + // CAUTION: You are required to call the parent-function, otherwise + // SilverStripe will not execute the request. + parent::onBeforeWrite(); + } + } ``` @@ -63,27 +63,27 @@ Example: Checking for a specific [permission](permissions) to delete this type o member is logged in who belongs to a group containing the permission "PLAYER_DELETE". ```php - use SilverStripe\Security\Permission; - use SilverStripe\Security\Security; - use SilverStripe\ORM\DataObject; + use SilverStripe\Security\Permission; + use SilverStripe\Security\Security; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - private static $has_many = [ - "Teams" => "Team" - ]; - - public function onBeforeDelete() - { - if(!Permission::check('PLAYER_DELETE')) { - Security::permissionFailure($this); - exit(); - } - - parent::onBeforeDelete(); - } - } + private static $has_many = [ + "Teams" => "Team" + ]; + + public function onBeforeDelete() + { + if(!Permission::check('PLAYER_DELETE')) { + Security::permissionFailure($this); + exit(); + } + + parent::onBeforeDelete(); + } + } ``` diff --git a/docs/en/02_Developer_Guides/00_Model/06_SearchFilters.md b/docs/en/02_Developer_Guides/00_Model/06_SearchFilters.md index 4be1a13d3..6babd8259 100644 --- a/docs/en/02_Developer_Guides/00_Model/06_SearchFilters.md +++ b/docs/en/02_Developer_Guides/00_Model/06_SearchFilters.md @@ -17,17 +17,17 @@ you can put on field names to change this behavior. These are represented as `Se An example of a `SearchFilter` in use: ```php - // fetch any player that starts with a S - $players = Player::get()->filter([ - 'FirstName:StartsWith' => 'S', - 'PlayerNumber:GreaterThan' => '10' - ]); + // fetch any player that starts with a S + $players = Player::get()->filter([ + 'FirstName:StartsWith' => 'S', + 'PlayerNumber:GreaterThan' => '10' + ]); - // to fetch any player that's name contains the letter 'z' - $players = Player::get()->filterAny([ - 'FirstName:PartialMatch' => 'z', - 'LastName:PartialMatch' => 'z' - ]); + // to fetch any player that's name contains the letter 'z' + $players = Player::get()->filterAny([ + 'FirstName:PartialMatch' => 'z', + 'LastName:PartialMatch' => 'z' + ]); ``` @@ -45,22 +45,22 @@ config: ```yaml - SilverStripe\Core\Injector\Injector: - DataListFilter.CustomMatch: - class: MyVendor/Search/CustomMatchFilter + SilverStripe\Core\Injector\Injector: + DataListFilter.CustomMatch: + class: MyVendor/Search/CustomMatchFilter ``` The following is a query which will return everyone whose first name starts with "S", either lowercase or uppercase: ```php - $players = Player::get()->filter([ - 'FirstName:StartsWith:nocase' => 'S' - ]); + $players = Player::get()->filter([ + 'FirstName:StartsWith:nocase' => 'S' + ]); - // use :not to perform a converse operation to filter anything but a 'W' - $players = Player::get()->filter([ - 'FirstName:StartsWith:not' => 'W' - ]); + // use :not to perform a converse operation to filter anything but a 'W' + $players = Player::get()->filter([ + 'FirstName:StartsWith:not' => 'W' + ]); ``` diff --git a/docs/en/02_Developer_Guides/00_Model/07_Permissions.md b/docs/en/02_Developer_Guides/00_Model/07_Permissions.md index bca9624d8..21ec3a66d 100644 --- a/docs/en/02_Developer_Guides/00_Model/07_Permissions.md +++ b/docs/en/02_Developer_Guides/00_Model/07_Permissions.md @@ -17,32 +17,32 @@ code. </div> ```php - use SilverStripe\Security\Permission; - use SilverStripe\ORM\DataObject; + use SilverStripe\Security\Permission; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { - - public function canView($member = null) - { - return Permission::check('CMS_ACCESS_CMSMain', 'any', $member); - } + 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 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 canDelete($member = null) + { + return Permission::check('CMS_ACCESS_CMSMain', 'any', $member); + } - public function canCreate($member = null) - { - return Permission::check('CMS_ACCESS_CMSMain', 'any', $member); - } - } + public function canCreate($member = null) + { + return Permission::check('CMS_ACCESS_CMSMain', 'any', $member); + } + } ``` <div class="alert" markdown="1"> diff --git a/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md b/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md index 7e0160626..b4dad61bd 100644 --- a/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md +++ b/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md @@ -19,15 +19,15 @@ For example, if you want to run a simple `COUNT` SQL statement, the following three statements are functionally equivalent: ```php - // Through raw SQL. - $count = DB::query('SELECT COUNT(*) FROM "Member"')->value(); + // Through raw SQL. + $count = DB::query('SELECT COUNT(*) FROM "Member"')->value(); - // Through SQLSelect abstraction layer. - $query = new SQLSelect(); - $count = $query->setFrom('Member')->setSelect('COUNT(*)')->value(); + // Through SQLSelect abstraction layer. + $query = new SQLSelect(); + $count = $query->setFrom('Member')->setSelect('COUNT(*)')->value(); - // Through the ORM. - $count = Member::get()->count(); + // Through the ORM. + $count = Member::get()->count(); ``` If you do use raw SQL, you'll run the risk of breaking @@ -58,29 +58,29 @@ conditional filters, grouping, limiting, and sorting. E.g. ```php - - $sqlQuery = new SQLSelect(); - $sqlQuery->setFrom('Player'); - $sqlQuery->selectField('FieldName', 'Name'); - $sqlQuery->selectField('YEAR("Birthday")', 'Birthyear'); - $sqlQuery->addLeftJoin('Team','"Player"."TeamID" = "Team"."ID"'); - $sqlQuery->addWhere(['YEAR("Birthday") = ?' => 1982]); - // $sqlQuery->setOrderBy(...); - // $sqlQuery->setGroupBy(...); - // $sqlQuery->setHaving(...); - // $sqlQuery->setLimit(...); - // $sqlQuery->setDistinct(true); - - // Get the raw SQL (optional) and parameters - $rawSQL = $sqlQuery->sql($parameters); - - // Execute and return a Query object - $result = $sqlQuery->execute(); + + $sqlQuery = new SQLSelect(); + $sqlQuery->setFrom('Player'); + $sqlQuery->selectField('FieldName', 'Name'); + $sqlQuery->selectField('YEAR("Birthday")', 'Birthyear'); + $sqlQuery->addLeftJoin('Team','"Player"."TeamID" = "Team"."ID"'); + $sqlQuery->addWhere(['YEAR("Birthday") = ?' => 1982]); + // $sqlQuery->setOrderBy(...); + // $sqlQuery->setGroupBy(...); + // $sqlQuery->setHaving(...); + // $sqlQuery->setLimit(...); + // $sqlQuery->setDistinct(true); + + // Get the raw SQL (optional) and parameters + $rawSQL = $sqlQuery->sql($parameters); + + // Execute and return a Query object + $result = $sqlQuery->execute(); - // Iterate over results - foreach($result as $row) { - echo $row['BirthYear']; - } + // Iterate over results + foreach($result as $row) { + echo $row['BirthYear']; + } ``` @@ -96,31 +96,31 @@ object instead. For example, creating a `SQLDelete` object ```php - - $query = SQLDelete::create() - ->setFrom('"SiteTree"') - ->setWhere(['"SiteTree"."ShowInMenus"' => 0]); - $query->execute(); + + $query = SQLDelete::create() + ->setFrom('"SiteTree"') + ->setWhere(['"SiteTree"."ShowInMenus"' => 0]); + $query->execute(); ``` Alternatively, turning an existing `SQLSelect` into a delete ```php - - $query = SQLSelect::create() - ->setFrom('"SiteTree"') - ->setWhere(['"SiteTree"."ShowInMenus"' => 0]) - ->toDelete(); - $query->execute(); + + $query = SQLSelect::create() + ->setFrom('"SiteTree"') + ->setWhere(['"SiteTree"."ShowInMenus"' => 0]) + ->toDelete(); + $query->execute(); ``` Directly querying the database ```php - - DB::prepared_query('DELETE FROM "SiteTree" WHERE "SiteTree"."ShowInMenus" = ?', [0]); + + DB::prepared_query('DELETE FROM "SiteTree" WHERE "SiteTree"."ShowInMenus" = ?', [0]); ``` @@ -169,29 +169,29 @@ SQLInsert also includes the following api methods: E.g. ```php - $update = SQLUpdate::create('"SiteTree"')->addWhere(['ID' => 3]); + $update = SQLUpdate::create('"SiteTree"')->addWhere(['ID' => 3]); - // assigning a list of items - $update->addAssignments([ - '"Title"' => 'Our Products', - '"MenuTitle"' => 'Products' - ]); + // assigning a list of items + $update->addAssignments([ + '"Title"' => 'Our Products', + '"MenuTitle"' => 'Products' + ]); - // Assigning a single value - $update->assign('"MenuTitle"', 'Products'); + // Assigning a single value + $update->assign('"MenuTitle"', 'Products'); - // Assigning a value using parameterised expression - $title = 'Products'; - $update->assign('"MenuTitle"', [ - 'CASE WHEN LENGTH("MenuTitle") > LENGTH(?) THEN "MenuTitle" ELSE ? END' => - [$title, $title] - ]); + // Assigning a value using parameterised expression + $title = 'Products'; + $update->assign('"MenuTitle"', [ + 'CASE WHEN LENGTH("MenuTitle") > LENGTH(?) THEN "MenuTitle" ELSE ? END' => + [$title, $title] + ]); - // Assigning a value using a pure SQL expression - $update->assignSQL('"Date"', 'NOW()'); + // Assigning a value using a pure SQL expression + $update->assignSQL('"Date"', 'NOW()'); - // Perform the update - $update->execute(); + // Perform the update + $update->execute(); ``` @@ -202,25 +202,25 @@ these are translated internally as multiple single row inserts. For example, ```php - $insert = SQLInsert::create('"SiteTree"'); + $insert = SQLInsert::create('"SiteTree"'); - // Add multiple rows in a single call. Note that column names do not need - // to be symmetric - $insert->addRows([ - ['"Title"' => 'Home', '"Content"' => '<p>This is our home page</p>'], - ['"Title"' => 'About Us', '"ClassName"' => 'AboutPage'] - ]); + // Add multiple rows in a single call. Note that column names do not need + // to be symmetric + $insert->addRows([ + ['"Title"' => 'Home', '"Content"' => '<p>This is our home page</p>'], + ['"Title"' => 'About Us', '"ClassName"' => 'AboutPage'] + ]); - // Adjust an assignment on the last row - $insert->assign('"Content"', '<p>This is about us</p>'); + // Adjust an assignment on the last row + $insert->assign('"Content"', '<p>This is about us</p>'); - // Add another row - $insert->addRow(['"Title"' => 'Contact Us']); + // Add another row + $insert->addRow(['"Title"' => 'Contact Us']); - $columns = $insert->getColumns(); - // $columns will be array('"Title"', '"Content"', '"ClassName"'); + $columns = $insert->getColumns(); + // $columns will be array('"Title"', '"Content"', '"ClassName"'); - $insert->execute(); + $insert->execute(); ``` @@ -232,19 +232,19 @@ e.g. when you want a single column rather than a full-blown object representatio Example: Get the count from a relationship. ```php - $sqlQuery = new SQLSelect(); - $sqlQuery->setFrom('Player'); - $sqlQuery->addSelect('COUNT("Player"."ID")'); - $sqlQuery->addWhere(['"Team"."ID"' => 99]); - $sqlQuery->addLeftJoin('Team', '"Team"."ID" = "Player"."TeamID"'); - $count = $sqlQuery->execute()->value(); + $sqlQuery = new SQLSelect(); + $sqlQuery->setFrom('Player'); + $sqlQuery->addSelect('COUNT("Player"."ID")'); + $sqlQuery->addWhere(['"Team"."ID"' => 99]); + $sqlQuery->addLeftJoin('Team', '"Team"."ID" = "Player"."TeamID"'); + $count = $sqlQuery->execute()->value(); ``` Note that in the ORM, this call would be executed in an efficient manner as well: ```php - $count = $myTeam->Players()->count(); + $count = $myTeam->Players()->count(); ``` ### Mapping @@ -255,12 +255,12 @@ This can be useful for creating dropdowns. Example: Show player names with their birth year, but set their birth dates as values. ```php - $sqlQuery = new SQLSelect(); - $sqlQuery->setFrom('Player'); - $sqlQuery->setSelect('Birthdate'); - $sqlQuery->selectField('CONCAT("Name", ' - ', YEAR("Birthdate")', 'NameWithBirthyear'); - $map = $sqlQuery->execute()->map(); - $field = new DropdownField('Birthdates', 'Birthdates', $map); + $sqlQuery = new SQLSelect(); + $sqlQuery->setFrom('Player'); + $sqlQuery->setSelect('Birthdate'); + $sqlQuery->selectField('CONCAT("Name", ' - ', YEAR("Birthdate")', 'NameWithBirthyear'); + $map = $sqlQuery->execute()->map(); + $field = new DropdownField('Birthdates', 'Birthdates', $map); ``` Note that going through SQLSelect is just necessary here @@ -268,20 +268,20 @@ because of the custom SQL value transformation (`YEAR()`). An alternative approach would be a custom getter in the object definition. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { - private static $db = [ - 'Name' => 'Varchar', - 'Birthdate' => 'Date' - ]; - function getNameWithBirthyear() { - return date('y', $this->Birthdate); - } - } - $players = Player::get(); - $map = $players->map('Name', 'NameWithBirthyear'); + class Player extends DataObject + { + private static $db = [ + 'Name' => 'Varchar', + 'Birthdate' => 'Date' + ]; + function getNameWithBirthyear() { + return date('y', $this->Birthdate); + } + } + $players = Player::get(); + $map = $players->map('Name', 'NameWithBirthyear'); ``` diff --git a/docs/en/02_Developer_Guides/00_Model/09_Validation.md b/docs/en/02_Developer_Guides/00_Model/09_Validation.md index 1d3be3ba3..acd23b752 100644 --- a/docs/en/02_Developer_Guides/00_Model/09_Validation.md +++ b/docs/en/02_Developer_Guides/00_Model/09_Validation.md @@ -22,27 +22,27 @@ write, and respond appropriately if it isn't. The return value of `validate()` is a [ValidationResult](api:SilverStripe\ORM\ValidationResult) object. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyObject extends DataObject - { + class MyObject extends DataObject + { - private static $db = [ - 'Country' => 'Varchar', - 'Postcode' => 'Varchar' - ]; + private static $db = [ + 'Country' => 'Varchar', + 'Postcode' => 'Varchar' + ]; - public function validate() - { - $result = parent::validate(); + public function validate() + { + $result = parent::validate(); - if($this->Country == 'DE' && $this->Postcode && strlen($this->Postcode) != 5) { - $result->error('Need five digits for German postcodes'); - } + if($this->Country == 'DE' && $this->Postcode && strlen($this->Postcode) != 5) { + $result->error('Need five digits for German postcodes'); + } - return $result; - } - } + return $result; + } + } ``` diff --git a/docs/en/02_Developer_Guides/00_Model/10_Versioning.md b/docs/en/02_Developer_Guides/00_Model/10_Versioning.md index 1f42fd16b..27ac8f186 100644 --- a/docs/en/02_Developer_Guides/00_Model/10_Versioning.md +++ b/docs/en/02_Developer_Guides/00_Model/10_Versioning.md @@ -21,15 +21,15 @@ also track versioned history. ```php - use SilverStripe\Versioned\Versioned; - use SilverStripe\ORM\DataObject; + use SilverStripe\Versioned\Versioned; + use SilverStripe\ORM\DataObject; - class MyStagedModel extends DataObject - { - private static $extensions = [ - Versioned::class - ]; - } + class MyStagedModel extends DataObject + { + private static $extensions = [ + Versioned::class + ]; + } ``` Alternatively, staging can be disabled, so that only versioned changes are tracked for your model. This @@ -37,14 +37,14 @@ can be specified by setting the constructor argument to "Versioned" ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class VersionedModel extends DataObject - { - private static $extensions = [ - "SilverStripe\\ORM\\Versioning\\Versioned('Versioned')" - ]; - } + class VersionedModel extends DataObject + { + private static $extensions = [ + "SilverStripe\\ORM\\Versioning\\Versioned('Versioned')" + ]; + } ``` <div class="notice" markdown="1"> @@ -87,13 +87,13 @@ By default, all records are retrieved from the "Draft" stage (so the `MyRecord` explicitly request a certain stage through various getters on the `Versioned` class. ```php - // Fetching multiple records - $stageRecords = Versioned::get_by_stage('MyRecord', Versioned::DRAFT); - $liveRecords = Versioned::get_by_stage('MyRecord', Versioned::LIVE); + // Fetching multiple records + $stageRecords = Versioned::get_by_stage('MyRecord', Versioned::DRAFT); + $liveRecords = Versioned::get_by_stage('MyRecord', Versioned::LIVE); - // Fetching a single record - $stageRecord = Versioned::get_by_stage('MyRecord', Versioned::DRAFT)->byID(99); - $liveRecord = Versioned::get_by_stage('MyRecord', Versioned::LIVE)->byID(99); + // Fetching a single record + $stageRecord = Versioned::get_by_stage('MyRecord', Versioned::DRAFT)->byID(99); + $liveRecord = Versioned::get_by_stage('MyRecord', Versioned::LIVE)->byID(99); ``` ### Historical Versions @@ -102,7 +102,7 @@ The above commands will just retrieve the latest version of its respective stage in the `<class>_versions` tables. ```php - $historicalRecord = Versioned::get_version('MyRecord', <record-id>, <version-id>); + $historicalRecord = Versioned::get_version('MyRecord', <record-id>, <version-id>); ``` <div class="alert" markdown="1"> @@ -115,9 +115,9 @@ objects, which expose the same database information as a `DataObject`, but also a record was published. ```php - $record = MyRecord::get()->byID(99); // stage doesn't matter here - $versions = $record->allVersions(); - echo $versions->First()->Version; // instance of Versioned_Version + $record = MyRecord::get()->byID(99); // stage doesn't matter here + $versions = $record->allVersions(); + echo $versions->First()->Version; // instance of Versioned_Version ``` ### Writing Versions and Changing Stages @@ -141,21 +141,21 @@ done via one of several ways: See "DataObject ownership" for reference on dependant objects. ```php - $record = Versioned::get_by_stage('MyRecord', Versioned::DRAFT)->byID(99); - $record->MyField = 'changed'; - // will update `MyRecord` table (assuming Versioned::current_stage() == 'Stage'), - // and write a row to `MyRecord_versions`. - $record->write(); - // will copy the saved record information to the `MyRecord_Live` table - $record->publishRecursive(); + $record = Versioned::get_by_stage('MyRecord', Versioned::DRAFT)->byID(99); + $record->MyField = 'changed'; + // will update `MyRecord` table (assuming Versioned::current_stage() == 'Stage'), + // and write a row to `MyRecord_versions`. + $record->write(); + // will copy the saved record information to the `MyRecord_Live` table + $record->publishRecursive(); ``` Similarly, an "unpublish" operation does the reverse, and removes a record from a specific stage. ```php - $record = MyRecord::get()->byID(99); // stage doesn't matter here - // will remove the row from the `MyRecord_Live` table - $record->deleteFromStage(Versioned::LIVE); + $record = MyRecord::get()->byID(99); // stage doesn't matter here + // will remove the row from the `MyRecord_Live` table + $record->deleteFromStage(Versioned::LIVE); ``` ### Forcing the Current Stage @@ -164,11 +164,11 @@ The current stage is stored as global state on the object. It is usually modifie is initialized. But it can also be set and reset temporarily to force a specific operation to run on a certain stage. ```php - $origMode = Versioned::get_reading_mode(); // save current mode - $obj = MyRecord::getComplexObjectRetrieval(); // returns 'Live' records - Versioned::set_reading_mode(Versioned::DRAFT); // temporarily overwrite mode - $obj = MyRecord::getComplexObjectRetrieval(); // returns 'Stage' records - Versioned::set_reading_mode($origMode); // reset current mode + $origMode = Versioned::get_reading_mode(); // save current mode + $obj = MyRecord::getComplexObjectRetrieval(); // returns 'Live' records + Versioned::set_reading_mode(Versioned::DRAFT); // temporarily overwrite mode + $obj = MyRecord::getComplexObjectRetrieval(); // returns 'Stage' records + Versioned::set_reading_mode($origMode); // reset current mode ``` ### DataObject ownership @@ -191,32 +191,32 @@ without requiring any custom code. ```php - use SilverStripe\Versioned\Versioned; - use SilverStripe\Assets\Image; - use Page; + use SilverStripe\Versioned\Versioned; + use SilverStripe\Assets\Image; + use Page; - class MyPage extends Page - { - private static $has_many = [ - 'Banners' => Banner::class - ]; - private static $owns = [ - 'Banners' - ]; - } - class Banner extends Page - { - private static $extensions = [ - Versioned::class - ]; - private static $has_one = [ - 'Parent' => MyPage::class, - 'Image' => Image::class, - ]; - private static $owns = [ - 'Image' - ]; - } + class MyPage extends Page + { + private static $has_many = [ + 'Banners' => Banner::class + ]; + private static $owns = [ + 'Banners' + ]; + } + class Banner extends Page + { + private static $extensions = [ + Versioned::class + ]; + private static $has_one = [ + 'Parent' => MyPage::class, + 'Image' => Image::class, + ]; + private static $owns = [ + 'Image' + ]; + } ``` @@ -236,35 +236,35 @@ that can be used to traverse between each, and then by ensuring you configure bo E.g. ```php - use SilverStripe\Versioned\Versioned; - use SilverStripe\ORM\DataObject; + use SilverStripe\Versioned\Versioned; + use SilverStripe\ORM\DataObject; - class MyParent extends DataObject - { - private static $extensions = [ - Versioned::class - ]; - private static $owns = [ - 'ChildObjects' - ]; - public function ChildObjects() - { - return MyChild::get(); - } - } - class MyChild extends DataObject - { - private static $extensions = [ - Versioned::class - ]; - private static $owned_by = [ - 'Parent' - ]; - public function Parent() - { - return MyParent::get()->first(); - } - } + class MyParent extends DataObject + { + private static $extensions = [ + Versioned::class + ]; + private static $owns = [ + 'ChildObjects' + ]; + public function ChildObjects() + { + return MyChild::get(); + } + } + class MyChild extends DataObject + { + private static $extensions = [ + Versioned::class + ]; + private static $owned_by = [ + 'Parent' + ]; + public function Parent() + { + return MyParent::get()->first(); + } + } ``` @@ -286,7 +286,7 @@ smaller modifications of the generated `DataList` objects. Example: Get the first 10 live records, filtered by creation date: ```php - $records = Versioned::get_by_stage('MyRecord', Versioned::LIVE)->limit(10)->sort('Created', 'ASC'); + $records = Versioned::get_by_stage('MyRecord', Versioned::LIVE)->limit(10)->sort('Created', 'ASC'); ``` ### Permissions @@ -395,11 +395,11 @@ to force a specific stage, we recommend the `Controller->init()` method for this **mysite/code/MyController.php** ```php - public function init() - { - parent::init(); - Versioned::set_stage(Versioned::DRAFT); - } + public function init() + { + parent::init(); + Versioned::set_stage(Versioned::DRAFT); + } ``` ### Controllers diff --git a/docs/en/02_Developer_Guides/00_Model/11_Scaffolding.md b/docs/en/02_Developer_Guides/00_Model/11_Scaffolding.md index a4373bff8..e8dd3e0ff 100644 --- a/docs/en/02_Developer_Guides/00_Model/11_Scaffolding.md +++ b/docs/en/02_Developer_Guides/00_Model/11_Scaffolding.md @@ -13,46 +13,46 @@ customise those fields as required. An example is `DataObject`, SilverStripe will automatically create your CMS interface so you can modify what you need. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { - - private static $db = [ - 'IsActive' => 'Boolean', - 'Title' => 'Varchar', - 'Content' => 'Text' - ]; + class MyDataObject extends DataObject + { + + private static $db = [ + 'IsActive' => 'Boolean', + 'Title' => 'Varchar', + 'Content' => 'Text' + ]; - public function getCMSFields() - { - // parent::getCMSFields() does all the hard work and creates the fields for Title, IsActive and Content. - $fields = parent::getCMSFields(); - $fields->dataFieldByName('IsActive')->setTitle('Is active?'); - - return $fields; - } - } + public function getCMSFields() + { + // parent::getCMSFields() does all the hard work and creates the fields for Title, IsActive and Content. + $fields = parent::getCMSFields(); + $fields->dataFieldByName('IsActive')->setTitle('Is active?'); + + return $fields; + } + } ``` To fully customise your form fields, start with an empty FieldList. ```php - - public function getCMSFields() - { - $fields = FieldList::create( - TabSet::create("Root.Main", - CheckboxSetField::create('IsActive','Is active?'), - TextField::create('Title'), - TextareaField::create('Content') - ->setRows(5) - ) - ); - - return $fields; - } + + public function getCMSFields() + { + $fields = FieldList::create( + TabSet::create("Root.Main", + CheckboxSetField::create('IsActive','Is active?'), + TextField::create('Title'), + TextareaField::create('Content') + ->setRows(5) + ) + ); + + return $fields; + } ``` You can also alter the fields of built-in and module `DataObject` classes through your own @@ -64,16 +64,16 @@ The `$searchable_fields` property uses a mixed array format that can be used to system. The default is a set of array values listing the fields. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { - - private static $searchable_fields = [ - 'Name', - 'ProductCode' - ]; - } + class MyDataObject extends DataObject + { + + private static $searchable_fields = [ + 'Name', + 'ProductCode' + ]; + } ``` @@ -82,16 +82,16 @@ default search filter assigned (usually an [ExactMatchFilter](api:SilverStripe\O additional information on `$searchable_fields`: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { + class MyDataObject extends DataObject + { - private static $searchable_fields = [ - 'Name' => 'PartialMatchFilter', - 'ProductCode' => 'NumericField' - ]; - } + private static $searchable_fields = [ + 'Name' => 'PartialMatchFilter', + 'ProductCode' => 'NumericField' + ]; + } ``` @@ -99,59 +99,59 @@ If you assign a single string value, you can set it to be either a [FormField](a both, you can assign an array: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { - - private static $searchable_fields = [ - 'Name' => [ - 'field' => 'TextField', - 'filter' => 'PartialMatchFilter', - ], - 'ProductCode' => [ - 'title' => 'Product code #', - 'field' => 'NumericField', - 'filter' => 'PartialMatchFilter', - ], - ]; - } + class MyDataObject extends DataObject + { + + private static $searchable_fields = [ + 'Name' => [ + 'field' => 'TextField', + 'filter' => 'PartialMatchFilter', + ], + 'ProductCode' => [ + 'title' => 'Product code #', + 'field' => 'NumericField', + 'filter' => 'PartialMatchFilter', + ], + ]; + } ``` To include relations (`$has_one`, `$has_many` and `$many_many`) in your search, you can use a dot-notation. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { - - private static $db = [ - 'Title' => 'Varchar' - ]; - - private static $many_many = [ - 'Players' => 'Player' - ]; - - private static $searchable_fields = [ - 'Title', - 'Players.Name', - ]; - } - class Player extends DataObject - { - - private static $db = [ - 'Name' => 'Varchar', - 'Birthday' => 'Date' - ]; - - private static $belongs_many_many = [ - 'Teams' => 'Team' - ]; - } + class Team extends DataObject + { + + private static $db = [ + 'Title' => 'Varchar' + ]; + + private static $many_many = [ + 'Players' => 'Player' + ]; + + private static $searchable_fields = [ + 'Title', + 'Players.Name', + ]; + } + class Player extends DataObject + { + + private static $db = [ + 'Name' => 'Varchar', + 'Birthday' => 'Date' + ]; + + private static $belongs_many_many = [ + 'Teams' => 'Team' + ]; + } ``` @@ -161,79 +161,79 @@ Summary fields can be used to show a quick overview of the data for a specific [ is their display as table columns, e.g. in the search results of a [ModelAdmin](api:SilverStripe\Admin\ModelAdmin) CMS interface. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { - - private static $db = [ - 'Name' => 'Text', - 'OtherProperty' => 'Text', - 'ProductCode' => 'Int', - ]; - - private static $summary_fields = [ - 'Name', - 'ProductCode' - ]; - } + class MyDataObject extends DataObject + { + + private static $db = [ + 'Name' => 'Text', + 'OtherProperty' => 'Text', + 'ProductCode' => 'Int', + ]; + + private static $summary_fields = [ + 'Name', + 'ProductCode' + ]; + } ``` To include relations or field manipulations in your summaries, you can use a dot-notation. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class OtherObject extends DataObject - { - - private static $db = [ - 'Title' => 'Varchar' - ]; - } - class MyDataObject extends DataObject - { - - private static $db = [ - 'Name' => 'Text', - 'Description' => 'HTMLText' - ]; - - private static $has_one = [ - 'OtherObject' => 'OtherObject' - ]; - - private static $summary_fields = [ - 'Name' => 'Name', - 'Description.Summary' => 'Description (summary)', - 'OtherObject.Title' => 'Other Object Title' - ]; - } + class OtherObject extends DataObject + { + + private static $db = [ + 'Title' => 'Varchar' + ]; + } + class MyDataObject extends DataObject + { + + private static $db = [ + 'Name' => 'Text', + 'Description' => 'HTMLText' + ]; + + private static $has_one = [ + 'OtherObject' => 'OtherObject' + ]; + + private static $summary_fields = [ + 'Name' => 'Name', + 'Description.Summary' => 'Description (summary)', + 'OtherObject.Title' => 'Other Object Title' + ]; + } ``` Non-textual elements (such as images and their manipulations) can also be used in summaries. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { - - private static $db = [ - 'Name' => 'Text' - ]; - - private static $has_one = [ - 'HeroImage' => 'Image' - ]; - - private static $summary_fields = [ - 'Name' => 'Name', - 'HeroImage.CMSThumbnail' => 'Hero Image' - ]; - } + class MyDataObject extends DataObject + { + + private static $db = [ + 'Name' => 'Text' + ]; + + private static $has_one = [ + 'HeroImage' => 'Image' + ]; + + private static $summary_fields = [ + 'Name' => 'Name', + 'HeroImage.CMSThumbnail' => 'Hero Image' + ]; + } ``` diff --git a/docs/en/02_Developer_Guides/00_Model/12_Indexes.md b/docs/en/02_Developer_Guides/00_Model/12_Indexes.md index 3b55dc704..673dde74f 100644 --- a/docs/en/02_Developer_Guides/00_Model/12_Indexes.md +++ b/docs/en/02_Developer_Guides/00_Model/12_Indexes.md @@ -25,20 +25,20 @@ Indexes are represented on a `DataObject` through the `DataObject::$indexes` arr descriptor. There are several supported notations: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyObject extends DataObject - { + class MyObject extends DataObject + { - private static $indexes = [ - '<column-name>' => true, - '<index-name>' => [ - 'type' => '<type>', - 'columns' => ['<column-name>', '<other-column-name>'], - ], - '<index-name>' => ['<column-name>', '<other-column-name>'], - ]; - } + private static $indexes = [ + '<column-name>' => true, + '<index-name>' => [ + 'type' => '<type>', + 'columns' => ['<column-name>', '<other-column-name>'], + ], + '<index-name>' => ['<column-name>', '<other-column-name>'], + ]; + } ``` The `<column-name>` is used to put a standard non-unique index on the column specified. For complex or large tables @@ -55,20 +55,20 @@ support the following: **mysite/code/MyTestObject.php** ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyTestObject extends DataObject - { + class MyTestObject extends DataObject + { - private static $db = [ - 'MyField' => 'Varchar', - 'MyOtherField' => 'Varchar', - ]; + private static $db = [ + 'MyField' => 'Varchar', + 'MyOtherField' => 'Varchar', + ]; - private static $indexes = [ - 'MyIndexName' => ['MyField', 'MyOtherField'], - ]; - } + private static $indexes = [ + 'MyIndexName' => ['MyField', 'MyOtherField'], + ]; + } ``` ## Complex/Composite Indexes diff --git a/docs/en/02_Developer_Guides/00_Model/How_Tos/Dynamic_Default_Fields.md b/docs/en/02_Developer_Guides/00_Model/How_Tos/Dynamic_Default_Fields.md index 6376f08ba..bd4709a3e 100644 --- a/docs/en/02_Developer_Guides/00_Model/How_Tos/Dynamic_Default_Fields.md +++ b/docs/en/02_Developer_Guides/00_Model/How_Tos/Dynamic_Default_Fields.md @@ -10,30 +10,30 @@ object! A simple example is to set a field to the current date and time: ```php - /** - * Sets the Date field to the current date. - */ - public function populateDefaults() - { - $this->Date = date('Y-m-d'); - parent::populateDefaults(); - } + /** + * Sets the Date field to the current date. + */ + public function populateDefaults() + { + $this->Date = date('Y-m-d'); + parent::populateDefaults(); + } ``` It's also possible to get the data from any other source, or another object, just by using the usual data retrieval methods. For example: ```php - /** - * This method combines the Title of the parent object with the Title of this - * object in the FullTitle field. - */ - public function populateDefaults() - { - if($parent = $this->Parent()) { - $this->FullTitle = $parent->Title . ': ' . $this->Title; - } else { - $this->FullTitle = $this->Title; - } - parent::populateDefaults(); - } + /** + * This method combines the Title of the parent object with the Title of this + * object in the FullTitle field. + */ + public function populateDefaults() + { + if($parent = $this->Parent()) { + $this->FullTitle = $parent->Title . ': ' . $this->Title; + } else { + $this->FullTitle = $this->Title; + } + parent::populateDefaults(); + } ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/00_Model/How_Tos/Grouping_DataObject_Sets.md b/docs/en/02_Developer_Guides/00_Model/How_Tos/Grouping_DataObject_Sets.md index fe1af2310..09a2f56d7 100644 --- a/docs/en/02_Developer_Guides/00_Model/How_Tos/Grouping_DataObject_Sets.md +++ b/docs/en/02_Developer_Guides/00_Model/How_Tos/Grouping_DataObject_Sets.md @@ -35,23 +35,23 @@ along with a method that returns the first letter of the title. This will be used both for grouping and for the title in the template. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Module extends DataObject - { - private static $db = [ - 'Title' => 'Text' - ]; - - /** - * Returns the first letter of the module title, used for grouping. - * @return string - */ - public function getTitleFirstLetter() - { - return $this->Title[0]; - } - } + class Module extends DataObject + { + private static $db = [ + 'Title' => 'Text' + ]; + + /** + * Returns the first letter of the module title, used for grouping. + * @return string + */ + public function getTitleFirstLetter() + { + return $this->Title[0]; + } + } ``` @@ -59,24 +59,24 @@ The next step is to create a method or variable that will contain/return all the sorted by title. For this example this will be a method on the `Page` class. ```php - use SilverStripe\CMS\Model\SiteTree; - use SilverStripe\ORM\GroupedList; + use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\ORM\GroupedList; - class Page extends SiteTree - { - - // ... - - /** - * Returns all modules, sorted by their title. - * @return GroupedList - */ - public function getGroupedModules() - { - return GroupedList::create(Module::get()->sort('Title')); - } - - } + class Page extends SiteTree + { + + // ... + + /** + * Returns all modules, sorted by their title. + * @return GroupedList + */ + public function getGroupedModules() + { + return GroupedList::create(Module::get()->sort('Title')); + } + + } ``` The final step is to render this into a template. The `GroupedBy()` method breaks up the set into @@ -84,16 +84,16 @@ a number of sets, grouped by the field that is passed as the parameter. In this case, the `getTitleFirstLetter()` method defined earlier is used to break them up. ```ss - <%-- Modules list grouped by TitleFirstLetter --%> - <h2>Modules</h2> - <% loop $GroupedModules.GroupedBy(TitleFirstLetter) %> - <h3>$TitleFirstLetter</h3> - <ul> - <% loop $Children %> - <li>$Title</li> - <% end_loop %> - </ul> - <% end_loop %> + <%-- Modules list grouped by TitleFirstLetter --%> + <h2>Modules</h2> + <% loop $GroupedModules.GroupedBy(TitleFirstLetter) %> + <h3>$TitleFirstLetter</h3> + <ul> + <% loop $Children %> + <li>$Title</li> + <% end_loop %> + </ul> + <% end_loop %> ``` ## Grouping Sets By Month @@ -109,61 +109,61 @@ which is automatically set when the record is first written to the database. This will have a method which returns the month it was posted in: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Module extends DataObject - { - - // ... - - /** - * Returns the month name this news item was posted in. - * @return string - */ - public function getMonthCreated() - { - return date('F', strtotime($this->Created)); - } - - } + class Module extends DataObject + { + + // ... + + /** + * Returns the month name this news item was posted in. + * @return string + */ + public function getMonthCreated() + { + return date('F', strtotime($this->Created)); + } + + } ``` The next step is to create a method that will return all records that exist, sorted by month name from January to December. This can be accomplshed by sorting by the `Created` field: ```php - use SilverStripe\CMS\Model\SiteTree; - use SilverStripe\ORM\GroupedList; + use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\ORM\GroupedList; - class Page extends SiteTree - { - - // ... - - /** - * Returns all news items, sorted by the month they were posted - * @return GroupedList - */ - public function getGroupedModulesByDate() - { - return GroupedList::create(Module::get()->sort('Created')); - } - - } + class Page extends SiteTree + { + + // ... + + /** + * Returns all news items, sorted by the month they were posted + * @return GroupedList + */ + public function getGroupedModulesByDate() + { + return GroupedList::create(Module::get()->sort('Created')); + } + + } ``` The final step is the render this into the template using the [GroupedList::GroupedBy()](api:SilverStripe\ORM\GroupedList::GroupedBy()) method. ```ss - // Modules list grouped by the Month Posted - <h2>Modules</h2> - <% loop $GroupedModulesByDate.GroupedBy(MonthCreated) %> - <h3>$MonthCreated</h3> - <ul> - <% loop $Children %> - <li>$Title ($Created.Nice)</li> - <% end_loop %> - </ul> - <% end_loop %> + // Modules list grouped by the Month Posted + <h2>Modules</h2> + <% loop $GroupedModulesByDate.GroupedBy(MonthCreated) %> + <h3>$MonthCreated</h3> + <ul> + <% loop $Children %> + <li>$Title ($Created.Nice)</li> + <% end_loop %> + </ul> + <% end_loop %> ``` ## Related diff --git a/docs/en/02_Developer_Guides/01_Templates/01_Syntax.md b/docs/en/02_Developer_Guides/01_Templates/01_Syntax.md index f9f8978de..63195ccde 100644 --- a/docs/en/02_Developer_Guides/01_Templates/01_Syntax.md +++ b/docs/en/02_Developer_Guides/01_Templates/01_Syntax.md @@ -13,32 +13,32 @@ An example of a SilverStripe template is below: ```ss - <html> - <head> - <% base_tag %> - <title>$Title - <% require themedCSS("screen") %> - - -
-

Bob's Chicken Shack

-
+ + + <% base_tag %> + $Title + <% require themedCSS("screen") %> + + +
+

Bob's Chicken Shack

+
- <% with $CurrentMember %> -

Welcome $FirstName $Surname.

- <% end_with %> + <% with $CurrentMember %> +

Welcome $FirstName $Surname.

+ <% end_with %> - <% if $Dishes %> -
    - <% loop $Dishes %> -
  • $Title ($Price.Nice)
    • - <% end_loop %> -
- <% end_if %> + <% if $Dishes %> +
    + <% loop $Dishes %> +
  • $Title ($Price.Nice)
    • + <% end_loop %> +
+ <% end_if %> - <% include Footer %> - - + <% include Footer %> + + ```
@@ -70,7 +70,7 @@ alphabetic character or underscore, with subsequent characters being alphanumeri ```ss - $Title + $Title ``` This inserts the value of the Title database field of the page being displayed in place of `$Title`. @@ -79,9 +79,9 @@ Variables can be chained together, and include arguments. ```ss - $Foo - $Foo(param) - $Foo.Bar + $Foo + $Foo(param) + $Foo.Bar ``` These variables will call a method / field on the object and insert the returned value as a string into the template. @@ -104,17 +104,17 @@ Variables can come from your database fields, or custom methods you define on yo **mysite/code/Page.php** ```php - public function UsersIpAddress() + public function UsersIpAddress() { - return $this->getRequest()->getIP(); - } + return $this->getRequest()->getIP(); + } ``` **mysite/code/Page.ss** ```html -

You are coming from $UsersIpAddress.

+

You are coming from $UsersIpAddress.

```
@@ -130,11 +130,11 @@ record and any subclasses of those two. ```ss - $Title - // returns the page `Title` property + $Title + // returns the page `Title` property - $Content - // returns the page `Content` property + $Content + // returns the page `Content` property ``` ## Conditional Logic @@ -143,18 +143,18 @@ The simplest conditional block is to check for the presence of a value (does not ```ss - <% if $CurrentMember %> -

You are logged in as $CurrentMember.FirstName $CurrentMember.Surname.

- <% end_if %> + <% if $CurrentMember %> +

You are logged in as $CurrentMember.FirstName $CurrentMember.Surname.

+ <% end_if %> ``` A conditional can also check for a value other than falsy. ```ss - <% if $MyDinner == "kipper" %> - Yummy, kipper for tea. - <% end_if %> + <% if $MyDinner == "kipper" %> + Yummy, kipper for tea. + <% end_if %> ```
@@ -165,24 +165,24 @@ Conditionals can also provide the `else` case. ```ss - <% if $MyDinner == "kipper" %> - Yummy, kipper for tea - <% else %> - I wish I could have kipper :-( - <% end_if %> + <% if $MyDinner == "kipper" %> + Yummy, kipper for tea + <% else %> + I wish I could have kipper :-( + <% end_if %> ``` `else_if` commands can be used to handle multiple `if` statements. ```ss - <% if $MyDinner == "quiche" %> - Real men don't eat quiche - <% else_if $MyDinner == $YourDinner %> - We both have good taste - <% else %> - Can I have some of your chips? - <% end_if %> + <% if $MyDinner == "quiche" %> + Real men don't eat quiche + <% else_if $MyDinner == $YourDinner %> + We both have good taste + <% else %> + Can I have some of your chips? + <% end_if %> ``` ### Negation @@ -191,9 +191,9 @@ The inverse of `<% if %>` is `<% if not %>`. ```ss - <% if not $DinnerInOven %> - I'm going out for dinner tonight. - <% end_if %> + <% if not $DinnerInOven %> + I'm going out for dinner tonight. + <% end_if %> ``` ### Boolean Logic @@ -204,18 +204,18 @@ If *either* of the conditions is true. ```ss - <% if $MyDinner == "kipper" || $MyDinner == "salmon" %> - yummy, fish for tea - <% end_if %> + <% if $MyDinner == "kipper" || $MyDinner == "salmon" %> + yummy, fish for tea + <% end_if %> ``` If *both* of the conditions are true. ```ss - <% if $MyDinner == "quiche" && $YourDinner == "kipper" %> - Lets swap dinners - <% end_if %> + <% if $MyDinner == "quiche" && $YourDinner == "kipper" %> + Lets swap dinners + <% end_if %> ``` ### Inequalities @@ -224,9 +224,9 @@ You can use inequalities like `<`, `<=`, `>`, `>=` to compare numbers. ```ss - <% if $Number >= "5" && $Number <= "10" %> - Number between 5 and 10 - <% end_if %> + <% if $Number >= "5" && $Number <= "10" %> + Number between 5 and 10 + <% end_if %> ``` ## Includes @@ -237,8 +237,8 @@ an additional `Includes` directory will be inserted into the resolved path just ```ss - <% include SideBar %> - <% include MyNamespace/SideBar %> + <% include SideBar %> + <% include MyNamespace/SideBar %> ``` When using subfolders in your template structure @@ -246,7 +246,7 @@ When using subfolders in your template structure ```ss - <% include MyNamespace/SideBar %> + <% include MyNamespace/SideBar %> ``` The `include` tag can be particularly helpful for nested functionality and breaking large templates up. In this example, @@ -254,9 +254,9 @@ the include only happens if the user is logged in. ```ss - <% if $CurrentMember %> - <% include MembersOnlyInclude %> - <% end_if %> + <% if $CurrentMember %> + <% include MembersOnlyInclude %> + <% end_if %> ``` Includes can't directly access the parent scope when the include is included. However you can pass arguments to the @@ -264,9 +264,9 @@ include. ```ss - <% with $CurrentMember %> - <% include MemberDetails Top=$Top, Name=$Name %> - <% end_with %> + <% with $CurrentMember %> + <% include MemberDetails Top=$Top, Name=$Name %> + <% end_with %> ``` ## Looping Over Lists @@ -276,13 +276,13 @@ collection. ```ss -

Children of $Title

+

Children of $Title

-
    - <% loop $Children %> -
  • $Title
    • - <% end_loop %> -
+
    + <% loop $Children %> +
  • $Title
    • + <% end_loop %> +
``` This snippet loops over the children of a page, and generates an unordered list showing the `Title` property from each @@ -305,55 +305,55 @@ Sorting the list by a given field. ```ss -
    - <% loop $Children.Sort(Title, ASC) %> -
  • $Title
    • - <% end_loop %> -
+
    + <% loop $Children.Sort(Title, ASC) %> +
  • $Title
    • + <% end_loop %> +
``` Limiting the number of items displayed. ```ss -
    - <% loop $Children.Limit(10) %> -
  • $Title
    • - <% end_loop %> -
+
    + <% loop $Children.Limit(10) %> +
  • $Title
    • + <% end_loop %> +
``` Reversing the loop. ```ss -
    - <% loop $Children.Reverse %> -
  • $Title
    • - <% end_loop %> -
+
    + <% loop $Children.Reverse %> +
  • $Title
    • + <% end_loop %> +
``` Filtering the loop. ```ss -
    - <% loop $Children.Filter('School', 'College') %> -
  • $Title
    • - <% end_loop %> -
+
    + <% loop $Children.Filter('School', 'College') %> +
  • $Title
    • + <% end_loop %> +
``` Methods can also be chained. ```ss -
    - <% loop $Children.Filter('School', 'College').Sort(Score, DESC) %> -
  • $Title
    • - <% end_loop %> -
+
    + <% loop $Children.Filter('School', 'College').Sort(Score, DESC) %> +
  • $Title
    • + <% end_loop %> +
``` ### Position Indicators @@ -373,15 +373,15 @@ iteration. ```ss -
    - <% loop $Children.Reverse %> - <% if First %> -
  • My Favourite
    • - <% end_if %> +
      + <% loop $Children.Reverse %> + <% if First %> +
    • My Favourite
      • + <% end_if %> -
    • Child $Pos of $TotalItems - $Title
      • - <% end_loop %> -
    +
  • Child $Pos of $TotalItems - $Title
    • + <% end_loop %> +
```
@@ -395,19 +395,19 @@ $Modulus and $MultipleOf can help to build column and grid layouts. ```ss - // returns an int - $Modulus(value, offset) + // returns an int + $Modulus(value, offset) - // returns a boolean. - $MultipleOf(factor, offset) + // returns a boolean. + $MultipleOf(factor, offset) - <% loop $Children %> -
- ... -
- <% end_loop %> + <% loop $Children %> +
+ ... +
+ <% end_loop %> - // returns
,
, + // returns
,
, ```
@@ -420,11 +420,11 @@ after every 3rd item. ```ss - <% loop $Children %> - <% if $MultipleOf(3) %> -
- <% end_if %> - <% end_loop %> + <% loop $Children %> + <% if $MultipleOf(3) %> +
+ <% end_if %> + <% end_loop %> ``` ### Escaping @@ -433,24 +433,24 @@ Sometimes you will have template tags which need to roll into one another. Use ` ```ss - $Foopx // will returns "" (as it looks for a `Foopx` value) - {$Foo}px // returns "3px" (CORRECT) + $Foopx // will returns "" (as it looks for a `Foopx` value) + {$Foo}px // returns "3px" (CORRECT) ``` Or when having a `$` sign in front of the variable such as displaying money. ```ss - $$Foo // returns "" - ${$Foo} // returns "$3" + $$Foo // returns "" + ${$Foo} // returns "$3" ``` You can also use a backslash to escape the name of the variable, such as: ```ss - $Foo // returns "3" - \$Foo // returns "$Foo" + $Foo // returns "3" + \$Foo // returns "$Foo" ```
@@ -481,15 +481,15 @@ When in a particular scope, `$Up` takes the scope back to the previous level. ```ss -

Children of '$Title'

+

Children of '$Title'

- <% loop $Children %> -

Page '$Title' is a child of '$Up.Title'

- - <% loop $Children %> -

Page '$Title' is a grandchild of '$Up.Up.Title'

- <% end_loop %> - <% end_loop %> + <% loop $Children %> +

Page '$Title' is a child of '$Up.Title'

+ + <% loop $Children %> +

Page '$Title' is a grandchild of '$Up.Up.Title'

+ <% end_loop %> + <% end_loop %> ``` Given the following structure, it will output the text. @@ -514,11 +514,11 @@ Additional selectors implicitely change the scope so you need to put additional ```ss -

Children of '$Title'

- <% loop $Children.Sort('Title').First %> - <%-- We have two additional selectors in the loop expression so... --%> -

Page '$Title' is a child of '$Up.Up.Up.Title'

- <% end_loop %> +

Children of '$Title'

+ <% loop $Children.Sort('Title').First %> + <%-- We have two additional selectors in the loop expression so... --%> +

Page '$Title' is a child of '$Up.Up.Up.Title'

+ <% end_loop %> ``` #### Top @@ -528,15 +528,15 @@ page. The previous example could be rewritten to use the following syntax. ```ss -

Children of '$Title'

+

Children of '$Title'

- <% loop $Children %> -

Page '$Title' is a child of '$Top.Title'

- - <% loop $Children %> -

Page '$Title' is a grandchild of '$Top.Title'

- <% end_loop %> - <% end_loop %> + <% loop $Children %> +

Page '$Title' is a child of '$Top.Title'

+ + <% loop $Children %> +

Page '$Title' is a grandchild of '$Top.Title'

+ <% end_loop %> + <% end_loop %> ``` ### With @@ -545,16 +545,16 @@ The `<% with %>` tag lets you change into a new scope. Consider the following ex ```ss - <% with $CurrentMember %> - Hello, $FirstName, welcome back. Your current balance is $Balance. - <% end_with %> + <% with $CurrentMember %> + Hello, $FirstName, welcome back. Your current balance is $Balance. + <% end_with %> ``` This is functionalty the same as the following: ```ss - Hello, $CurrentMember.FirstName, welcome back. Your current balance is $CurrentMember.Balance + Hello, $CurrentMember.FirstName, welcome back. Your current balance is $CurrentMember.Balance ``` Notice that the first example is much tidier, as it removes the repeated use of the `$CurrentMember` accessor. @@ -569,7 +569,7 @@ refer directly to properties and methods of the [Member](api:SilverStripe\Securi ```ss - $Me + $Me ``` ## Comments @@ -578,7 +578,7 @@ Using standard HTML comments is supported. These comments will be included in th ```ss - $EditForm + $EditForm ``` However you can also use special SilverStripe comments which will be stripped out of the published site. This is useful @@ -586,7 +586,7 @@ for adding notes for other developers but for things you don't want published in ```ss - $EditForm <%-- Some hidden comment about the form --%> + $EditForm <%-- Some hidden comment about the form --%> ``` ## Related diff --git a/docs/en/02_Developer_Guides/01_Templates/02_Common_Variables.md b/docs/en/02_Developer_Guides/01_Templates/02_Common_Variables.md index 34d8b9655..1f33349ef 100644 --- a/docs/en/02_Developer_Guides/01_Templates/02_Common_Variables.md +++ b/docs/en/02_Developer_Guides/01_Templates/02_Common_Variables.md @@ -32,11 +32,11 @@ functionality may not be included. ```ss - - <% base_tag %> + + <% base_tag %> - .. - + .. + ``` The `<% base_tag %>` placeholder is replaced with the HTML base element. Relative links within a document (such as ` is nearly always required or assumed by SilverStripe to exist Returns the currently logged in [Member](api:SilverStripe\Security\Member) instance, if there is one logged in.```ss - <% if $CurrentMember %> - Welcome Back, $CurrentMember.FirstName - <% end_if %> + <% if $CurrentMember %> + Welcome Back, $CurrentMember.FirstName + <% end_if %> ``` ## Title and Menu Title ```ss - $Title - $MenuTitle + $Title + $MenuTitle ``` Most objects within SilverStripe will respond to `$Title` (i.e they should have a `Title` database field or at least a @@ -80,7 +80,7 @@ If `MenuTitle` is left blank by the CMS author, it'll just default to the value ```ss - $Content + $Content ``` It returns the database content of the `Content` property. With the CMS Module, this is the value of the WYSIWYG editor @@ -104,7 +104,7 @@ web pages. You'll need to install it via `composer`. ```ss - $SiteConfig.Title + $SiteConfig.Title ``` The [SiteConfig](../configuration/siteconfig) object allows content authors to modify global data in the CMS, rather @@ -128,30 +128,30 @@ By default `$MetaTags` renders: ```ss - Title of the Page - - + Title of the Page + + ``` `$MetaTags(false)` will render```ss - - + + ``` If using `$MetaTags(false)` we can provide a more custom `title`. ```ss - $MetaTags(false) - $Title - Bob's Fantasy Football + $MetaTags(false) + $Title - Bob's Fantasy Football ``` ## Links ```ss - .. + .. ``` All objects that could be accessible in SilverStripe should define a `Link` method and an `AbsoluteLink` method. Link @@ -160,19 +160,19 @@ link. ```ss - $Link - + $Link + - $AbsoluteLink - + $AbsoluteLink + ``` ### Linking Modes ```ss - $isSection - $isCurrent + $isSection + $isCurrent ``` When looping over a list of `SiteTree` instances through a `<% loop $Menu %>` or `<% loop $Children %>`, `$isSection` and `$isCurrent` @@ -182,11 +182,11 @@ For instance, to only show the menu item linked if it's the current one: ```ss - <% if $isCurrent %> - $Title - <% else %> - $Title - <% end_if %> + <% if $isCurrent %> + $Title + <% else %> + $Title + <% end_if %> ``` An example for checking for `current` or `section` is as follows: @@ -202,9 +202,9 @@ An example for checking for `current` or `section` is as follows: ```ss - <% if $InSection(about-us) %> -

You are viewing the about us section

- <% end_if %> + <% if $InSection(about-us) %> +

You are viewing the about us section

+ <% end_if %> ``` ### URLSegment @@ -215,11 +215,11 @@ It can be used within templates to generate anchors or other CSS classes. ```ss -
+
-
+
- + ``` ## ClassName @@ -230,18 +230,18 @@ behavior based on the page type used: ```ss - + - + ``` ## Children Loops ```ss - <% loop $Children %> + <% loop $Children %> - <% end_loop %> + <% end_loop %> ``` Will loop over all Children records of the current object context. Children are pages that sit under the current page in @@ -256,9 +256,9 @@ context. ```ss - <% loop $ChildrenOf() %> + <% loop $ChildrenOf() %> - <% end_loop %> + <% end_loop %> ``` Will create a list of the children of the given page, as identified by its `URLSegment` value. This can come in handy @@ -274,18 +274,18 @@ preference, `AllChildren` does not filter by `ShowInMenus`. ```ss - <% loop $AllChildren %> - ... - <% end_loop %> + <% loop $AllChildren %> + ... + <% end_loop %> ``` ### Menu Loops ```ss - <% loop $Menu(1) %> - ... - <% end_loop %> + <% loop $Menu(1) %> + ... + <% end_loop %> ``` `$Menu(1)` returns the top-level menu of the website. You can also create a sub-menu using `$Menu(2)`, and so forth. @@ -298,9 +298,9 @@ Pages with the `ShowInMenus` property set to `false` will be filtered out. ```ss - <% with $Page(my-page) %> - $Title - <% end_with %> + <% with $Page(my-page) %> + $Title + <% end_with %> ``` Page will return a single page from site, looking it up by URL. @@ -311,9 +311,9 @@ Page will return a single page from site, looking it up by URL. ```ss - <% with $Level(1) %> - $Title - <% end_with %> + <% with $Level(1) %> + $Title + <% end_with %> ``` Will return a page in the current path, at the level specified by the numbers. It is based on the current page context, @@ -329,13 +329,13 @@ For example, imagine you're on the "bob marley" page, which is three levels in: ```ss - - - $Parent.Title - + + + $Parent.Title + - $Parent.Parent.Title - + $Parent.Parent.Title + ``` ## Navigating Scope @@ -352,18 +352,18 @@ While you can achieve breadcrumbs through the `$Level()` control manually ```ss - $Breadcrumbs + $Breadcrumbs ``` By default, it uses the template defined in `cms/templates/BreadcrumbsTemplate.ss` ```ss - <% if $Pages %> - <% loop $Pages %> - <% if $Last %>$Title.XML<% else %>$MenuTitle.XML »<% end_if %> - <% end_loop %> - <% end_if %> + <% if $Pages %> + <% loop $Pages %> + <% if $Last %>$Title.XML<% else %>$MenuTitle.XML »<% end_if %> + <% end_loop %> + <% end_if %> ```
@@ -375,7 +375,7 @@ To customise the markup that the `$Breadcrumbs` generates, copy `cms/templates/B ```ss - $Form + $Form ``` A page will normally contain some content and potentially a form of some kind. For example, the log-in page has a the diff --git a/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md b/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md index 143109b83..84f69b322 100644 --- a/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md +++ b/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md @@ -17,9 +17,9 @@ The `Requirements` class can work with arbitrary file paths. ```ss - <% require css("/css/some_file.css") %> - <% require themedCSS("some_themed_file") %> - <% require javascript("/javascript/some_file.js") %> + <% require css("/css/some_file.css") %> + <% require themedCSS("some_themed_file") %> + <% require javascript("/javascript/some_file.js") %> ```
@@ -97,11 +97,11 @@ You can also use the second argument to add the 'async' and/or 'defer attributes ```php Requirements::javascript( - "/javascript/some_file.js", - [ - "async" => true, - "defer" => true, - ] + "/javascript/some_file.js", + [ + "async" => true, + "defer" => true, + ] ); ``` @@ -281,13 +281,13 @@ class MyMinifier implements Requirements_Minifier * @param string $type Either js or css * @param string $filename Name of file to display in case of error * @return string minified content - */ - public function minify ($content, $type, $fileName) - { - // Minify $content; + */ + public function minify ($content, $type, $fileName) + { + // Minify $content; - return $minifiedContent; - } + return $minifiedContent; + } } ``` diff --git a/docs/en/02_Developer_Guides/01_Templates/05_Template_Inheritance.md b/docs/en/02_Developer_Guides/01_Templates/05_Template_Inheritance.md index 35c0374db..6197574b1 100644 --- a/docs/en/02_Developer_Guides/01_Templates/05_Template_Inheritance.md +++ b/docs/en/02_Developer_Guides/01_Templates/05_Template_Inheritance.md @@ -16,11 +16,11 @@ name in the `mysite/templates/email` folder or in the `themes/your_theme/templat **mysite/templates/email/GenericEmail.ss** - :::ss +```ss $Body

Thanks from Bob's Fantasy Football League.

- +``` All emails going out of our application will have the footer `Thanks from Bob's Fantasy Football Leaguee` added.
@@ -103,19 +103,19 @@ footer and navigation will remain the same and we don't want to replicate this w **mysite/templates/Page.ss** ```ss - - - .. - - - - <% include Header %> - <% include Navigation %> + + + .. + + + + <% include Header %> + <% include Navigation %> - $Layout + $Layout - <% include Footer %> - + <% include Footer %> + `` **mysite/templates/Layout/Page.ss** ```ss diff --git a/docs/en/02_Developer_Guides/01_Templates/07_Caching.md b/docs/en/02_Developer_Guides/01_Templates/07_Caching.md index 8f0a9edf0..3104f2652 100644 --- a/docs/en/02_Developer_Guides/01_Templates/07_Caching.md +++ b/docs/en/02_Developer_Guides/01_Templates/07_Caching.md @@ -9,22 +9,22 @@ All functions that provide data to templates must have no side effects, as the v example, this controller method will not behave as you might imagine. ```php - private $counter = 0; + private $counter = 0; - public function Counter() - { - $this->counter += 1; + public function Counter() + { + $this->counter += 1; - return $this->counter; - } + return $this->counter; + } ``` ```ss - $Counter, $Counter, $Counter + $Counter, $Counter, $Counter - // returns 1, 1, 1 + // returns 1, 1, 1 ``` When we render `$Counter` to the template we would expect the value to increase and output `1, 2, 3`. However, as @@ -38,9 +38,9 @@ from the database to display, the contents of the area are fetched from a [cache ```ss - <% cached 'MyCachedContent', LastEdited %> - $Title - <% end_cached %> + <% cached 'MyCachedContent', LastEdited %> + $Title + <% end_cached %> ``` diff --git a/docs/en/02_Developer_Guides/01_Templates/08_Translations.md b/docs/en/02_Developer_Guides/01_Templates/08_Translations.md index b93b97ab6..498d8612f 100644 --- a/docs/en/02_Developer_Guides/01_Templates/08_Translations.md +++ b/docs/en/02_Developer_Guides/01_Templates/08_Translations.md @@ -6,7 +6,7 @@ summary: Definition of the syntax for writing i18n compatible templates. Translations are easy to use with a template, and give access to SilverStripe's translation facilities. Here is an example: ```ss - <%t Foo.BAR 'Bar' %> + <%t Foo.BAR 'Bar' %> <%t Member.WELCOME 'Welcome {name} to {site}' name=$Member.Name site="Foobar.com" %> ``` diff --git a/docs/en/02_Developer_Guides/01_Templates/09_Casting.md b/docs/en/02_Developer_Guides/01_Templates/09_Casting.md index f87fd3822..9f5db2717 100644 --- a/docs/en/02_Developer_Guides/01_Templates/09_Casting.md +++ b/docs/en/02_Developer_Guides/01_Templates/09_Casting.md @@ -14,11 +14,11 @@ output the result of the [DBHtmlText::FirstParagraph()](api:SilverStripe\ORM\Fie ```ss - $Content.FirstParagraph - + $Content.FirstParagraph + - $LastEdited.Format("d/m/Y") - + $LastEdited.Format("d/m/Y") + ``` Any public method from the object in scope can be called within the template. If that method returns another @@ -26,14 +26,14 @@ Any public method from the object in scope can be called within the template. If ```ss - $Content.FirstParagraph.NoHTML - + $Content.FirstParagraph.NoHTML + -

Copyright {$Now.Year}

- +

Copyright {$Now.Year}

+ -
- +
+ ```
@@ -48,23 +48,23 @@ provide default template for an object. **mysite/code/Page.php** ```php - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { + class Page extends SiteTree + { - public function forTemplate() - { - return "Page: ". $this->Title; - } - } + public function forTemplate() + { + return "Page: ". $this->Title; + } + } ``` **mysite/templates/Page.ss** ```ss - $Me - + $Me + ``` ## Casting @@ -74,20 +74,20 @@ content that method sends back, or, provide a type in the `$casting` array for t to a template, SilverStripe will ensure that the object is wrapped in the correct type and values are safely escaped. ```php - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { + class Page extends SiteTree + { - private static $casting = [ - 'MyCustomMethod' => 'HTMLText' - ]; + private static $casting = [ + 'MyCustomMethod' => 'HTMLText' + ]; - public function MyCustomMethod() - { - return "

This is my header

"; - } - } + public function MyCustomMethod() + { + return "

This is my header

"; + } + } ``` diff --git a/docs/en/02_Developer_Guides/01_Templates/How_Tos/01_Navigation_Menu.md b/docs/en/02_Developer_Guides/01_Templates/How_Tos/01_Navigation_Menu.md index 63d6d2375..4dc53b965 100644 --- a/docs/en/02_Developer_Guides/01_Templates/How_Tos/01_Navigation_Menu.md +++ b/docs/en/02_Developer_Guides/01_Templates/How_Tos/01_Navigation_Menu.md @@ -7,7 +7,7 @@ top level menu with a nested second level using the `Menu` loop and a `Children` **mysite/templates/Page.ss** - :::ss +```ss
    <% loop $Menu(1) %>
  • @@ -27,7 +27,7 @@ top level menu with a nested second level using the `Menu` loop and a `Children`
    • <% end_loop %>
- +``` ## Related * [Template Syntax](../syntax) diff --git a/docs/en/02_Developer_Guides/01_Templates/How_Tos/02_Pagination.md b/docs/en/02_Developer_Guides/01_Templates/How_Tos/02_Pagination.md index 6ba10d9ae..d96eaac90 100644 --- a/docs/en/02_Developer_Guides/01_Templates/How_Tos/02_Pagination.md +++ b/docs/en/02_Developer_Guides/01_Templates/How_Tos/02_Pagination.md @@ -10,7 +10,7 @@ The `PaginatedList` will automatically set up query limits and read the request **mysite/code/Page.php** - :::php +```php /** * Returns a paginated list of all pages in the site. */ @@ -20,6 +20,7 @@ The `PaginatedList` will automatically set up query limits and read the request return new PaginatedList($list, $this->getRequest()); } +```
Note that the concept of "pages" used in pagination does not necessarily mean that we're dealing with `Page` classes, @@ -33,19 +34,19 @@ The first step is to simply list the objects in the template: **mysite/templates/Page.ss** - :::ss +```ss
    <% loop $PaginatedPages %>
  • $Title
    • <% end_loop %>
- +``` By default this will display 10 pages at a time. The next step is to add pagination controls below this so the user can switch between pages: **mysite/templates/Page.ss** - :::ss +```ss <% if $PaginatedPages.MoreThanOnePage %> <% if $PaginatedPages.NotFirstPage %> @@ -65,6 +66,7 @@ switch between pages: <% end_if %> <% end_if %> +``` If there is more than one page, this block will render a set of pagination controls in the form `[1] ... [3] [4] [5] [6] [7] ... [10]`. @@ -76,18 +78,19 @@ that you wish to display on the current page. In this situation the automatic li will break the pagination. You can disable automatic limiting using the [PaginatedList::setLimitItems()](api:SilverStripe\ORM\PaginatedList::setLimitItems()) method when using custom lists. - :::php +```php $myPreLimitedList = Page::get()->limit(10); $pages = new PaginatedList($myPreLimitedList, $this->getRequest()); $pages->setLimitItems(false); - +``` ## Setting the limit of items - :::php +```php $pages = new PaginatedList(Page::get(), $this->getRequest()); $pages->setPageLength(25); +``` If you set this limit to 0 it will disable paging entirely, effectively causing it to appear as a single page list. diff --git a/docs/en/02_Developer_Guides/01_Templates/How_Tos/03_Disable_Anchor_Links.md b/docs/en/02_Developer_Guides/01_Templates/How_Tos/03_Disable_Anchor_Links.md index a0802a025..3e998aaf0 100644 --- a/docs/en/02_Developer_Guides/01_Templates/How_Tos/03_Disable_Anchor_Links.md +++ b/docs/en/02_Developer_Guides/01_Templates/How_Tos/03_Disable_Anchor_Links.md @@ -5,12 +5,12 @@ title: Disable Anchor Rewriting Anchor links are links with a "#" in them. A frequent use-case is to use anchor links to point to different sections of the current page. For example, we might have this in our template: - :::ss +```ss - +``` Things get tricky because of we have set our `` tag to point to the root of the site. So, when you click the first link you will be sent to http://yoursite.com/#section1 instead of http://yoursite.com/my-long-page/#section1 @@ -19,24 +19,27 @@ In order to prevent this situation, the SSViewer template renderer will automati doesn't specify a URL before the anchor, prefixing the URL of the current page. For our example above, the following would be created in the final HTML - :::ss +```ss - +``` There are cases where this can be unhelpful. HTML anchors created from Ajax responses are the most common. In these situations, you can disable anchor link rewriting by setting the `SSViewer.rewrite_hash_links` configuration value to `false`. **mysite/_config/app.yml** + +```yml SSViewer: rewrite_hash_links: false +``` Or, a better way is to call this just for the rendering phase of this particular file: - :::php +```php public function RenderCustomTemplate() { Config::inst()->update('SSViewer', 'rewrite_hash_links', false); @@ -44,4 +47,5 @@ Or, a better way is to call this just for the rendering phase of this particular Config::inst()->update('SSViewer', 'rewrite_hash_links', true); return $html; - } \ No newline at end of file + } +``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/02_Controllers/01_Introduction.md b/docs/en/02_Developer_Guides/02_Controllers/01_Introduction.md index b45cd83c8..2b8b8d9ba 100644 --- a/docs/en/02_Developer_Guides/02_Controllers/01_Introduction.md +++ b/docs/en/02_Developer_Guides/02_Controllers/01_Introduction.md @@ -9,26 +9,26 @@ subclass the base `Controller` class. **mysite/code/controllers/TeamController.php** ```php - use SilverStripe\Control\Controller; + use SilverStripe\Control\Controller; - class TeamController extends Controller - { - - private static $allowed_actions = [ - 'players', - 'index' - ]; - - public function index(HTTPRequest $request) - { - // .. - } + class TeamController extends Controller + { + + private static $allowed_actions = [ + 'players', + 'index' + ]; + + public function index(HTTPRequest $request) + { + // .. + } - public function players(HTTPRequest $request) - { - print_r($request->allParams()); - } - } + public function players(HTTPRequest $request) + { + print_r($request->allParams()); + } + } ``` @@ -51,13 +51,13 @@ Make sure that after you have modified the `routes.yml` file, that you clear you ```yml - --- - Name: mysiteroutes - After: framework/routes#coreroutes - --- - SilverStripe\Control\Director: - rules: - 'teams//$Action/$ID/$Name': 'TeamController' + --- + Name: mysiteroutes + After: framework/routes#coreroutes + --- + SilverStripe\Control\Director: + rules: + 'teams//$Action/$ID/$Name': 'TeamController' ``` For more information about creating custom routes, see the [Routing](routing) documentation. @@ -81,62 +81,62 @@ Action methods can return one of four main things: **mysite/code/controllers/TeamController.php** ```php - /** - * Return some additional data to the current response that is waiting to go out, this makes $Title set to - * 'MyTeamName' and continues on with generating the response. - */ - public function index(HTTPRequest $request) - { - return [ - 'Title' => 'My Team Name' - ]; - } + /** + * Return some additional data to the current response that is waiting to go out, this makes $Title set to + * 'MyTeamName' and continues on with generating the response. + */ + public function index(HTTPRequest $request) + { + return [ + 'Title' => 'My Team Name' + ]; + } - /** - * We can manually create a response and return that to ignore any previous data. - */ - public function someaction(HTTPRequest $request) - { - $this->setResponse(new HTTPResponse()); - $this->getResponse()->setStatusCode(400); - $this->getResponse()->setBody('invalid'); + /** + * We can manually create a response and return that to ignore any previous data. + */ + public function someaction(HTTPRequest $request) + { + $this->setResponse(new HTTPResponse()); + $this->getResponse()->setStatusCode(400); + $this->getResponse()->setBody('invalid'); - return $this->getResponse(); - } + return $this->getResponse(); + } - /** - * Or, we can modify the response that is waiting to go out. - */ - public function anotheraction(HTTPRequest $request) - { - $this->getResponse()->setStatusCode(400); + /** + * Or, we can modify the response that is waiting to go out. + */ + public function anotheraction(HTTPRequest $request) + { + $this->getResponse()->setStatusCode(400); - return $this->getResponse(); - } + return $this->getResponse(); + } - /** - * We can render HTML and leave SilverStripe to set the response code and body. - */ - public function htmlaction() - { - return $this->customise(new ArrayData([ - 'Title' => 'HTML Action' - ]))->renderWith('MyCustomTemplate'); - } + /** + * We can render HTML and leave SilverStripe to set the response code and body. + */ + public function htmlaction() + { + return $this->customise(new ArrayData([ + 'Title' => 'HTML Action' + ]))->renderWith('MyCustomTemplate'); + } - /** - * We can send stuff to the browser which isn't HTML - */ - public function ajaxaction() - { - $this->getResponse()->setBody(json_encode([ - 'json' => true - ])); + /** + * We can send stuff to the browser which isn't HTML + */ + public function ajaxaction() + { + $this->getResponse()->setBody(json_encode([ + 'json' => true + ])); - $this->getResponse()->addHeader("Content-type", "application/json"); + $this->getResponse()->addHeader("Content-type", "application/json"); - return $this->getResponse(). - } + return $this->getResponse(). + } ``` @@ -167,10 +167,10 @@ Each controller should define a `Link()` method. This should be used to avoid ha **mysite/code/controllers/TeamController.php** ```php - public function Link($action = null) - { - return Controller::join_links('teams', $action); - } + public function Link($action = null) + { + return Controller::join_links('teams', $action); + } ```
diff --git a/docs/en/02_Developer_Guides/02_Controllers/03_Access_Control.md b/docs/en/02_Developer_Guides/02_Controllers/03_Access_Control.md index efe74745a..dc66f4ebe 100644 --- a/docs/en/02_Developer_Guides/02_Controllers/03_Access_Control.md +++ b/docs/en/02_Developer_Guides/02_Controllers/03_Access_Control.md @@ -12,31 +12,31 @@ Any action you define on a controller must be defined in a `$allowed_actions` st directly calling methods that they shouldn't. ```php - use SilverStripe\Control\Controller; + use SilverStripe\Control\Controller; - class MyController extends Controller - { - - private static $allowed_actions = [ - // someaction can be accessed by anyone, any time - 'someaction', + class MyController extends Controller + { + + private static $allowed_actions = [ + // someaction can be accessed by anyone, any time + 'someaction', - // So can otheraction - 'otheraction' => true, - - // restrictedaction can only be people with ADMIN privilege - 'restrictedaction' => 'ADMIN', + // So can otheraction + 'otheraction' => true, + + // restrictedaction can only be people with ADMIN privilege + 'restrictedaction' => 'ADMIN', - // restricted to uses that have the 'CMS_ACCESS_CMSMain' access - 'cmsrestrictedaction' => 'CMS_ACCESS_CMSMain', - - // complexaction can only be accessed if $this->canComplexAction() returns true. - 'complexaction' => '->canComplexAction', + // restricted to uses that have the 'CMS_ACCESS_CMSMain' access + 'cmsrestrictedaction' => 'CMS_ACCESS_CMSMain', + + // complexaction can only be accessed if $this->canComplexAction() returns true. + 'complexaction' => '->canComplexAction', - // complexactioncheck can only be accessed if $this->canComplexAction("MyRestrictedAction", false, 42) is true. - 'complexactioncheck' => '->canComplexAction("MyRestrictedAction", false, 42)', - ]; - } + // complexactioncheck can only be accessed if $this->canComplexAction("MyRestrictedAction", false, 42) is true. + 'complexactioncheck' => '->canComplexAction("MyRestrictedAction", false, 42)', + ]; + } ``` @@ -48,88 +48,88 @@ An action named "index" is white listed by default, unless `allowed_actions` is is specifically restricted. ```php - use SilverStripe\Control\Controller; + use SilverStripe\Control\Controller; - getVar('apikey')) { - return $this->httpError(403, 'No API key provided'); - } - - return 'valid'; - } - } + class MyController extends Controller + { + + private static $allowed_actions = [ + 'myaction' + ]; + + public function myaction($request) + { + if(!$request->getVar('apikey')) { + return $this->httpError(403, 'No API key provided'); + } + + return 'valid'; + } + } ``` @@ -207,23 +207,23 @@ execution. This behavior can be used to implement permission checks. `init` is called for any possible action on the controller and before any specific method such as `index`.
```php - use SilverStripe\Security\Permission; - use SilverStripe\Control\Controller; + use SilverStripe\Security\Permission; + use SilverStripe\Control\Controller; - class MyController extends Controller - { - - private static $allowed_actions = []; - - public function init() - { - parent::init(); + class MyController extends Controller + { + + private static $allowed_actions = []; + + public function init() + { + parent::init(); - if(!Permission::check('ADMIN')) { - return $this->httpError(403); - } - } - } + if(!Permission::check('ADMIN')) { + return $this->httpError(403); + } + } + } ``` diff --git a/docs/en/02_Developer_Guides/02_Controllers/04_Redirection.md b/docs/en/02_Developer_Guides/02_Controllers/04_Redirection.md index e628fe6a5..60e6c78d9 100644 --- a/docs/en/02_Developer_Guides/02_Controllers/04_Redirection.md +++ b/docs/en/02_Developer_Guides/02_Controllers/04_Redirection.md @@ -10,17 +10,17 @@ HTTP header. ```php - $this->redirect('goherenow'); - // redirect to Page::goherenow(), i.e on the contact-us page this will redirect to /contact-us/goherenow/ + $this->redirect('goherenow'); + // redirect to Page::goherenow(), i.e on the contact-us page this will redirect to /contact-us/goherenow/ - $this->redirect('goherenow/'); - // redirect to the URL on yoursite.com/goherenow/. (note the trailing slash) + $this->redirect('goherenow/'); + // redirect to the URL on yoursite.com/goherenow/. (note the trailing slash) - $this->redirect('http://google.com'); - // redirect to http://google.com + $this->redirect('http://google.com'); + // redirect to http://google.com - $this->redirectBack(); - // go back to the previous page. + $this->redirectBack(); + // go back to the previous page. ``` ## Status Codes @@ -28,8 +28,8 @@ HTTP header. The `redirect()` method takes an optional HTTP status code, either `301` for permanent redirects, or `302` for temporary redirects (default). ```php - $this->redirect('/', 302); - // go back to the homepage, don't cache that this page has moved + $this->redirect('/', 302); + // go back to the homepage, don't cache that this page has moved ``` ## Redirection in URL Handling @@ -39,9 +39,9 @@ operator. ```php - private static $url_handlers = [ - 'players/john' => '~>coach' - ]; + private static $url_handlers = [ + 'players/john' => '~>coach' + ]; ``` diff --git a/docs/en/02_Developer_Guides/03_Forms/03_Form_Templates.md b/docs/en/02_Developer_Guides/03_Forms/03_Form_Templates.md index 78c805a07..b314c5fc5 100644 --- a/docs/en/02_Developer_Guides/03_Forms/03_Form_Templates.md +++ b/docs/en/02_Developer_Guides/03_Forms/03_Form_Templates.md @@ -8,12 +8,12 @@ can be rendered out using custom templates using `setTemplate`. ```php - $form = new Form(..); - $form->setTemplate('MyCustomFormTemplate'); + $form = new Form(..); + $form->setTemplate('MyCustomFormTemplate'); - // or, just a field - $field = new TextField(..); - $field->setTemplate('MyCustomTextField'); + // or, just a field + $field = new TextField(..); + $field->setTemplate('MyCustomTextField'); ``` Both `MyCustomTemplate.ss` and `MyCustomTextField.ss` should be located in **mysite/templates/forms/** or the same directory as the core. @@ -37,27 +37,27 @@ For [FormField](api:SilverStripe\Forms\FormField) instances, there are several o ```php - $field = new TextField(); + $field = new TextField(); - $field->setTemplate('CustomTextField'); - // Sets the template for the tag. i.e '' - - $field->setFieldHolderTemplate('CustomTextField_Holder'); - // Sets the template for the wrapper around the text field. i.e - // '
' - // - // The actual FormField is rendered into the holder via the `$Field` - // variable. - // - // setFieldHolder() is used in most `Form` instances and needs to output - // labels, error messages and the like. + $field->setTemplate('CustomTextField'); + // Sets the template for the tag. i.e '' + + $field->setFieldHolderTemplate('CustomTextField_Holder'); + // Sets the template for the wrapper around the text field. i.e + // '
' + // + // The actual FormField is rendered into the holder via the `$Field` + // variable. + // + // setFieldHolder() is used in most `Form` instances and needs to output + // labels, error messages and the like. - $field->setSmallFieldHolderTemplate('CustomTextField_Holder_Small'); - // Sets the template for the wrapper around the text field. - // - // The difference here is the small field holder template is used when the - // field is embedded within another field. For example, if the field is - // part of a `FieldGroup` or `CompositeField` alongside other fields. + $field->setSmallFieldHolderTemplate('CustomTextField_Holder_Small'); + // Sets the template for the wrapper around the text field. + // + // The difference here is the small field holder template is used when the + // field is embedded within another field. For example, if the field is + // part of a `FieldGroup` or `CompositeField` alongside other fields. ``` All templates are rendered within the scope of the [FormField](api:SilverStripe\Forms\FormField). To understand more about Scope within Templates as diff --git a/docs/en/02_Developer_Guides/03_Forms/04_Form_Security.md b/docs/en/02_Developer_Guides/03_Forms/04_Form_Security.md index e4dcc8a32..73c3258aa 100644 --- a/docs/en/02_Developer_Guides/03_Forms/04_Form_Security.md +++ b/docs/en/02_Developer_Guides/03_Forms/04_Form_Security.md @@ -22,16 +22,16 @@ The `SecurityToken` automatically added looks something like: ```php - $form = new Form(..); - echo $form->getSecurityToken()->getValue(); + $form = new Form(..); + echo $form->getSecurityToken()->getValue(); - // 'c443076989a7f24cf6b35fe1360be8683a753e2c' + // 'c443076989a7f24cf6b35fe1360be8683a753e2c' ``` This token value is passed through the rendered Form HTML as a [HiddenField](api:SilverStripe\Forms\HiddenField). ```html - + ``` The token should be present whenever a operation has a side effect such as a `POST` operation. @@ -41,8 +41,8 @@ normally require a security token). ```php - $form = new Form(..); - $form->disableSecurityToken(); + $form = new Form(..); + $form->disableSecurityToken(); ```
@@ -58,13 +58,13 @@ application errors or edge cases. If you need to disable this setting follow the ```php - $form = new Form(..); + $form = new Form(..); - $form->setFormMethod('POST'); - $form->setStrictFormMethodCheck(false); + $form->setFormMethod('POST'); + $form->setStrictFormMethodCheck(false); - // or alternative short notation.. - $form->setFormMethod('POST', false); + // or alternative short notation.. + $form->setFormMethod('POST', false); ``` ## Spam and Bot Attacks diff --git a/docs/en/02_Developer_Guides/03_Forms/05_Form_Transformations.md b/docs/en/02_Developer_Guides/03_Forms/05_Form_Transformations.md index 94561c008..1cf29a535 100644 --- a/docs/en/02_Developer_Guides/03_Forms/05_Form_Transformations.md +++ b/docs/en/02_Developer_Guides/03_Forms/05_Form_Transformations.md @@ -11,36 +11,36 @@ To make an entire [Form](api:SilverStripe\Forms\Form) read-only. ```php - $form = new Form(..); - $form->makeReadonly(); + $form = new Form(..); + $form->makeReadonly(); ``` To make all the fields within a [FieldList](api:SilverStripe\Forms\FieldList) read-only (i.e to make fields read-only but not buttons). ```php - $fields = new FieldList(..); - $fields = $fields->makeReadonly(); + $fields = new FieldList(..); + $fields = $fields->makeReadonly(); ``` To make a [FormField](api:SilverStripe\Forms\FormField) read-only you need to know the name of the form field or call it direct on the object ```php - $field = new TextField(..); - $field = $field->performReadonlyTransformation(); + $field = new TextField(..); + $field = $field->performReadonlyTransformation(); - $fields = new FieldList( - $field - ); + $fields = new FieldList( + $field + ); - // Or, - $field = new TextField(..); - $field->setReadonly(true); + // Or, + $field = new TextField(..); + $field->setReadonly(true); - $fields = new FieldList( - $field - ); + $fields = new FieldList( + $field + ); ``` ## Disabled FormFields @@ -49,11 +49,11 @@ Disabling [FormField](api:SilverStripe\Forms\FormField) instances, sets the `dis a normal form, but set the `disabled` attribute on the `input` tag. ```php - $field = new TextField(..); - $field->setDisabled(true); + $field = new TextField(..); + $field->setDisabled(true); - echo $field->forTemplate(); + echo $field->forTemplate(); - // returns '' + // returns '' ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/03_Forms/06_Tabbed_Forms.md b/docs/en/02_Developer_Guides/03_Forms/06_Tabbed_Forms.md index 8e51173ec..33961f275 100644 --- a/docs/en/02_Developer_Guides/03_Forms/06_Tabbed_Forms.md +++ b/docs/en/02_Developer_Guides/03_Forms/06_Tabbed_Forms.md @@ -23,41 +23,41 @@ display up to two levels of tabs in the interface. ```php - $fields->addFieldToTab('Root.Main', new TextField(..)); + $fields->addFieldToTab('Root.Main', new TextField(..)); ``` ## Removing a field from a tab ```php - $fields->removeFieldFromTab('Root.Main', 'Content'); + $fields->removeFieldFromTab('Root.Main', 'Content'); ``` ## Creating a new tab ```php - $fields->addFieldToTab('Root.MyNewTab', new TextField(..)); + $fields->addFieldToTab('Root.MyNewTab', new TextField(..)); ``` ## Moving a field between tabs ```php - $content = $fields->dataFieldByName('Content'); + $content = $fields->dataFieldByName('Content'); - $fields->removeFieldFromTab('Root.Main', 'Content'); - $fields->addFieldToTab('Root.MyContent', $content); + $fields->removeFieldFromTab('Root.Main', 'Content'); + $fields->addFieldToTab('Root.MyContent', $content); ``` ## Add multiple fields at once ```php - $fields->addFieldsToTab('Root.Content', [ - TextField::create('Name'), - TextField::create('Email') - ]); + $fields->addFieldsToTab('Root.Content', [ + TextField::create('Name'), + TextField::create('Email') + ]); ``` diff --git a/docs/en/02_Developer_Guides/03_Forms/Field_types/02_DateField.md b/docs/en/02_Developer_Guides/03_Forms/Field_types/02_DateField.md index 088cf9dd5..6c059338c 100644 --- a/docs/en/02_Developer_Guides/03_Forms/Field_types/02_DateField.md +++ b/docs/en/02_Developer_Guides/03_Forms/Field_types/02_DateField.md @@ -16,28 +16,28 @@ The following example will add a simple DateField to your Page, allowing you to ```php - use SilverStripe\Forms\DateField; - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\Forms\DateField; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { + class Page extends SiteTree + { - private static $db = [ - 'MyDate' => 'Date', - ]; - - public function getCMSFields() - { - $fields = parent::getCMSFields(); - - $fields->addFieldToTab( - 'Root.Main', - DateField::create('MyDate', 'Enter a date') - ); - - return $fields; - } - } + private static $db = [ + 'MyDate' => 'Date', + ]; + + public function getCMSFields() + { + $fields = parent::getCMSFields(); + + $fields->addFieldToTab( + 'Root.Main', + DateField::create('MyDate', 'Enter a date') + ); + + return $fields; + } + } ``` @@ -48,10 +48,10 @@ This is only necessary if you want to opt-out of the built-in browser localisati ```php - // will display a date in the following format: 31/06/2012 - DateField::create('MyDate') - ->setHTML5(false) - ->setDateFormat('dd/MM/yyyy'); + // will display a date in the following format: 31/06/2012 + DateField::create('MyDate') + ->setHTML5(false) + ->setDateFormat('dd/MM/yyyy'); ```
@@ -66,9 +66,9 @@ Sets the minimum and maximum allowed date values using the `min` and `max` confi ```php - DateField::create('MyDate') - ->setMinDate('-7 days') - ->setMaxDate('2012-12-31') + DateField::create('MyDate') + ->setMinDate('-7 days') + ->setMaxDate('2012-12-31') ``` ## Formatting Hints @@ -79,17 +79,17 @@ field description as an example. ```php - $dateField = DateField::create('MyDate'); + $dateField = DateField::create('MyDate'); - // Show long format as text below the field - $dateField->setDescription(_t( - 'FormField.Example', - 'e.g. {format}', - [ 'format' => $dateField->getDateFormat() ] - )); + // Show long format as text below the field + $dateField->setDescription(_t( + 'FormField.Example', + 'e.g. {format}', + [ 'format' => $dateField->getDateFormat() ] + )); - // Alternatively, set short format as a placeholder in the field - $dateField->setAttribute('placeholder', $dateField->getDateFormat()); + // Alternatively, set short format as a placeholder in the field + $dateField->setAttribute('placeholder', $dateField->getDateFormat()); ```
diff --git a/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md b/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md index c56e39cf1..a69474498 100644 --- a/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md +++ b/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md @@ -17,24 +17,24 @@ functionality. It is usually added through the [DataObject::getCMSFields()](api: ```php - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\HTMLEditor\HTMLEditorField; - use SilverStripe\ORM\DataObject; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\HTMLEditor\HTMLEditorField; + use SilverStripe\ORM\DataObject; - class MyObject extends DataObject - { - - private static $db = [ - 'Content' => 'HTMLText' - ]; - - public function getCMSFields() - { - return new FieldList( - new HTMLEditorField('Content') - ); - } - } + class MyObject extends DataObject + { + + private static $db = [ + 'Content' => 'HTMLText' + ]; + + public function getCMSFields() + { + return new FieldList( + new HTMLEditorField('Content') + ); + } + } ``` @@ -51,25 +51,25 @@ This is particularly useful if you need different configurations for multiple [H ```php - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\HTMLEditor\HTMLEditorField; - use SilverStripe\ORM\DataObject; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\HTMLEditor\HTMLEditorField; + use SilverStripe\ORM\DataObject; - class MyObject extends DataObject - { - private static $db = [ - 'Content' => 'HTMLText', - 'OtherContent' => 'HTMLText' - ]; - - public function getCMSFields() - { - return new FieldList([ - new HTMLEditorField('Content'), - new HTMLEditorField('OtherContent', 'Other content', $this->OtherContent, 'myConfig') - ]); - } - } + class MyObject extends DataObject + { + private static $db = [ + 'Content' => 'HTMLText', + 'OtherContent' => 'HTMLText' + ]; + + public function getCMSFields() + { + return new FieldList([ + new HTMLEditorField('Content'), + new HTMLEditorField('OtherContent', 'Other content', $this->OtherContent, 'myConfig') + ]); + } + } ``` @@ -103,7 +103,7 @@ transparently generate the relevant underlying TinyMCE code. **mysite/_config.php** ```php - HtmlEditorConfig::get('cms')->enablePlugins('media'); + HtmlEditorConfig::get('cms')->enablePlugins('media'); ```
@@ -118,7 +118,7 @@ configuration. Here is an example of adding a `ssmacron` button after the `charm **mysite/_config.php** ```php - HtmlEditorConfig::get('cms')->insertButtonsAfter('charmap', 'ssmacron'); + HtmlEditorConfig::get('cms')->insertButtonsAfter('charmap', 'ssmacron'); ``` Buttons can also be removed: @@ -126,7 +126,7 @@ Buttons can also be removed: **mysite/_config.php** ```php - HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr'); + HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr'); ```
@@ -147,18 +147,18 @@ from the HTML source by the editor. **mysite/_config.php** ```php - // Add start and type attributes for
    , add and with all attributes. - HtmlEditorConfig::get('cms')->setOption( - 'extended_valid_elements', - 'img[class|src|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name|usemap],' . - 'iframe[src|name|width|height|title|align|allowfullscreen|frameborder|marginwidth|marginheight|scrolling],' . - 'object[classid|codebase|width|height|data|type],' . - 'embed[src|type|pluginspage|width|height|autoplay],' . - 'param[name|value],' . - 'map[class|name|id],' . - 'area[shape|coords|href|target|alt],' . - 'ol[start|type]' - ); + // Add start and type attributes for
      , add and with all attributes. + HtmlEditorConfig::get('cms')->setOption( + 'extended_valid_elements', + 'img[class|src|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name|usemap],' . + 'iframe[src|name|width|height|title|align|allowfullscreen|frameborder|marginwidth|marginheight|scrolling],' . + 'object[classid|codebase|width|height|data|type],' . + 'embed[src|type|pluginspage|width|height|autoplay],' . + 'param[name|value],' . + 'map[class|name|id],' . + 'area[shape|coords|href|target|alt],' . + 'ol[start|type]' + ); ```
      @@ -174,7 +174,7 @@ You can enable them through [HtmlEditorConfig::enablePlugins()](api:SilverStripe **mysite/_config.php** ```php - HtmlEditorConfig::get('cms')->enablePlugins(['myplugin' => '../../../mysite/javascript/myplugin/editor_plugin.js']); + HtmlEditorConfig::get('cms')->enablePlugins(['myplugin' => '../../../mysite/javascript/myplugin/editor_plugin.js']); ``` @@ -229,7 +229,7 @@ In case you want to adhere to HTML4 instead, use the following configuration: ```php - HtmlEditorConfig::get('cms')->setOption('element_format', 'html'); + HtmlEditorConfig::get('cms')->setOption('element_format', 'html'); ``` By default, TinyMCE and SilverStripe will generate valid HTML5 markup, but it will strip out HTML5 tags like @@ -254,23 +254,23 @@ Example: Remove field for "image captions" ```php - use SilverStripe\Core\Extension; + use SilverStripe\Core\Extension; - // File: mysite/code/MyToolbarExtension.php - class MyToolbarExtension extends Extension - { - public function updateFieldsForImage(&$fields, $url, $file) - { - $fields->removeByName('CaptionText'); - } - } + // File: mysite/code/MyToolbarExtension.php + class MyToolbarExtension extends Extension + { + public function updateFieldsForImage(&$fields, $url, $file) + { + $fields->removeByName('CaptionText'); + } + } ``` ```php - // File: mysite/_config.php - ModalController::add_extension('MyToolbarExtension'); + // File: mysite/_config.php + ModalController::add_extension('MyToolbarExtension'); ``` Adding functionality is a bit more advanced, you'll most likely @@ -298,17 +298,17 @@ of the CMS you have to take care of instantiate yourself: ```php - use SilverStripe\Admin\ModalController; - use SilverStripe\Control\Controller; + use SilverStripe\Admin\ModalController; + use SilverStripe\Control\Controller; - // File: mysite/code/MyController.php - class MyObjectController extends Controller - { - public function Modals() - { - return ModalController::create($this, "Modals"); - } - } + // File: mysite/code/MyController.php + class MyObjectController extends Controller + { + public function Modals() + { + return ModalController::create($this, "Modals"); + } + } ``` Note: The dialogs rely on CMS-access, e.g. for uploading and browsing files, @@ -316,10 +316,10 @@ so this is considered advanced usage of the field. ```php - // File: mysite/_config.php - HtmlEditorConfig::get('cms')->disablePlugins('ssbuttons'); - HtmlEditorConfig::get('cms')->removeButtons('sslink', 'ssmedia'); - HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'link', 'media'); + // File: mysite/_config.php + HtmlEditorConfig::get('cms')->disablePlugins('ssbuttons'); + HtmlEditorConfig::get('cms')->removeButtons('sslink', 'ssmedia'); + HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'link', 'media'); ``` ### Developing a wrapper to use a different WYSIWYG editors with HTMLEditorField @@ -342,22 +342,22 @@ Assuming you have the module installed, here's how you enable its use in `mysite ```php - HtmlEditorConfig::get('cms')->enablePlugins('spellchecker', 'contextmenu'); - HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'spellchecker'); - HtmlEditorConfig::get('cms')->setOption( - 'spellchecker_rpc_url', - THIRDPARTY_DIR . '/tinymce-spellchecker/rpc.php' - ); - HtmlEditorConfig::get('cms')->setOption('browser_spellcheck', false); + HtmlEditorConfig::get('cms')->enablePlugins('spellchecker', 'contextmenu'); + HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'spellchecker'); + HtmlEditorConfig::get('cms')->setOption( + 'spellchecker_rpc_url', + THIRDPARTY_DIR . '/tinymce-spellchecker/rpc.php' + ); + HtmlEditorConfig::get('cms')->setOption('browser_spellcheck', false); ``` Now change the default spellchecker in `framework/thirdparty/tinymce-spellchecker/config.php`: ```php - - // ... - $config['general.engine'] = 'PSpell'; + + // ... + $config['general.engine'] = 'PSpell'; ``` diff --git a/docs/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md b/docs/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md index 2607d3593..412d723cd 100644 --- a/docs/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md +++ b/docs/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md @@ -8,7 +8,7 @@ tabular data in a format that is easy to view and modify. It can be thought of a ```php - $field = new GridField($name, $title, $list); + $field = new GridField($name, $title, $list); ```
      @@ -29,23 +29,23 @@ actions such as deleting records. ```php - use SilverStripe\Forms\GridField\GridField; - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\Forms\GridField\GridField; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { - - public function getCMSFields() - { - $fields = parent::getCMSFields(); + class Page extends SiteTree + { + + public function getCMSFields() + { + $fields = parent::getCMSFields(); - $fields->addFieldToTab('Root.Pages', - new GridField('Pages', 'All pages', SiteTree::get()) - ); + $fields->addFieldToTab('Root.Pages', + new GridField('Pages', 'All pages', SiteTree::get()) + ); - return $fields; - } - } + return $fields; + } + } ``` This will display a bare bones `GridField` instance under `Pages` tab in the CMS. As we have not specified the @@ -65,82 +65,82 @@ the `getConfig()` method on `GridField`. ```php - use SilverStripe\Forms\GridField\GridField; - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\Forms\GridField\GridField; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { - - public function getCMSFields() - { - $fields = parent::getCMSFields(); + class Page extends SiteTree + { + + public function getCMSFields() + { + $fields = parent::getCMSFields(); - $fields->addFieldToTab('Root.Pages', - $grid = new GridField('Pages', 'All pages', SiteTree::get()) - ); + $fields->addFieldToTab('Root.Pages', + $grid = new GridField('Pages', 'All pages', SiteTree::get()) + ); - // GridField configuration - $config = $grid->getConfig(); + // GridField configuration + $config = $grid->getConfig(); - // - // Modification of existing components can be done by fetching that component. - // Consult the API documentation for each component to determine the configuration - // you can do. - // - $dataColumns = $config->getComponentByType('GridFieldDataColumns'); - - $dataColumns->setDisplayFields([ - 'Title' => 'Title', - 'Link'=> 'URL', - 'LastEdited' => 'Changed' - ]); + // + // Modification of existing components can be done by fetching that component. + // Consult the API documentation for each component to determine the configuration + // you can do. + // + $dataColumns = $config->getComponentByType('GridFieldDataColumns'); + + $dataColumns->setDisplayFields([ + 'Title' => 'Title', + 'Link'=> 'URL', + 'LastEdited' => 'Changed' + ]); - return $fields; - } - } + return $fields; + } + } ``` With the `GridFieldConfig` instance, we can modify the behavior of the `GridField`. ```php - // `GridFieldConfig::create()` will create an empty configuration (no components). - $config = GridFieldConfig::create(); + // `GridFieldConfig::create()` will create an empty configuration (no components). + $config = GridFieldConfig::create(); - // add a component - $config->addComponent(new GridFieldDataColumns()); + // add a component + $config->addComponent(new GridFieldDataColumns()); - // Update the GridField with our custom configuration - $gridField->setConfig($config); + // Update the GridField with our custom configuration + $gridField->setConfig($config); ``` `GridFieldConfig` provides a number of methods to make setting the configuration easier. We can insert a component before another component by passing the second parameter. ```php - $config->addComponent(new GridFieldFilterHeader(), 'GridFieldDataColumns'); + $config->addComponent(new GridFieldFilterHeader(), 'GridFieldDataColumns'); ``` We can add multiple components in one call. ```php - $config->addComponents( - new GridFieldDataColumns(), - new GridFieldToolbarHeader() - ); + $config->addComponents( + new GridFieldDataColumns(), + new GridFieldToolbarHeader() + ); ``` Or, remove a component. ```php - $config->removeComponentsByType('GridFieldDeleteAction'); + $config->removeComponentsByType('GridFieldDeleteAction'); ``` Fetch a component to modify it later on. ```php - $component = $config->getComponentByType('GridFieldFilterHeader') + $component = $config->getComponentByType('GridFieldFilterHeader') ``` Here is a list of components for use bundled with the core framework. Many more components are provided by third-party @@ -169,17 +169,17 @@ A simple read-only and paginated view of records with sortable and searchable he ```php - $config = GridFieldConfig_Base::create(); + $config = GridFieldConfig_Base::create(); - $gridField->setConfig($config); + $gridField->setConfig($config); - // Is the same as adding the following components.. - // .. new GridFieldToolbarHeader() - // .. new GridFieldSortableHeader() - // .. new GridFieldFilterHeader() - // .. new GridFieldDataColumns() - // .. new GridFieldPageCount('toolbar-header-right') - // .. new GridFieldPaginator($itemsPerPage) + // Is the same as adding the following components.. + // .. new GridFieldToolbarHeader() + // .. new GridFieldSortableHeader() + // .. new GridFieldFilterHeader() + // .. new GridFieldDataColumns() + // .. new GridFieldPageCount('toolbar-header-right') + // .. new GridFieldPaginator($itemsPerPage) ``` ### GridFieldConfig_RecordViewer @@ -199,13 +199,13 @@ this record. ```php - $config = GridFieldConfig_RecordViewer::create(); - - $gridField->setConfig($config); + $config = GridFieldConfig_RecordViewer::create(); + + $gridField->setConfig($config); - // Same as GridFieldConfig_Base with the addition of - // .. new GridFieldViewButton(), - // .. new GridFieldDetailForm() + // Same as GridFieldConfig_Base with the addition of + // .. new GridFieldViewButton(), + // .. new GridFieldDetailForm() ``` ### GridFieldConfig_RecordEditor @@ -224,14 +224,14 @@ Permission control for editing and deleting the record uses the `canEdit()` and ```php - $config = GridFieldConfig_RecordEditor::create(); - - $gridField->setConfig($config); + $config = GridFieldConfig_RecordEditor::create(); + + $gridField->setConfig($config); - // Same as GridFieldConfig_RecordViewer with the addition of - // .. new GridFieldAddNewButton(), - // .. new GridFieldEditButton(), - // .. new GridFieldDeleteAction() + // Same as GridFieldConfig_RecordViewer with the addition of + // .. new GridFieldAddNewButton(), + // .. new GridFieldEditButton(), + // .. new GridFieldDeleteAction() ``` ### GridFieldConfig_RelationEditor @@ -239,9 +239,9 @@ Permission control for editing and deleting the record uses the `canEdit()` and Similar to `GridFieldConfig_RecordEditor`, but adds features to work on a record's has-many or many-many relationships. As such, it expects the list used with the `GridField` to be a instance of `RelationList`. ```php - $config = GridFieldConfig_RelationEditor::create(); + $config = GridFieldConfig_RelationEditor::create(); - $gridField->setConfig($config); + $gridField->setConfig($config); ``` This configuration adds the ability to searched for existing records and add a relationship @@ -258,10 +258,10 @@ The `GridFieldDetailForm` component drives the record viewing and editing form. ```php - $form = $gridField->getConfig()->getComponentByType('GridFieldDetailForm'); - $form->setFields(new FieldList( - new TextField('Title') - )); + $form = $gridField->getConfig()->getComponentByType('GridFieldDetailForm'); + $form->setFields(new FieldList( + new TextField('Title') + )); ``` ### many_many_extraFields @@ -277,61 +277,61 @@ The namespace notation is `ManyMany[]`, so for example `Ma ```php - use SilverStripe\Forms\TextField; - use SilverStripe\Forms\GridField\GridField; - use SilverStripe\Forms\GridField\GridFieldConfig_RelationEditor; - use SilverStripe\ORM\DataObject; + use SilverStripe\Forms\TextField; + use SilverStripe\Forms\GridField\GridField; + use SilverStripe\Forms\GridField\GridFieldConfig_RelationEditor; + use SilverStripe\ORM\DataObject; - class Team extends DataObject - { - - private static $db = [ - 'Name' => 'Text' - ]; + class Team extends DataObject + { + + private static $db = [ + 'Name' => 'Text' + ]; - public static $many_many = [ - 'Players' => 'Player' - ]; - } - class Player extends DataObject - { - - private static $db = [ - 'Name' => 'Text' - ]; - - public static $many_many = [ - 'Teams' => 'Team' - ]; - - public static $many_many_extraFields = [ - 'Teams' => [ - 'Position' => 'Text' - ] - ]; + public static $many_many = [ + 'Players' => 'Player' + ]; + } + class Player extends DataObject + { + + private static $db = [ + 'Name' => 'Text' + ]; + + public static $many_many = [ + 'Teams' => 'Team' + ]; + + public static $many_many_extraFields = [ + 'Teams' => [ + 'Position' => 'Text' + ] + ]; - public function getCMSFields() - { - $fields = parent::getCMSFields(); + public function getCMSFields() + { + $fields = parent::getCMSFields(); - if($this->ID) { - $teamFields = singleton('Team')->getCMSFields(); - $teamFields->addFieldToTab( - 'Root.Main', - // The "ManyMany[]" convention - new TextField('ManyMany[Position]', 'Current Position') - ); + if($this->ID) { + $teamFields = singleton('Team')->getCMSFields(); + $teamFields->addFieldToTab( + 'Root.Main', + // The "ManyMany[]" convention + new TextField('ManyMany[Position]', 'Current Position') + ); - $config = GridFieldConfig_RelationEditor::create(); - $config->getComponentByType('GridFieldDetailForm')->setFields($teamFields); + $config = GridFieldConfig_RelationEditor::create(); + $config->getComponentByType('GridFieldDetailForm')->setFields($teamFields); - $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config); - $fields->findOrMakeTab('Root.Teams')->replaceField('Teams', $gridField); - } + $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config); + $fields->findOrMakeTab('Root.Teams')->replaceField('Teams', $gridField); + } - return $fields; - } - } + return $fields; + } + } ``` @@ -354,8 +354,8 @@ bottom right of the table. ```php - $config->addComponent(new GridFieldButtonRow('after')); - $config->addComponent(new GridFieldPrintButton('buttons-after-right')); + $config->addComponent(new GridFieldButtonRow('after')); + $config->addComponent(new GridFieldPrintButton('buttons-after-right')); ``` ### Creating your own Fragments @@ -366,16 +366,16 @@ create an area rendered before the table wrapped in a simple `
      `. ```php - class MyAreaComponent implements GridField_HTMLProvider - { - - public function getHTMLFragments( $gridField) - { - return [ - 'before' => '
      $DefineFragment(my-area)
      ' - ]; - } - } + class MyAreaComponent implements GridField_HTMLProvider + { + + public function getHTMLFragments( $gridField) + { + return [ + 'before' => '
      $DefineFragment(my-area)
      ' + ]; + } + } ``` @@ -389,16 +389,16 @@ Now you can add other components into this area by returning them as an array fr ```php - class MyShareLinkComponent implements GridField_HTMLProvider - { - - public function getHTMLFragments( $gridField) - { - return [ - 'my-area' => '...' - ]; - } - } + class MyShareLinkComponent implements GridField_HTMLProvider + { + + public function getHTMLFragments( $gridField) + { + return [ + 'my-area' => '...' + ]; + } + } ``` @@ -406,7 +406,7 @@ Your new area can also be used by existing components, e.g. the [GridFieldPrintB ```php - new GridFieldPrintButton('my-component-area'); + new GridFieldPrintButton('my-component-area'); ``` ## Creating a Custom GridFieldComponent diff --git a/docs/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md b/docs/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md index 93b7dcd9e..7bbe07fb0 100644 --- a/docs/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md +++ b/docs/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md @@ -11,66 +11,66 @@ code for a `Form` is to create it as a subclass to `Form`. Let's look at a examp ```php - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\RequiredFields; - use SilverStripe\Forms\Form; - use SilverStripe\Forms\HeaderField; - use SilverStripe\Forms\OptionsetField; - use SilverStripe\Forms\CompositeField; - use SilverStripe\Forms\CheckboxSetField; - use SilverStripe\Forms\NumericField; - use SilverStripe\Forms\FormAction; - use SilverStripe\CMS\Controllers\ContentController; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\RequiredFields; + use SilverStripe\Forms\Form; + use SilverStripe\Forms\HeaderField; + use SilverStripe\Forms\OptionsetField; + use SilverStripe\Forms\CompositeField; + use SilverStripe\Forms\CheckboxSetField; + use SilverStripe\Forms\NumericField; + use SilverStripe\Forms\FormAction; + use SilverStripe\CMS\Controllers\ContentController; - class PageController extends ContentController - { - - public function SearchForm() - { - $fields = new FieldList( - HeaderField::create('Header', 'Step 1. Basics'), - OptionsetField::create('Type', '', [ - 'foo' => 'Search Foo', - 'bar' => 'Search Bar', - 'baz' => 'Search Baz' - ]), + class PageController extends ContentController + { + + public function SearchForm() + { + $fields = new FieldList( + HeaderField::create('Header', 'Step 1. Basics'), + OptionsetField::create('Type', '', [ + 'foo' => 'Search Foo', + 'bar' => 'Search Bar', + 'baz' => 'Search Baz' + ]), - CompositeField::create( - HeaderField::create('Header2', 'Step 2. Advanced '), - CheckboxSetField::create('Foo', 'Select Option', [ - 'qux' => 'Search Qux' - ]), + CompositeField::create( + HeaderField::create('Header2', 'Step 2. Advanced '), + CheckboxSetField::create('Foo', 'Select Option', [ + 'qux' => 'Search Qux' + ]), - CheckboxSetField::create('Category', 'Category', [ - 'Foo' => 'Foo', - 'Bar' => 'Bar' - ]), + CheckboxSetField::create('Category', 'Category', [ + 'Foo' => 'Foo', + 'Bar' => 'Bar' + ]), - NumericField::create('Minimum', 'Minimum'), - NumericField::create('Maximum', 'Maximum') - ) - ); - - $actions = new FieldList( - FormAction::create('doSearchForm', 'Search') - ); - - $required = new RequiredFields([ - 'Type' - ]); + NumericField::create('Minimum', 'Minimum'), + NumericField::create('Maximum', 'Maximum') + ) + ); + + $actions = new FieldList( + FormAction::create('doSearchForm', 'Search') + ); + + $required = new RequiredFields([ + 'Type' + ]); - $form = new Form($this, 'SearchForm', $fields, $actions, $required); - $form->setFormMethod('GET'); - - $form->addExtraClass('no-action-styles'); - $form->disableSecurityToken(); - $form->loadDataFrom($_REQUEST); - - return $form; - } + $form = new Form($this, 'SearchForm', $fields, $actions, $required); + $form->setFormMethod('GET'); + + $form->addExtraClass('no-action-styles'); + $form->disableSecurityToken(); + $form->loadDataFrom($_REQUEST); + + return $form; + } - .. - } + .. + } ``` @@ -81,70 +81,70 @@ should be. Good practice would be to move this to a subclass and create a new in ```php - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\RequiredFields; - use SilverStripe\Forms\HeaderField; - use SilverStripe\Forms\OptionsetField; - use SilverStripe\Forms\CompositeField; - use SilverStripe\Forms\CheckboxSetField; - use SilverStripe\Forms\NumericField; - use SilverStripe\Forms\FormAction; - use SilverStripe\Forms\Form; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\RequiredFields; + use SilverStripe\Forms\HeaderField; + use SilverStripe\Forms\OptionsetField; + use SilverStripe\Forms\CompositeField; + use SilverStripe\Forms\CheckboxSetField; + use SilverStripe\Forms\NumericField; + use SilverStripe\Forms\FormAction; + use SilverStripe\Forms\Form; - class SearchForm extends Form - { + class SearchForm extends Form + { - /** - * Our constructor only requires the controller and the name of the form - * method. We'll create the fields and actions in here. - * - */ - public function __construct($controller, $name) - { - $fields = new FieldList( - HeaderField::create('Header', 'Step 1. Basics'), - OptionsetField::create('Type', '', [ - 'foo' => 'Search Foo', - 'bar' => 'Search Bar', - 'baz' => 'Search Baz' - ]), + /** + * Our constructor only requires the controller and the name of the form + * method. We'll create the fields and actions in here. + * + */ + public function __construct($controller, $name) + { + $fields = new FieldList( + HeaderField::create('Header', 'Step 1. Basics'), + OptionsetField::create('Type', '', [ + 'foo' => 'Search Foo', + 'bar' => 'Search Bar', + 'baz' => 'Search Baz' + ]), - CompositeField::create( - HeaderField::create('Header2', 'Step 2. Advanced '), - CheckboxSetField::create('Foo', 'Select Option', [ - 'qux' => 'Search Qux' - ]), + CompositeField::create( + HeaderField::create('Header2', 'Step 2. Advanced '), + CheckboxSetField::create('Foo', 'Select Option', [ + 'qux' => 'Search Qux' + ]), - CheckboxSetField::create('Category', 'Category', [ - 'Foo' => 'Foo', - 'Bar' => 'Bar' - ]), + CheckboxSetField::create('Category', 'Category', [ + 'Foo' => 'Foo', + 'Bar' => 'Bar' + ]), - NumericField::create('Minimum', 'Minimum'), - NumericField::create('Maximum', 'Maximum') - ) - ); - - $actions = new FieldList( - FormAction::create('doSearchForm', 'Search') - ); - - $required = new RequiredFields([ - 'Type' - ]); + NumericField::create('Minimum', 'Minimum'), + NumericField::create('Maximum', 'Maximum') + ) + ); + + $actions = new FieldList( + FormAction::create('doSearchForm', 'Search') + ); + + $required = new RequiredFields([ + 'Type' + ]); - // now we create the actual form with our fields and actions defined - // within this class - parent::__construct($controller, $name, $fields, $actions, $required); + // now we create the actual form with our fields and actions defined + // within this class + parent::__construct($controller, $name, $fields, $actions, $required); - // any modifications we need to make to the form. - $this->setFormMethod('GET'); - - $this->addExtraClass('no-action-styles'); - $this->disableSecurityToken(); - $this->loadDataFrom($_REQUEST); - } - } + // any modifications we need to make to the form. + $this->setFormMethod('GET'); + + $this->addExtraClass('no-action-styles'); + $this->disableSecurityToken(); + $this->loadDataFrom($_REQUEST); + } + } ``` @@ -154,21 +154,21 @@ Our controller will now just have to create a new instance of this form object. ```php - use SearchForm; - use SilverStripe\CMS\Controllers\ContentController; + use SearchForm; + use SilverStripe\CMS\Controllers\ContentController; - class PageController extends ContentController - { - - private static $allowed_actions = [ - 'SearchForm', - ]; - - public function SearchForm() - { - return new SearchForm($this, 'SearchForm'); - } - } + class PageController extends ContentController + { + + private static $allowed_actions = [ + 'SearchForm', + ]; + + public function SearchForm() + { + return new SearchForm($this, 'SearchForm'); + } + } ``` diff --git a/docs/en/02_Developer_Guides/03_Forms/How_Tos/02_Lightweight_Form.md b/docs/en/02_Developer_Guides/03_Forms/How_Tos/02_Lightweight_Form.md index 176ffcd11..4a1a69138 100644 --- a/docs/en/02_Developer_Guides/03_Forms/How_Tos/02_Lightweight_Form.md +++ b/docs/en/02_Developer_Guides/03_Forms/How_Tos/02_Lightweight_Form.md @@ -13,22 +13,22 @@ totally custom template to meet our needs. To do this, we'll provide the class w ```php - - public function SearchForm() - { - $fields = new FieldList( - TextField::create('q') - ); + + public function SearchForm() + { + $fields = new FieldList( + TextField::create('q') + ); - $actions = new FieldList( - FormAction::create('doSearch', 'Search') - ); + $actions = new FieldList( + FormAction::create('doSearch', 'Search') + ); - $form = new Form($this, 'SearchForm', $fields, $actions); - $form->setTemplate('SearchForm'); + $form = new Form($this, 'SearchForm', $fields, $actions); + $form->setTemplate('SearchForm'); - return $form; - } + return $form; + } ``` **mysite/templates/Includes/SearchForm.ss** @@ -36,15 +36,15 @@ totally custom template to meet our needs. To do this, we'll provide the class w ```ss -
      -
      - $Fields.dataFieldByName(q) -
      - -
      - <% loop $Actions %>$Field<% end_loop %> -
      -
      +
      +
      + $Fields.dataFieldByName(q) +
      + +
      + <% loop $Actions %>$Field<% end_loop %> +
      +
      ``` `SearchForm.ss` will be executed within the scope of the `Form` object so has access to any of the methods and diff --git a/docs/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md b/docs/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md index 70befc562..fd2718896 100644 --- a/docs/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md +++ b/docs/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md @@ -19,66 +19,66 @@ below: ```php - class GridFieldCustomAction implements GridField_ColumnProvider, GridField_ActionProvider - { + class GridFieldCustomAction implements GridField_ColumnProvider, GridField_ActionProvider + { - public function augmentColumns($gridField, &$columns) - { - if(!in_array('Actions', $columns)) { - $columns[] = 'Actions'; - } - } + public function augmentColumns($gridField, &$columns) + { + if(!in_array('Actions', $columns)) { + $columns[] = 'Actions'; + } + } - public function getColumnAttributes($gridField, $record, $columnName) - { - return ['class' => 'grid-field__col-compact']; - } + public function getColumnAttributes($gridField, $record, $columnName) + { + return ['class' => 'grid-field__col-compact']; + } - public function getColumnMetadata($gridField, $columnName) - { - if($columnName == 'Actions') { - return ['title' => '']; - } - } + public function getColumnMetadata($gridField, $columnName) + { + if($columnName == 'Actions') { + return ['title' => '']; + } + } - public function getColumnsHandled($gridField) - { - return ['Actions']; - } + public function getColumnsHandled($gridField) + { + return ['Actions']; + } - public function getColumnContent($gridField, $record, $columnName) - { - if(!$record->canEdit()) return; + public function getColumnContent($gridField, $record, $columnName) + { + if(!$record->canEdit()) return; - $field = GridField_FormAction::create( - $gridField, - 'CustomAction'.$record->ID, - 'Do Action', - "docustomaction", - ['RecordID' => $record->ID] - ); + $field = GridField_FormAction::create( + $gridField, + 'CustomAction'.$record->ID, + 'Do Action', + "docustomaction", + ['RecordID' => $record->ID] + ); - return $field->Field(); - } + return $field->Field(); + } - public function getActions($gridField) - { - return ['docustomaction']; - } + public function getActions($gridField) + { + return ['docustomaction']; + } - public function handleAction(GridField $gridField, $actionName, $arguments, $data) - { - if($actionName == 'docustomaction') { - // perform your action here + public function handleAction(GridField $gridField, $actionName, $arguments, $data) + { + if($actionName == 'docustomaction') { + // perform your action here - // output a success message to the user - Controller::curr()->getResponse()->setStatusCode( - 200, - 'Do Custom Action Done.' - ); - } - } - } + // output a success message to the user + Controller::curr()->getResponse()->setStatusCode( + 200, + 'Do Custom Action Done.' + ); + } + } + } ``` @@ -91,14 +91,14 @@ manipulating the `GridFieldConfig` instance if required. ```php - // option 1: creating a new GridField with the CustomAction - $config = GridFieldConfig::create(); - $config->addComponent(new GridFieldCustomAction()); + // option 1: creating a new GridField with the CustomAction + $config = GridFieldConfig::create(); + $config->addComponent(new GridFieldCustomAction()); - $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config); + $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config); - // option 2: adding the CustomAction to an exisitng GridField - $gridField->getConfig()->addComponent(new GridFieldCustomAction()); + // option 2: adding the CustomAction to an exisitng GridField + $gridField->getConfig()->addComponent(new GridFieldCustomAction()); ``` For documentation on adding a Component to a `GridField` created by `ModelAdmin` diff --git a/docs/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md b/docs/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md index 6932cf2b6..5344eb683 100644 --- a/docs/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md +++ b/docs/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md @@ -6,34 +6,34 @@ Let's start by defining a new `ContactPage` page type: ```php - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\TextField; - use SilverStripe\Forms\EmailField; - use SilverStripe\Forms\TextareaField; - use SilverStripe\Forms\FormAction; - use SilverStripe\Forms\Form; - use Page; - use PageController; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\TextField; + use SilverStripe\Forms\EmailField; + use SilverStripe\Forms\TextareaField; + use SilverStripe\Forms\FormAction; + use SilverStripe\Forms\Form; + use Page; + use PageController; - class ContactPage extends Page - { - } - class ContactPageController extends PageController - { - private static $allowed_actions = ['Form']; - public function Form() - { - $fields = new FieldList( - new TextField('Name'), - new EmailField('Email'), - new TextareaField('Message') - ); - $actions = new FieldList( - new FormAction('submit', 'Submit') - ); - return new Form($this, 'Form', $fields, $actions); - } - } + class ContactPage extends Page + { + } + class ContactPageController extends PageController + { + private static $allowed_actions = ['Form']; + public function Form() + { + $fields = new FieldList( + new TextField('Name'), + new EmailField('Email'), + new TextareaField('Message') + ); + $actions = new FieldList( + new FormAction('submit', 'Submit') + ); + return new Form($this, 'Form', $fields, $actions); + } + } ``` @@ -43,27 +43,27 @@ There's quite a bit in this function, so we'll step through one piece at a time. ```php - $fields = new FieldList( - new TextField('Name'), - new EmailField('Email'), - new TextareaField('Message') - ); + $fields = new FieldList( + new TextField('Name'), + new EmailField('Email'), + new TextareaField('Message') + ); ``` First we create all the fields we want in the contact form, and put them inside a FieldList. You can find a list of form fields available on the [FormField](api:SilverStripe\Forms\FormField) page. ```php - $actions = FieldList( - new FormAction('submit', 'Submit') - ); + $actions = FieldList( + new FormAction('submit', 'Submit') + ); ``` We then create a [FieldList](api:SilverStripe\Forms\FieldList) of the form actions, or the buttons that submit the form. Here we add a single form action, with the name 'submit', and the label 'Submit'. We'll use the name of the form action later. ```php - return new Form($this, 'Form', $fields, $actions); + return new Form($this, 'Form', $fields, $actions); ``` Finally we create the `Form` object and return it. The first argument is the controller that the form is on – this is almost always $this. The second argument is the name of the form – this has to be the same as the name of the function that creates the form, so we've used 'Form'. The third and fourth arguments are the fields and actions we created earlier. @@ -82,36 +82,36 @@ Now that we have a contact form, we need some way of collecting the data submitt ```php - use SilverStripe\Control\Email\Email; - use PageController; + use SilverStripe\Control\Email\Email; + use PageController; - class ContactPageController extends PageController - { - private static $allowed_actions = ['Form']; - public function Form() - { - // ... - } - public function submit($data, $form) - { - $email = new Email(); - - $email->setTo('siteowner@mysite.com'); - $email->setFrom($data['Email']); - $email->setSubject("Contact Message from {$data["Name"]}"); - - $messageBody = " -

      Name: {$data['Name']}

      -

      Message: {$data['Message']}

      - "; - $email->setBody($messageBody); - $email->send(); - return [ - 'Content' => '

      Thank you for your feedback.

      ', - 'Form' => '' - ]; - } - } + class ContactPageController extends PageController + { + private static $allowed_actions = ['Form']; + public function Form() + { + // ... + } + public function submit($data, $form) + { + $email = new Email(); + + $email->setTo('siteowner@mysite.com'); + $email->setFrom($data['Email']); + $email->setSubject("Contact Message from {$data["Name"]}"); + + $messageBody = " +

      Name: {$data['Name']}

      +

      Message: {$data['Message']}

      + "; + $email->setBody($messageBody); + $email->send(); + return [ + 'Content' => '

      Thank you for your feedback.

      ', + 'Form' => '' + ]; + } + } ``` @@ -137,12 +137,12 @@ The framework comes with a predefined validator called [RequiredFields](api:Silv ```php - public function Form() - { - // ... - $validator = new RequiredFields('Name', 'Message'); - return new Form($this, 'Form', $fields, $actions, $validator); - } + public function Form() + { + // ... + $validator = new RequiredFields('Name', 'Message'); + return new Form($this, 'Form', $fields, $actions, $validator); + } ``` We've created a RequiredFields object, passing the name of the fields we want to be required. The validator we have created is then passed as the fifth argument of the form constructor. If we now try to submit the form without filling out the required fields, JavaScript validation will kick in, and the user will be presented with a message about the missing fields. If the user has JavaScript disabled, PHP validation will kick in when the form is submitted, and the user will be redirected back to the Form with messages about their missing fields. diff --git a/docs/en/02_Developer_Guides/04_Configuration/00_Configuration.md b/docs/en/02_Developer_Guides/04_Configuration/00_Configuration.md index 503838845..ac0875014 100644 --- a/docs/en/02_Developer_Guides/04_Configuration/00_Configuration.md +++ b/docs/en/02_Developer_Guides/04_Configuration/00_Configuration.md @@ -29,23 +29,23 @@ be marked `private static` and follow the `lower_case_with_underscores` structur ```php - use Page; + use Page; - class MyClass extends Page - { + class MyClass extends Page + { - /** - * @config - */ - private static $option_one = true; + /** + * @config + */ + private static $option_one = true; - /** - * @config - */ - private static $option_two = []; + /** + * @config + */ + private static $option_two = []; - // .. - } + // .. + } ``` @@ -55,12 +55,12 @@ This can be done by calling the static method [Config::inst()](api:SilverStripe\ ```php - $config = Config::inst()->get('MyClass', 'property'); + $config = Config::inst()->get('MyClass', 'property'); ``` Or through the `config()` object on the class. ```php - $config = $this->config()->get('property')'; + $config = $this->config()->get('property')'; ``` Note that by default `Config::inst()` returns only an immutable version of config. Use `Config::modify()` @@ -87,44 +87,44 @@ To set those configuration options on our previously defined class we can define ```yml - MyClass: - option_one: false - option_two: - - Foo - - Bar - - Baz + MyClass: + option_one: false + option_two: + - Foo + - Bar + - Baz ``` To use those variables in your application code: ```php - $me = new MyClass(); + $me = new MyClass(); - echo $me->config()->option_one; - // returns false + echo $me->config()->option_one; + // returns false - echo implode(', ', $me->config()->option_two); - // returns 'Foo, Bar, Baz' + echo implode(', ', $me->config()->option_two); + // returns 'Foo, Bar, Baz' - echo Config::inst()->get('MyClass', 'option_one'); - // returns false + echo Config::inst()->get('MyClass', 'option_one'); + // returns false - echo implode(', ', Config::inst()->get('MyClass', 'option_two')); - // returns 'Foo, Bar, Baz' + echo implode(', ', Config::inst()->get('MyClass', 'option_two')); + // returns 'Foo, Bar, Baz' - Config::modify()->set('MyClass', 'option_one', true); + Config::modify()->set('MyClass', 'option_one', true); - echo Config::inst()->get('MyClass', 'option_one'); - // returns true + echo Config::inst()->get('MyClass', 'option_one'); + // returns true - // You can also use the static version - MyClass::config()->option_two = [ - 'Qux' - ]; + // You can also use the static version + MyClass::config()->option_two = [ + 'Qux' + ]; - echo implode(', ', MyClass::config()->option_one); - // returns 'Qux' + echo implode(', ', MyClass::config()->option_one); + // returns 'Qux' ``` @@ -204,16 +204,16 @@ The name of the files within the applications `_config` directly are arbitrary. The structure of each YAML file is a series of headers and values separated by YAML document separators. ```yml - --- - Name: adminroutes - After: - - '#rootroutes' - - '#coreroutes' - --- - Director: - rules: - 'admin': 'AdminRootController' - --- + --- + Name: adminroutes + After: + - '#rootroutes' + - '#coreroutes' + --- + Director: + rules: + 'admin': 'AdminRootController' + --- ```
      @@ -254,16 +254,16 @@ keys is a list of reference paths to other value sections. A basic example: ```yml - --- - Name: adminroutes - After: - - '#rootroutes' - - '#coreroutes' - --- - Director: - rules: - 'admin': 'AdminRootController' - --- + --- + Name: adminroutes + After: + - '#rootroutes' + - '#coreroutes' + --- + Director: + rules: + 'admin': 'AdminRootController' + --- ``` You do not have to specify all portions of a reference path. Any portion may be replaced with a wildcard "\*", or left @@ -320,19 +320,19 @@ For instance, to add a property to "foo" when a module exists, and "bar" otherwi ```yml - --- - Only: - moduleexists: 'MyFineModule' - --- - MyClass: - property: 'foo' - --- - Except: - moduleexists: 'MyFineModule' - --- - MyClass: - property: 'bar' - --- + --- + Only: + moduleexists: 'MyFineModule' + --- + MyClass: + property: 'foo' + --- + Except: + moduleexists: 'MyFineModule' + --- + MyClass: + property: 'bar' + --- ``` Multiple conditions of the same type can be declared via array format @@ -341,11 +341,11 @@ Multiple conditions of the same type can be declared via array format ```yaml - --- - Only: - moduleexists: - - 'silverstripe/blog' - - 'silverstripe/lumberjack' + --- + Only: + moduleexists: + - 'silverstripe/blog' + - 'silverstripe/lumberjack' ```
      diff --git a/docs/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md b/docs/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md index 5132c272d..17830ba2f 100644 --- a/docs/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md +++ b/docs/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md @@ -13,23 +13,23 @@ throughout the site. Out of the box this includes selecting the current site the ```ss - $SiteConfig.Title - $SiteConfig.Tagline - - <% with $SiteConfig %> - $Title $AnotherField - <% end_with %> + $SiteConfig.Title + $SiteConfig.Tagline + + <% with $SiteConfig %> + $Title $AnotherField + <% end_with %> ``` To access variables in the PHP: ```php - $config = SiteConfig::current_site_config(); - - echo $config->Title; + $config = SiteConfig::current_site_config(); + + echo $config->Title; - // returns "Website Name" + // returns "Website Name" ``` ## Extending SiteConfig @@ -40,23 +40,23 @@ To extend the options available in the panel, define your own fields via a [Data ```php - use SilverStripe\Forms\HTMLEditor\HTMLEditorField; - use SilverStripe\ORM\DataExtension; + use SilverStripe\Forms\HTMLEditor\HTMLEditorField; + use SilverStripe\ORM\DataExtension; - class CustomSiteConfig extends DataExtension - { - - private static $db = [ - 'FooterContent' => 'HTMLText' - ]; - - public function updateCMSFields(FieldList $fields) - { - $fields->addFieldToTab("Root.Main", - new HTMLEditorField("FooterContent", "Footer Content") - ); - } - } + class CustomSiteConfig extends DataExtension + { + + private static $db = [ + 'FooterContent' => 'HTMLText' + ]; + + public function updateCMSFields(FieldList $fields) + { + $fields->addFieldToTab("Root.Main", + new HTMLEditorField("FooterContent", "Footer Content") + ); + } + } ``` @@ -67,9 +67,9 @@ Then activate the extension. ```yml - Silverstripe\SiteConfig\SiteConfig: - extensions: - - CustomSiteConfig + Silverstripe\SiteConfig\SiteConfig: + extensions: + - CustomSiteConfig ```
      diff --git a/docs/en/02_Developer_Guides/05_Extending/01_Extensions.md b/docs/en/02_Developer_Guides/05_Extending/01_Extensions.md index d43ffc81b..12b341c93 100644 --- a/docs/en/02_Developer_Guides/05_Extending/01_Extensions.md +++ b/docs/en/02_Developer_Guides/05_Extending/01_Extensions.md @@ -19,21 +19,21 @@ and `RequestHandler`. You can still apply extensions to descendants of these cla ```php - use SilverStripe\ORM\DataExtension; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { + class MyMemberExtension extends DataExtension + { - private static $db = [ - 'DateOfBirth' => 'SS_Datetime' - ]; + private static $db = [ + 'DateOfBirth' => 'SS_Datetime' + ]; - public function SayHi() - { - // $this->owner refers to the original instance. In this case a `Member`. - return "Hi " . $this->owner->Name; - } - } + public function SayHi() + { + // $this->owner refers to the original instance. In this case a `Member`. + return "Hi " . $this->owner->Name; + } + } ``` @@ -49,16 +49,16 @@ we want to add the `MyMemberExtension` too. To activate this extension, add the ```yml - Member: - extensions: - - MyMemberExtension + Member: + extensions: + - MyMemberExtension ``` Alternatively, we can add extensions through PHP code (in the `_config.php` file). ```php - Member::add_extension('MyMemberExtension'); + Member::add_extension('MyMemberExtension'); ``` This class now defines a `MyMemberExtension` that applies to all `Member` instances on the website. It will have @@ -82,25 +82,25 @@ $has_one etc. ```php - use SilverStripe\ORM\DataExtension; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { + class MyMemberExtension extends DataExtension + { - private static $db = [ - 'Position' => 'Varchar', - ]; + private static $db = [ + 'Position' => 'Varchar', + ]; - private static $has_one = [ - 'Image' => 'Image', - ]; + private static $has_one = [ + 'Image' => 'Image', + ]; - public function SayHi() - { - // $this->owner refers to the original instance. In this case a `Member`. - return "Hi " . $this->owner->Name; - } - } + public function SayHi() + { + // $this->owner refers to the original instance. In this case a `Member`. + return "Hi " . $this->owner->Name; + } + } ``` @@ -109,8 +109,8 @@ $has_one etc. ```ss - $CurrentMember.Position - $CurrentMember.Image + $CurrentMember.Position + $CurrentMember.Image ``` ## Adding Methods @@ -122,18 +122,18 @@ we added a `SayHi` method which is unique to our extension. ```ss -

      $CurrentMember.SayHi

      +

      $CurrentMember.SayHi

      - // "Hi Sam" + // "Hi Sam" ``` **mysite/code/Page.php** ```php - $member = Security::getCurrentUser(); - echo $member->SayHi; + $member = Security::getCurrentUser(); + echo $member->SayHi; - // "Hi Sam" + // "Hi Sam" ``` ## Modifying Existing Methods @@ -146,14 +146,14 @@ through the `extend()` method of the [Extensible](api:SilverStripe\Core\Extensib ```php - public function getValidator() - { - // .. - - $this->extend('updateValidator', $validator); + public function getValidator() + { + // .. + + $this->extend('updateValidator', $validator); - // .. - } + // .. + } ``` Extension Hooks can be located anywhere in the method and provide a point for any `Extension` instances to modify the @@ -165,19 +165,19 @@ validator by defining the `updateValidator` method. ```php - use SilverStripe\ORM\DataExtension; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { + class MyMemberExtension extends DataExtension + { - // .. + // .. - public function updateValidator($validator) - { - // we want to make date of birth required for each member - $validator->addRequiredField('DateOfBirth'); - } - } + public function updateValidator($validator) + { + // we want to make date of birth required for each member + $validator->addRequiredField('DateOfBirth'); + } + } ```
      @@ -189,28 +189,28 @@ extension. The `CMS` provides a `updateCMSFields` Extension Hook to tie into. ```php - use SilverStripe\Forms\TextField; - use SilverStripe\AssetAdmin\Forms\UploadField; - use SilverStripe\ORM\DataExtension; + use SilverStripe\Forms\TextField; + use SilverStripe\AssetAdmin\Forms\UploadField; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { + class MyMemberExtension extends DataExtension + { - private static $db = [ - 'Position' => 'Varchar', - ]; + private static $db = [ + 'Position' => 'Varchar', + ]; - private static $has_one = [ - 'Image' => 'Image', - ]; + private static $has_one = [ + 'Image' => 'Image', + ]; - public function updateCMSFields(FieldList $fields) - { - $fields->push(new TextField('Position')); - $fields->push($upload = new UploadField('Image', 'Profile Image')); - $upload->setAllowedFileCategories('image/supported'); - } - } + public function updateCMSFields(FieldList $fields) + { + $fields->push(new TextField('Position')); + $fields->push($upload = new UploadField('Image', 'Profile Image')); + $upload->setAllowedFileCategories('image/supported'); + } + } ``` @@ -221,14 +221,14 @@ which allows an Extension to modify the results. ```php - public function Foo() - { - $foo = // .. + public function Foo() + { + $foo = // .. - $this->extend('updateFoo', $foo); + $this->extend('updateFoo', $foo); - return $foo; - } + return $foo; + } ``` The convention for extension hooks is to provide an `update{$Function}` hook at the end before you return the result. If @@ -241,17 +241,17 @@ In your [Extension](api:SilverStripe\Core\Extension) class you can only refer to ```php - use SilverStripe\ORM\DataExtension; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { + class MyMemberExtension extends DataExtension + { - public function updateFoo($foo) - { - // outputs the original class - var_dump($this->owner); - } - } + public function updateFoo($foo) + { + // outputs the original class + var_dump($this->owner); + } + } ``` ## Checking to see if an Object has an Extension @@ -259,13 +259,13 @@ In your [Extension](api:SilverStripe\Core\Extension) class you can only refer to To see what extensions are currently enabled on an object, use the [getExtensionInstances()](api:SilverStripe\Core\Extensible::getExtensionInstances()) and [hasExtension()](api:SilverStripe\Core\Extensible::hasExtension()) methods of the [Extensible](api:SilverStripe\Core\Extensible) trait. ```php - $member = Security::getCurrentUser(); + $member = Security::getCurrentUser(); - print_r($member->getExtensionInstances()); - - if($member->hasExtension('MyCustomMemberExtension')) { - // .. - } + print_r($member->getExtensionInstances()); + + if($member->hasExtension('MyCustomMemberExtension')) { + // .. + } ``` ## Extension injection points @@ -286,17 +286,17 @@ if not specified in `self::$defaults`, but before extensions have been called: ```php - function __construct() { - $self = $this; + function __construct() { + $self = $this; - $this->beforeExtending('populateDefaults', function() use ($self) { - if(empty($self->MyField)) { - $self->MyField = 'Value we want as a default if not specified in $defaults, but set before extensions'; - } - }); + $this->beforeExtending('populateDefaults', function() use ($self) { + if(empty($self->MyField)) { + $self->MyField = 'Value we want as a default if not specified in $defaults, but set before extensions'; + } + }); - parent::__construct(); - } + parent::__construct(); + } ``` Example 2: User code can intervene in the process of extending cms fields. @@ -307,18 +307,18 @@ This method is preferred to disabling, enabling, and calling field extensions ma ```php - public function getCMSFields() - { + public function getCMSFields() + { - $this->beforeUpdateCMSFields(function($fields) { - // Include field which must be present when updateCMSFields is called on extensions - $fields->addFieldToTab("Root.Main", new TextField('Detail', 'Details', null, 255)); - }); + $this->beforeUpdateCMSFields(function($fields) { + // Include field which must be present when updateCMSFields is called on extensions + $fields->addFieldToTab("Root.Main", new TextField('Detail', 'Details', null, 255)); + }); - $fields = parent::getCMSFields(); - // ... additional fields here - return $fields; - } + $fields = parent::getCMSFields(); + // ... additional fields here + return $fields; + } ``` ## Related Documentaion diff --git a/docs/en/02_Developer_Guides/05_Extending/04_Shortcodes.md b/docs/en/02_Developer_Guides/05_Extending/04_Shortcodes.md index 1335f788f..c235133c5 100644 --- a/docs/en/02_Developer_Guides/05_Extending/04_Shortcodes.md +++ b/docs/en/02_Developer_Guides/05_Extending/04_Shortcodes.md @@ -12,22 +12,22 @@ in their WYSIWYG editor. Shortcodes are a semi-technical solution for this. A go viewer or a Google Map at a certain location. ```php - $text = "

      My Map

      [map]" - - // Will output - //

      My Map

      + $text = "

      My Map

      [map]" + + // Will output + //

      My Map

      ``` Here's some syntax variations: ```php - [my_shortcode] - # - [my_shortcode /] - # - [my_shortcode,myparameter="value"] - # - [my_shortcode,myparameter="value"]Enclosed Content[/my_shortcode] + [my_shortcode] + # + [my_shortcode /] + # + [my_shortcode,myparameter="value"] + # + [my_shortcode,myparameter="value"]Enclosed Content[/my_shortcode] ``` Shortcodes are automatically parsed on any database field which is declared as [HTMLValue](api:SilverStripe\View\Parsers\HTMLValue) or [DBHTMLText](api:SilverStripe\ORM\FieldType\DBHTMLText), @@ -38,8 +38,8 @@ Other fields can be manually parsed with shortcodes through the `parse` method. ```php - $text = "My awesome [my_shortcode] is here."; - ShortcodeParser::get_active()->parse($text); + $text = "My awesome [my_shortcode] is here."; + ShortcodeParser::get_active()->parse($text); ``` ## Defining Custom Shortcodes @@ -50,20 +50,20 @@ First we need to define a callback for the shortcode. ```php - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { - - private static $casting = [ - 'MyShortCodeMethod' => 'HTMLText' - ]; + class Page extends SiteTree + { + + private static $casting = [ + 'MyShortCodeMethod' => 'HTMLText' + ]; - public static function MyShortCodeMethod($arguments, $content = null, $parser = null, $tagName) - { - return "" . $tagName . " " . $content . "; " . count($arguments) . " arguments."; - } - } + public static function MyShortCodeMethod($arguments, $content = null, $parser = null, $tagName) + { + return "" . $tagName . " " . $content . "; " . count($arguments) . " arguments."; + } + } ``` @@ -85,9 +85,9 @@ To register a shortcode you call the following. ```php - // ShortcodeParser::get('default')->register($shortcode, $callback); + // ShortcodeParser::get('default')->register($shortcode, $callback); - ShortcodeParser::get('default')->register('my_shortcode', ['Page', 'MyShortCodeMethod']); + ShortcodeParser::get('default')->register('my_shortcode', ['Page', 'MyShortCodeMethod']); ``` @@ -103,14 +103,14 @@ shortcode, which takes an `id` parameter. ```php - + ``` Links to internal `File` database records work exactly the same, but with the `[file_link]` shortcode. ```php - + ``` ### Images @@ -148,30 +148,30 @@ The first is called "element scope" use, the second "attribute scope" You may not use shortcodes in any other location. Specifically, you can not use shortcodes to generate attributes or change the name of a tag. These usages are forbidden: ```ss - <[paragraph]>Some test + <[paragraph]>Some test - link + link ``` You may need to escape text inside attributes `>` becomes `>`, You can include HTML tags inside a shortcode tag, but you need to be careful of nesting to ensure you don't break the output. ```ss - -
      - [shortcode] -

      Caption

      - [/shortcode] -
      + +
      + [shortcode] +

      Caption

      + [/shortcode] +
      - + -
      - [shortcode] -
      -

      - [/shortcode] -

      +
      + [shortcode] +
      +

      + [/shortcode] +

      ``` ### Location @@ -179,51 +179,51 @@ you need to be careful of nesting to ensure you don't break the output. Element scoped shortcodes have a special ability to move the location they are inserted at to comply with HTML lexical rules. Take for example this basic paragraph tag: ```ss -

      Head [figure,src="assets/a.jpg",caption="caption"] Tail

      +

      Head [figure,src="assets/a.jpg",caption="caption"] Tail

      ``` When converted naively would become: ```ss -

      Head

      caption
      Tail

      +

      Head

      caption
      Tail

      ``` However this is not valid HTML - P elements can not contain other block level elements. To fix this you can specify a "location" attribute on a shortcode. When the location attribute is "left" or "right" the inserted content will be moved to immediately before the block tag. The result is this: ```ss -
      caption

      Head Tail

      +
      caption

      Head Tail

      ``` When the location attribute is "leftAlone" or "center" then the DOM is split around the element. The result is this: ```ss -

      Head

      caption

      Tail

      +

      Head

      caption

      Tail

      ``` ### Parameter values Here is a summary of the callback parameter values based on some example shortcodes. ```php - public function MyCustomShortCode($arguments, $content = null, $parser = null, $tagName) - { - // .. - } + public function MyCustomShortCode($arguments, $content = null, $parser = null, $tagName) + { + // .. + } - [my_shortcode] - $attributes => []; - $content => null; - $parser => ShortcodeParser instance, - $tagName => 'my_shortcode') + [my_shortcode] + $attributes => []; + $content => null; + $parser => ShortcodeParser instance, + $tagName => 'my_shortcode') - [my_shortcode,attribute="foo",other="bar"] + [my_shortcode,attribute="foo",other="bar"] - $attributes => ['attribute' => 'foo', 'other' => 'bar'] - $enclosedContent => null - $parser => ShortcodeParser instance - $tagName => 'my_shortcode' + $attributes => ['attribute' => 'foo', 'other' => 'bar'] + $enclosedContent => null + $parser => ShortcodeParser instance + $tagName => 'my_shortcode' - [my_shortcode,attribute="foo"]content[/my_shortcode] + [my_shortcode,attribute="foo"]content[/my_shortcode] - $attributes => ['attribute' => 'foo'] - $enclosedContent => 'content' - $parser => ShortcodeParser instance - $tagName => 'my_shortcode' + $attributes => ['attribute' => 'foo'] + $enclosedContent => 'content' + $parser => ShortcodeParser instance + $tagName => 'my_shortcode' ``` diff --git a/docs/en/02_Developer_Guides/05_Extending/05_Injector.md b/docs/en/02_Developer_Guides/05_Extending/05_Injector.md index 4a0639914..8dbca173b 100644 --- a/docs/en/02_Developer_Guides/05_Extending/05_Injector.md +++ b/docs/en/02_Developer_Guides/05_Extending/05_Injector.md @@ -20,7 +20,7 @@ The following sums up the simplest usage of the `Injector` it creates a new obje ```php - $object = Injector::inst()->create('MyClassName'); + $object = Injector::inst()->create('MyClassName'); ``` The benefit of constructing objects through this syntax is `ClassName` can be swapped out using the @@ -30,21 +30,21 @@ The benefit of constructing objects through this syntax is `ClassName` can be sw ```yml - Injector: - MyClassName: - class: MyBetterClassName + Injector: + MyClassName: + class: MyBetterClassName ``` Repeated calls to `create()` create a new object each time. ```php - $object = Injector::inst()->create('MyClassName'); - $object2 = Injector::inst()->create('MyClassName'); + $object = Injector::inst()->create('MyClassName'); + $object2 = Injector::inst()->create('MyClassName'); - echo $object !== $object2; + echo $object !== $object2; - // returns true; + // returns true; ``` ## Singleton Pattern @@ -54,13 +54,13 @@ object instance as the first call. ```php - // sets up MyClassName as a singleton - $object = Injector::inst()->get('MyClassName'); - $object2 = Injector::inst()->get('MyClassName'); + // sets up MyClassName as a singleton + $object = Injector::inst()->get('MyClassName'); + $object2 = Injector::inst()->get('MyClassName'); - echo ($object === $object2); + echo ($object === $object2); - // returns true; + // returns true; ``` ## Dependencies @@ -69,23 +69,23 @@ The `Injector` API can be used to define the types of `$dependencies` that an ob ```php - use SilverStripe\Control\Controller; + use SilverStripe\Control\Controller; - class MyController extends Controller - { - - // both of these properties will be automatically - // set by the injector on object creation - public $permissions; - public $textProperty; - - // we declare the types for each of the properties on the object. Anything we pass in via the Injector API must - // match these data types. - static $dependencies = [ - 'textProperty' => 'a string value', - 'permissions' => '%$PermissionService', - ]; - } + class MyController extends Controller + { + + // both of these properties will be automatically + // set by the injector on object creation + public $permissions; + public $textProperty; + + // we declare the types for each of the properties on the object. Anything we pass in via the Injector API must + // match these data types. + static $dependencies = [ + 'textProperty' => 'a string value', + 'permissions' => '%$PermissionService', + ]; + } ``` @@ -93,13 +93,13 @@ When creating a new instance of `MyController` the dependencies on that class wi ```php - $object = Injector::inst()->get('MyController'); - - echo ($object->permissions instanceof PermissionService); - // returns true; + $object = Injector::inst()->get('MyController'); + + echo ($object->permissions instanceof PermissionService); + // returns true; - echo (is_string($object->textProperty)); - // returns true; + echo (is_string($object->textProperty)); + // returns true; ``` The [Configuration YAML](../configuration) does the hard work of configuring those `$dependencies` for us. @@ -108,25 +108,25 @@ The [Configuration YAML](../configuration) does the hard work of configuring tho ```yml - Injector: - PermissionService: - class: MyCustomPermissionService - MyController - properties: - textProperty: 'My Text Value' + Injector: + PermissionService: + class: MyCustomPermissionService + MyController + properties: + textProperty: 'My Text Value' ``` Now the dependencies will be replaced with our configuration. ```php - $object = Injector::inst()->get('MyController'); - - echo ($object->permissions instanceof MyCustomPermissionService); - // returns true; + $object = Injector::inst()->get('MyController'); + + echo ($object->permissions instanceof MyCustomPermissionService); + // returns true; - echo ($object->textProperty == 'My Text Value'); - // returns true; + echo ($object->textProperty == 'My Text Value'); + // returns true; ``` As well as properties, method calls can also be specified: @@ -134,11 +134,11 @@ As well as properties, method calls can also be specified: ```yml - Injector: - Logger: - class: Monolog\Logger - calls: - - [ pushHandler, [ %$DefaultHandler ] ] + Injector: + Logger: + class: Monolog\Logger + calls: + - [ pushHandler, [ %$DefaultHandler ] ] ``` ## Using constants as variables @@ -169,26 +169,26 @@ An example using the `MyFactory` service to create instances of the `MyService` ```yml - Injector: - MyService: - factory: MyFactory + Injector: + MyService: + factory: MyFactory ``` **mysite/code/MyFactory.php** ```php - class MyFactory implements SilverStripe\Core\Injector\Factory - { + class MyFactory implements SilverStripe\Core\Injector\Factory + { - public function create($service, array $params = []) - { - return new MyServiceImplementation(); - } - } + public function create($service, array $params = []) + { + return new MyServiceImplementation(); + } + } - // Will use MyFactoryImplementation::create() to create the service instance. - $instance = Injector::inst()->get('MyService'); + // Will use MyFactoryImplementation::create() to create the service instance. + $instance = Injector::inst()->get('MyService'); ``` @@ -198,10 +198,10 @@ To override the `$dependency` declaration for a class, define the following conf **mysite/_config/app.yml** ```yml - MyController: - dependencies: - textProperty: a string value - permissions: %$PermissionService + MyController: + dependencies: + textProperty: a string value + permissions: %$PermissionService ``` ## Managed objects @@ -215,26 +215,26 @@ Assuming a class structure such as ```php - class RestrictivePermissionService - { - private $database; + class RestrictivePermissionService + { + private $database; - public function setDatabase($d) - { - $this->database = $d; - } - } - class MySQLDatabase - { - private $username; - private $password; - - public function __construct($username, $password) - { - $this->username = $username; - $this->password = $password; - } - } + public function setDatabase($d) + { + $this->database = $d; + } + } + class MySQLDatabase + { + private $username; + private $password; + + public function __construct($username, $password) + { + $this->username = $username; + $this->password = $password; + } + } ``` And the following configuration.. @@ -242,28 +242,28 @@ And the following configuration.. ```yml - name: MyController - --- - MyController: - dependencies: - permissions: %$PermissionService - Injector: - PermissionService: - class: RestrictivePermissionService - properties: - database: %$MySQLDatabase - MySQLDatabase - constructor: - 0: 'dbusername' - 1: 'dbpassword' + name: MyController + --- + MyController: + dependencies: + permissions: %$PermissionService + Injector: + PermissionService: + class: RestrictivePermissionService + properties: + database: %$MySQLDatabase + MySQLDatabase + constructor: + 0: 'dbusername' + 1: 'dbpassword' ``` Calling.. ```php - // sets up ClassName as a singleton - $controller = Injector::inst()->get('MyController'); + // sets up ClassName as a singleton + $controller = Injector::inst()->get('MyController'); ``` Would setup the following @@ -283,12 +283,12 @@ Thus if you want an object to have the injected dependencies of a service of ano assign a reference to that service. ```yaml - Injector: - JSONServiceDefinition: - class: JSONServiceImplementor - properties: - Serialiser: JSONSerialiser - GZIPJSONProvider: %$JSONServiceDefinition + Injector: + JSONServiceDefinition: + class: JSONServiceImplementor + properties: + Serialiser: JSONSerialiser + GZIPJSONProvider: %$JSONServiceDefinition ``` `Injector::inst()->get('GZIPJSONProvider')` will then be an instance of `JSONServiceImplementor` with the injected @@ -300,11 +300,11 @@ If class is not specified, then the class will be inherited from the outer servi For example with this config: ```yml - Injector: - Connector: - properties: - AsString: true - ServiceConnector: %$Connector + Injector: + Connector: + properties: + AsString: true + ServiceConnector: %$Connector ``` Both `Connector` and `ServiceConnector` will have the `AsString` property set to true, but the resulting @@ -319,18 +319,18 @@ This is useful when writing test cases, as certain services may be necessary to ```php - // Setup default service - Injector::inst()->registerService(new LiveService(), 'ServiceName'); + // Setup default service + Injector::inst()->registerService(new LiveService(), 'ServiceName'); - // Test substitute service temporarily - Injector::nest(); + // Test substitute service temporarily + Injector::nest(); - Injector::inst()->registerService(new TestingService(), 'ServiceName'); - $service = Injector::inst()->get('ServiceName'); - // ... do something with $service + Injector::inst()->registerService(new TestingService(), 'ServiceName'); + $service = Injector::inst()->get('ServiceName'); + // ... do something with $service - // revert changes - Injector::unnest(); + // revert changes + Injector::unnest(); ``` ## API Documentation diff --git a/docs/en/02_Developer_Guides/05_Extending/06_Aspects.md b/docs/en/02_Developer_Guides/05_Extending/06_Aspects.md index d413d68d8..e84d41eae 100644 --- a/docs/en/02_Developer_Guides/05_Extending/06_Aspects.md +++ b/docs/en/02_Developer_Guides/05_Extending/06_Aspects.md @@ -47,31 +47,31 @@ used. ```php - class MySQLWriteDbAspect implements BeforeCallAspect - { + class MySQLWriteDbAspect implements BeforeCallAspect + { - /** - * @var MySQLDatabase - */ - public $writeDb; - - public $writeQueries = [ - 'insert','update','delete','replace' - ]; + /** + * @var MySQLDatabase + */ + public $writeDb; + + public $writeQueries = [ + 'insert','update','delete','replace' + ]; - public function beforeCall($proxied, $method, $args, &$alternateReturn) - { - if (isset($args[0])) { - $sql = $args[0]; - $code = isset($args[1]) ? $args[1] : E_USER_ERROR; + public function beforeCall($proxied, $method, $args, &$alternateReturn) + { + if (isset($args[0])) { + $sql = $args[0]; + $code = isset($args[1]) ? $args[1] : E_USER_ERROR; - if (in_array(strtolower(substr($sql,0,strpos($sql,' '))), $this->writeQueries)) { - $alternateReturn = $this->writeDb->query($sql, $code); - return false; - } - } - } - } + if (in_array(strtolower(substr($sql,0,strpos($sql,' '))), $this->writeQueries)) { + $alternateReturn = $this->writeDb->query($sql, $code); + return false; + } + } + } + } ``` @@ -83,14 +83,14 @@ object that's made use of above. ```yml - WriteMySQLDatabase: - class: MySQLDatabase - constructor: - - type: MySQLDatabase - server: write.hostname.db - username: user - password: pass - database: write_database + WriteMySQLDatabase: + class: MySQLDatabase + constructor: + - type: MySQLDatabase + server: write.hostname.db + username: user + password: pass + database: write_database ``` This means that whenever something asks the [Injector](api:SilverStripe\Core\Injector\Injector) for the `WriteMySQLDatabase` object, it'll receive an object @@ -103,9 +103,9 @@ Next, this should be bound into an instance of the `Aspect` class ```yml - MySQLWriteDbAspect: - properties: - writeDb: %$WriteMySQLDatabase + MySQLWriteDbAspect: + properties: + writeDb: %$WriteMySQLDatabase ``` Next, we need to define the database connection that will be used for all non-write queries @@ -113,14 +113,14 @@ Next, we need to define the database connection that will be used for all non-wr **mysite/_config/app.yml** ```yml - ReadMySQLDatabase: - class: MySQLDatabase - constructor: - - type: MySQLDatabase - server: slavecluster.hostname.db - username: user - password: pass - database: read_database + ReadMySQLDatabase: + class: MySQLDatabase + constructor: + - type: MySQLDatabase + server: slavecluster.hostname.db + username: user + password: pass + database: read_database ``` The final piece that ties everything together is the [AopProxyService](api:SilverStripe\Core\Injector\AopProxyService) instance that will be used as the replacement @@ -129,13 +129,13 @@ object when the framework creates the database connection. **mysite/_config/app.yml** ```yml - MySQLDatabase: - class: AopProxyService - properties: - proxied: %$ReadMySQLDatabase - beforeCall: - query: - - %$MySQLWriteDbAspect + MySQLDatabase: + class: AopProxyService + properties: + proxied: %$ReadMySQLDatabase + beforeCall: + query: + - %$MySQLWriteDbAspect ``` The two important parts here are in the `properties` declared for the object. @@ -149,33 +149,33 @@ Overall configuration for this would look as follows **mysite/_config/app.yml** ```yml - Injector: - ReadMySQLDatabase: - class: MySQLDatabase - constructor: - - type: MySQLDatabase - server: slavecluster.hostname.db - username: user - password: pass - database: read_database - MySQLWriteDbAspect: - properties: - writeDb: %$WriteMySQLDatabase - WriteMySQLDatabase: - class: MySQLDatabase - constructor: - - type: MySQLDatabase - server: write.hostname.db - username: user - password: pass - database: write_database - MySQLDatabase: - class: AopProxyService - properties: - proxied: %$ReadMySQLDatabase - beforeCall: - query: - - %$MySQLWriteDbAspect + Injector: + ReadMySQLDatabase: + class: MySQLDatabase + constructor: + - type: MySQLDatabase + server: slavecluster.hostname.db + username: user + password: pass + database: read_database + MySQLWriteDbAspect: + properties: + writeDb: %$WriteMySQLDatabase + WriteMySQLDatabase: + class: MySQLDatabase + constructor: + - type: MySQLDatabase + server: write.hostname.db + username: user + password: pass + database: write_database + MySQLDatabase: + class: AopProxyService + properties: + proxied: %$ReadMySQLDatabase + beforeCall: + query: + - %$MySQLWriteDbAspect ``` ## Changing what a method returns @@ -184,9 +184,9 @@ One major feature of an `Aspect` is the ability to modify what is returned from As seen in the above example, the `beforeCall` method modifies the `&$alternateReturn` variable, and returns `false` after doing so. ```php - $alternateReturn = $this->writeDb->query($sql, $code); + $alternateReturn = $this->writeDb->query($sql, $code); - return false; + return false; ``` By returning `false` from the `beforeCall()` method, the wrapping proxy class will_not_ call any additional `beforeCall` diff --git a/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md b/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md index cc0f0c431..e37fb4c5e 100644 --- a/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md +++ b/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md @@ -19,31 +19,31 @@ this: ```js - { - "name": "your-vendor-name/module-name", - "description": "One-liner describing your module", - "type": "silverstripe-module", - "homepage": "http://github.com/your-vendor-name/module-name", - "keywords": ["silverstripe", "some-tag", "some-other-tag"], - "license": "BSD-3-Clause", - "authors": [ - {"name": "Your Name","email": "your@email.com"} - ], - "support": { - "issues": "http://github.com/your-vendor-name/module-name/issues" - }, - "require": { - "silverstripe/cms": "~3.1", - "silverstripe/framework": "~3.1" - }, - "extra": { - "installer-name": "module-name", - "screenshots": [ - "relative/path/screenshot1.png", - "http://myhost.com/screenshot2.png" - ] - } - } + { + "name": "your-vendor-name/module-name", + "description": "One-liner describing your module", + "type": "silverstripe-module", + "homepage": "http://github.com/your-vendor-name/module-name", + "keywords": ["silverstripe", "some-tag", "some-other-tag"], + "license": "BSD-3-Clause", + "authors": [ + {"name": "Your Name","email": "your@email.com"} + ], + "support": { + "issues": "http://github.com/your-vendor-name/module-name/issues" + }, + "require": { + "silverstripe/cms": "~3.1", + "silverstripe/framework": "~3.1" + }, + "extra": { + "installer-name": "module-name", + "screenshots": [ + "relative/path/screenshot1.png", + "http://myhost.com/screenshot2.png" + ] + } + } ``` Once your module is published online with a service like Github.com or Bitbucket.com, submit the repository to diff --git a/docs/en/02_Developer_Guides/05_Extending/How_Tos/02_Create_a_Google_Maps_Shortcode.md b/docs/en/02_Developer_Guides/05_Extending/How_Tos/02_Create_a_Google_Maps_Shortcode.md index e97c71526..5d22005c5 100644 --- a/docs/en/02_Developer_Guides/05_Extending/How_Tos/02_Create_a_Google_Maps_Shortcode.md +++ b/docs/en/02_Developer_Guides/05_Extending/How_Tos/02_Create_a_Google_Maps_Shortcode.md @@ -7,7 +7,7 @@ address. We want our CMS authors to be able to embed the map using the following ```php - [googlemap,width=500,height=300]97-99 Courtenay Place, Wellington, New Zealand[/googlemap] + [googlemap,width=500,height=300]97-99 Courtenay Place, Wellington, New Zealand[/googlemap] ``` So we've got the address as "content" of our new `googlemap` shortcode tags, plus some `width` and `height` arguments. @@ -15,22 +15,22 @@ We'll add defaults to those in our shortcode parser so they're optional. **mysite/_config.php** -```php - ShortcodeParser::get('default')->register('googlemap', function($arguments, $address, $parser, $shortcode) { - $iframeUrl = sprintf( - 'http://maps.google.com/maps?q=%s&hnear=%s&ie=UTF8&hq=&t=m&z=14&output=embed', - urlencode($address), - urlencode($address) - ); +```php + ShortcodeParser::get('default')->register('googlemap', function($arguments, $address, $parser, $shortcode) { + $iframeUrl = sprintf( + 'http://maps.google.com/maps?q=%s&hnear=%s&ie=UTF8&hq=&t=m&z=14&output=embed', + urlencode($address), + urlencode($address) + ); - $width = (isset($arguments['width']) && $arguments['width']) ? $arguments['width'] : 400; - $height = (isset($arguments['height']) && $arguments['height']) ? $arguments['height'] : 300; + $width = (isset($arguments['width']) && $arguments['width']) ? $arguments['width'] : 400; + $height = (isset($arguments['height']) && $arguments['height']) ? $arguments['height'] : 300; - return sprintf( - '', - $width, - $height, - $iframeUrl - ); - }); + return sprintf( + '', + $width, + $height, + $iframeUrl + ); + }); ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md b/docs/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md index 7acc71389..b415cbdb3 100644 --- a/docs/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md +++ b/docs/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md @@ -11,55 +11,55 @@ explicitly logging in or by invoking the "remember me" functionality. ```php - use SilverStripe\Forms\ReadonlyField; - use SilverStripe\Security\Security; - use SilverStripe\ORM\DB; - use SilverStripe\ORM\DataExtension; + use SilverStripe\Forms\ReadonlyField; + use SilverStripe\Security\Security; + use SilverStripe\ORM\DB; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { - private static $db = [ - 'LastVisited' => 'Datetime', - 'NumVisit' => 'Int', - ]; + class MyMemberExtension extends DataExtension + { + private static $db = [ + 'LastVisited' => 'Datetime', + 'NumVisit' => 'Int', + ]; - public function memberLoggedIn() - { - $this->logVisit(); - } + public function memberLoggedIn() + { + $this->logVisit(); + } - public function memberAutoLoggedIn() - { - $this->logVisit(); - } + public function memberAutoLoggedIn() + { + $this->logVisit(); + } - public function updateCMSFields(FieldList $fields) - { - $fields->addFieldsToTab('Root.Main', [ - ReadonlyField::create('LastVisited', 'Last visited'), - ReadonlyField::create('NumVisit', 'Number of visits') - ]); - } + public function updateCMSFields(FieldList $fields) + { + $fields->addFieldsToTab('Root.Main', [ + ReadonlyField::create('LastVisited', 'Last visited'), + ReadonlyField::create('NumVisit', 'Number of visits') + ]); + } - protected function logVisit() - { - if(!Security::database_is_ready()) return; - - DB::query(sprintf( - 'UPDATE "Member" SET "LastVisited" = %s, "NumVisit" = "NumVisit" + 1 WHERE "ID" = %d', - DB::get_conn()->now(), - $this->owner->ID - )); - } - } + protected function logVisit() + { + if(!Security::database_is_ready()) return; + + DB::query(sprintf( + 'UPDATE "Member" SET "LastVisited" = %s, "NumVisit" = "NumVisit" + 1 WHERE "ID" = %d', + DB::get_conn()->now(), + $this->owner->ID + )); + } + } ``` Now you just need to apply this extension through your config: ```yml - Member: - extensions: - - MyMemberExtension + Member: + extensions: + - MyMemberExtension ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md b/docs/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md index 9253ac79c..003c0dae8 100644 --- a/docs/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md +++ b/docs/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md @@ -10,33 +10,33 @@ to ensure that it works as it should. A simple example would be to test the resu ```php - + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree + class Page extends SiteTree { - public static function MyMethod() + public static function MyMethod() { - return (1 + 1); - } - } + return (1 + 1); + } + } ``` **mysite/tests/PageTest.php** ```php - + use Page; use SilverStripe\Dev\SapphireTest; - class PageTest extends SapphireTest + class PageTest extends SapphireTest { - public function testMyMethod() + public function testMyMethod() { - $this->assertEquals(2, Page::MyMethod()); - } - } + $this->assertEquals(2, Page::MyMethod()); + } + } ```
      @@ -89,23 +89,23 @@ needs. ```xml - - - mysite/tests - cms/tests - framework/tests - - - - - - - - - sanitychecks - - - + + + mysite/tests + cms/tests + framework/tests + + + + + + + + + sanitychecks + + + ``` ### setUp() and tearDown() @@ -116,37 +116,37 @@ end of each test. ```php - + use SilverStripe\Core\Config\Config; use SilverStripe\Dev\SapphireTest; - class PageTest extends SapphireTest + class PageTest extends SapphireTest { - function setUp() + function setUp() { - parent::setUp(); + parent::setUp(); - // create 100 pages - for ($i = 0; $i < 100; $i++) { - $page = new Page(['Title' => "Page $i"]); - $page->write(); - $page->copyVersionToStage(Versioned::DRAFT, Versioned::LIVE); - } + // create 100 pages + for ($i = 0; $i < 100; $i++) { + $page = new Page(['Title' => "Page $i"]); + $page->write(); + $page->copyVersionToStage(Versioned::DRAFT, Versioned::LIVE); + } - // set custom configuration for the test. - Config::inst()->update('Foo', 'bar', 'Hello!'); - } + // set custom configuration for the test. + Config::inst()->update('Foo', 'bar', 'Hello!'); + } - public function testMyMethod() + public function testMyMethod() { - // .. - } + // .. + } - public function testMySecondMethod() + public function testMySecondMethod() { - // .. - } - } + // .. + } + } ``` @@ -156,25 +156,25 @@ takes place. ```php - + use SilverStripe\Dev\SapphireTest; - - class PageTest extends SapphireTest + + class PageTest extends SapphireTest { - public static function setUpBeforeClass() + public static function setUpBeforeClass() { - parent::setUpBeforeClass(); + parent::setUpBeforeClass(); - // .. - } + // .. + } - public static function tearDownAfterClass() + public static function tearDownAfterClass() { - parent::tearDownAfterClass(); + parent::tearDownAfterClass(); - // .. - } - } + // .. + } + } ``` ### Config and Injector Nesting @@ -189,23 +189,23 @@ It's important to remember that the `parent::setUp();` functions will need to be ```php - public static function setUpBeforeClass() + public static function setUpBeforeClass() { - parent::setUpBeforeClass(); - //this will remain for the whole suite and be removed for any other tests - Config::inst()->update('ClassName', 'var_name', 'var_value'); - } - - public function testFeatureDoesAsExpected() + parent::setUpBeforeClass(); + //this will remain for the whole suite and be removed for any other tests + Config::inst()->update('ClassName', 'var_name', 'var_value'); + } + + public function testFeatureDoesAsExpected() { - //this will be reset to 'var_value' at the end of this test function - Config::inst()->update('ClassName', 'var_name', 'new_var_value'); - } - - public function testAnotherFeatureDoesAsExpected() + //this will be reset to 'var_value' at the end of this test function + Config::inst()->update('ClassName', 'var_name', 'new_var_value'); + } + + public function testAnotherFeatureDoesAsExpected() { - Config::inst()->get('ClassName', 'var_name'); // this will be 'var_value' - } + Config::inst()->get('ClassName', 'var_name'); // this will be 'var_value' + } ``` ## Related Documentation diff --git a/docs/en/02_Developer_Guides/06_Testing/01_Functional_Testing.md b/docs/en/02_Developer_Guides/06_Testing/01_Functional_Testing.md index c4377819b..e3a3597ec 100644 --- a/docs/en/02_Developer_Guides/06_Testing/01_Functional_Testing.md +++ b/docs/en/02_Developer_Guides/06_Testing/01_Functional_Testing.md @@ -9,7 +9,7 @@ creating [HTTPRequest](api:SilverStripe\Control\HTTPRequest), receiving [HTTPRes ## Get ```php - $page = $this->get($url); + $page = $this->get($url); ``` Performs a GET request on $url and retrieves the [HTTPResponse](api:SilverStripe\Control\HTTPResponse). This also changes the current page to the value @@ -17,7 +17,7 @@ of the response. ## Post ```php - $page = $this->post($url); + $page = $this->post($url); ``` Performs a POST request on $url and retrieves the [HTTPResponse](api:SilverStripe\Control\HTTPResponse). This also changes the current page to the value @@ -27,7 +27,7 @@ of the response. ```php - $submit = $this->submitForm($formID, $button = null, $data = []); + $submit = $this->submitForm($formID, $button = null, $data = []); ``` @@ -37,14 +37,14 @@ Submits the given form (`#ContactForm`) on the current page and returns the [HTT ```php - $this->logInAs($member); + $this->logInAs($member); ``` Logs a given user in, sets the current session. To log all users out pass `null` to the method. ```php - $this->logInAs(null); + $this->logInAs(null); ``` ## Assertions @@ -55,9 +55,9 @@ The `FunctionalTest` class also provides additional asserts to validate your tes ```php - $this->assertPartialMatchBySelector('p.good',[ - 'Test save was successful' - ]); + $this->assertPartialMatchBySelector('p.good',[ + 'Test save was successful' + ]); ``` @@ -70,9 +70,9 @@ assertion fails if one of the expectedMatches fails to appear. ```php - $this->assertExactMatchBySelector("#MyForm_ID p.error", [ - "That email address is invalid." - ]); + $this->assertExactMatchBySelector("#MyForm_ID p.error", [ + "That email address is invalid." + ]); ``` @@ -82,9 +82,9 @@ assertion fails if one of the expectedMatches fails to appear. ### assertPartialHTMLMatchBySelector ```php - $this->assertPartialHTMLMatchBySelector("#MyForm_ID p.error", [ - "That email address is invalid." - ]); + $this->assertPartialHTMLMatchBySelector("#MyForm_ID p.error", [ + "That email address is invalid." + ]); ``` @@ -98,9 +98,9 @@ assertion fails if one of the expectedMatches fails to appear. ### assertExactHTMLMatchBySelector ```php - $this->assertExactHTMLMatchBySelector("#MyForm_ID p.error", [ - "That email address is invalid." - ]); + $this->assertExactHTMLMatchBySelector("#MyForm_ID p.error", [ + "That email address is invalid." + ]); ``` diff --git a/docs/en/02_Developer_Guides/06_Testing/04_Fixtures.md b/docs/en/02_Developer_Guides/06_Testing/04_Fixtures.md index 9715dde6a..1a4853bf0 100644 --- a/docs/en/02_Developer_Guides/06_Testing/04_Fixtures.md +++ b/docs/en/02_Developer_Guides/06_Testing/04_Fixtures.md @@ -16,12 +16,12 @@ To include your fixture file in your tests, you should define it as your `$fixtu ```php - class MyNewTest extends SapphireTest - { - - protected static $fixture_file = 'fixtures.yml'; - - } + class MyNewTest extends SapphireTest + { + + protected static $fixture_file = 'fixtures.yml'; + + } ``` You can also use an array of fixture files, if you want to use parts of multiple other tests: @@ -31,15 +31,15 @@ You can also use an array of fixture files, if you want to use parts of multiple ```php - class MyNewTest extends SapphireTest - { - - protected static $fixture_file = [ - 'fixtures.yml', - 'otherfixtures.yml' - ]; - - } + class MyNewTest extends SapphireTest + { + + protected static $fixture_file = [ + 'fixtures.yml', + 'otherfixtures.yml' + ]; + + } ``` @@ -50,31 +50,31 @@ ideal for fixture generation. Say we have the following two DataObjects: ```php - + use SilverStripe\ORM\DataObject; - class Player extends DataObject + class Player extends DataObject { - private static $db = [ - 'Name' => 'Varchar(255)' - ]; + private static $db = [ + 'Name' => 'Varchar(255)' + ]; - private static $has_one = [ - 'Team' => 'Team' - ]; - } + private static $has_one = [ + 'Team' => 'Team' + ]; + } - class Team extends DataObject + class Team extends DataObject { - private static $db = [ - 'Name' => 'Varchar(255)', - 'Origin' => 'Varchar(255)' - ]; + private static $db = [ + 'Name' => 'Varchar(255)', + 'Origin' => 'Varchar(255)' + ]; - private static $has_many = [ - 'Players' => 'Player' - ]; - } + private static $has_many = [ + 'Players' => 'Player' + ]; + } ``` @@ -85,23 +85,23 @@ We can represent multiple instances of them in `YAML` as follows: ```yml - Team: - hurricanes: - Name: The Hurricanes - Origin: Wellington - crusaders: - Name: The Crusaders - Origin: Canterbury - Player: - john: - Name: John - Team: =>Team.hurricanes - joe: - Name: Joe - Team: =>Team.crusaders - jack: - Name: Jack - Team: =>Team.crusaders + Team: + hurricanes: + Name: The Hurricanes + Origin: Wellington + crusaders: + Name: The Crusaders + Origin: Canterbury + Player: + john: + Name: John + Team: =>Team.hurricanes + joe: + Name: Joe + Team: =>Team.crusaders + jack: + Name: Jack + Team: =>Team.crusaders ``` This `YAML` is broken up into three levels, signified by the indentation of each line. In the first level of @@ -112,7 +112,7 @@ represents a new object and can be referenced in the PHP using `objFromFixture` ```php - $player = $this->objFromFixture('Player', 'jack'); + $player = $this->objFromFixture('Player', 'jack'); ``` The third and final level represents each individual object's fields. @@ -144,22 +144,22 @@ We can also declare the relationships conversely. Another way we could write the ```yml - Player: - john: - Name: John - joe: - Name: Joe - jack: - Name: Jack - Team: - hurricanes: - Name: Hurricanes - Origin: Wellington - Players: =>Player.john - crusaders: - Name: Crusaders - Origin: Canterbury - Players: =>Player.joe,=>Player.jack + Player: + john: + Name: John + joe: + Name: Joe + jack: + Name: Jack + Team: + hurricanes: + Name: Hurricanes + Origin: Wellington + Players: =>Player.john + crusaders: + Name: Crusaders + Origin: Canterbury + Players: =>Player.joe,=>Player.jack ``` The database is populated by instantiating `DataObject` objects and setting the fields declared in the `YAML`, then @@ -168,14 +168,14 @@ writing: ```php - $team = new Team([ - 'Name' => 'Hurricanes', - 'Origin' => 'Wellington' - ]); + $team = new Team([ + 'Name' => 'Hurricanes', + 'Origin' => 'Wellington' + ]); - $team->write(); + $team->write(); - $team->Players()->add($john); + $team->Players()->add($john); ``` @@ -215,33 +215,33 @@ declare the role each player has in the team. ```php use SilverStripe\ORM\DataObject; - class Player extends DataObject + class Player extends DataObject { - private static $db = [ - 'Name' => 'Varchar(255)' - ]; + private static $db = [ + 'Name' => 'Varchar(255)' + ]; - private static $belongs_many_many = [ - 'Teams' => 'Team' - ]; - } + private static $belongs_many_many = [ + 'Teams' => 'Team' + ]; + } - class Team extends DataObject + class Team extends DataObject { - private static $db = [ - 'Name' => 'Varchar(255)' - ]; + private static $db = [ + 'Name' => 'Varchar(255)' + ]; - private static $many_many = [ - 'Players' => 'Player' - ]; + private static $many_many = [ + 'Players' => 'Player' + ]; - private static $many_many_extraFields = [ - 'Players' => [ - 'Role' => "Varchar" - ] - ]; - } + private static $many_many_extraFields = [ + 'Players' => [ + 'Role' => "Varchar" + ] + ]; + } ``` @@ -250,27 +250,27 @@ To provide the value for the `many_many_extraField` use the YAML list syntax. ```yml - Player: - john: - Name: John - joe: - Name: Joe - jack: - Name: Jack - Team: - hurricanes: - Name: The Hurricanes - Players: - - =>Player.john: - Role: Captain + Player: + john: + Name: John + joe: + Name: Joe + jack: + Name: Jack + Team: + hurricanes: + Name: The Hurricanes + Players: + - =>Player.john: + Role: Captain - crusaders: - Name: The Crusaders - Players: - - =>Player.joe: - Role: Captain - - =>Player.jack: - Role: Winger + crusaders: + Name: The Crusaders + Players: + - =>Player.joe: + Role: Captain + - =>Player.jack: + Role: Winger ``` ## Fixture Factories @@ -293,18 +293,18 @@ using them. ```php - $factory = Injector::inst()->create('FixtureFactory'); + $factory = Injector::inst()->create('FixtureFactory'); - $obj = $factory->createObject('Team', 'hurricanes'); + $obj = $factory->createObject('Team', 'hurricanes'); ``` In order to create an object with certain properties, just add a third argument: ```php - $obj = $factory->createObject('Team', 'hurricanes', [ - 'Name' => 'My Value' - ]); + $obj = $factory->createObject('Team', 'hurricanes', [ + 'Name' => 'My Value' + ]); ``` @@ -317,7 +317,7 @@ After we've created this object in the factory, `getId` is used to retrieve it b ```php - $databaseId = $factory->getId('Team', 'hurricanes'); + $databaseId = $factory->getId('Team', 'hurricanes'); ``` ### Default Properties @@ -327,9 +327,9 @@ name, we can set the default to be `Unknown Team`. ```php - $factory->define('Team', [ - 'Name' => 'Unknown Team' - ]); + $factory->define('Team', [ + 'Name' => 'Unknown Team' + ]); ``` @@ -340,16 +340,16 @@ values based on other fixture data. ```php - $factory->define('Member', [ - 'Email' => function($obj, $data, $fixtures) { - if(isset($data['FirstName']) { - $obj->Email = strtolower($data['FirstName']) . '@example.org'; - } - }, - 'Score' => function($obj, $data, $fixtures) { - $obj->Score = rand(0,10); - } - )]; + $factory->define('Member', [ + 'Email' => function($obj, $data, $fixtures) { + if(isset($data['FirstName']) { + $obj->Email = strtolower($data['FirstName']) . '@example.org'; + } + }, + 'Score' => function($obj, $data, $fixtures) { + $obj->Score = rand(0,10); + } + )]; ``` @@ -360,9 +360,9 @@ Model relations can be expressed through the same notation as in the YAML fixtur ```php - $obj = $factory->createObject('Team', 'hurricanes', [ - 'MyHasManyRelation' => '=>Player.john,=>Player.joe' - ]); + $obj = $factory->createObject('Team', 'hurricanes', [ + 'MyHasManyRelation' => '=>Player.john,=>Player.joe' + ]); ``` @@ -373,13 +373,13 @@ publish a page, which requires a method call. ```php - $blueprint = Injector::inst()->create('FixtureBlueprint', 'Member'); + $blueprint = Injector::inst()->create('FixtureBlueprint', 'Member'); - $blueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) { - $obj->copyVersionToStage(Versioned::DRAFT, Versioned::LIVE); - }); + $blueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) { + $obj->copyVersionToStage(Versioned::DRAFT, Versioned::LIVE); + }); - $page = $factory->define('Page', $blueprint); + $page = $factory->define('Page', $blueprint); ``` Available callbacks: @@ -395,20 +395,20 @@ equal the class names they manage. ```php - $memberBlueprint = Injector::inst()->create('FixtureBlueprint', 'Member', 'Member'); + $memberBlueprint = Injector::inst()->create('FixtureBlueprint', 'Member', 'Member'); - $adminBlueprint = Injector::inst()->create('FixtureBlueprint', 'AdminMember', 'Member'); + $adminBlueprint = Injector::inst()->create('FixtureBlueprint', 'AdminMember', 'Member'); - $adminBlueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) { - if(isset($fixtures['Group']['admin'])) { - $adminGroup = Group::get()->byId($fixtures['Group']['admin']); - $obj->Groups()->add($adminGroup); - } - }); + $adminBlueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) { + if(isset($fixtures['Group']['admin'])) { + $adminGroup = Group::get()->byId($fixtures['Group']['admin']); + $obj->Groups()->add($adminGroup); + } + }); - $member = $factory->createObject('Member'); // not in admin group + $member = $factory->createObject('Member'); // not in admin group - $admin = $factory->createObject('AdminMember'); // in admin group + $admin = $factory->createObject('AdminMember'); // in admin group ``` ## Related Documentation diff --git a/docs/en/02_Developer_Guides/06_Testing/How_Tos/00_Write_a_SapphireTest.md b/docs/en/02_Developer_Guides/06_Testing/How_Tos/00_Write_a_SapphireTest.md index d087450b0..67cc5c1fd 100644 --- a/docs/en/02_Developer_Guides/06_Testing/How_Tos/00_Write_a_SapphireTest.md +++ b/docs/en/02_Developer_Guides/06_Testing/How_Tos/00_Write_a_SapphireTest.md @@ -9,41 +9,41 @@ how you can load default records into the test database. ```php - + use SilverStripe\Dev\SapphireTest; - class PageTest extends SapphireTest + class PageTest extends SapphireTest { - /** - * Defines the fixture file to use for this test class - * @var string - */ - protected static $fixture_file = 'SiteTreeTest.yml'; + /** + * Defines the fixture file to use for this test class + * @var string + */ + protected static $fixture_file = 'SiteTreeTest.yml'; - /** - * Test generation of the URLSegment values. - * - * Makes sure to: - * - Turn things into lowercase-hyphen-format - * - Generates from Title by default, unless URLSegment is explicitly set - * - Resolves duplicates by appending a number - */ - public function testURLGeneration() + /** + * Test generation of the URLSegment values. + * + * Makes sure to: + * - Turn things into lowercase-hyphen-format + * - Generates from Title by default, unless URLSegment is explicitly set + * - Resolves duplicates by appending a number + */ + public function testURLGeneration() { - $expectedURLs = [ - 'home' => 'home', - 'staff' => 'my-staff', - 'about' => 'about-us', - 'staffduplicate' => 'my-staff-2' - ]; + $expectedURLs = [ + 'home' => 'home', + 'staff' => 'my-staff', + 'about' => 'about-us', + 'staffduplicate' => 'my-staff-2' + ]; - foreach($expectedURLs as $fixture => $urlSegment) { - $obj = $this->objFromFixture('Page', $fixture); + foreach($expectedURLs as $fixture => $urlSegment) { + $obj = $this->objFromFixture('Page', $fixture); - $this->assertEquals($urlSegment, $obj->URLSegment); - } - } - } + $this->assertEquals($urlSegment, $obj->URLSegment); + } + } + } ``` diff --git a/docs/en/02_Developer_Guides/06_Testing/How_Tos/01_Write_a_FunctionalTest.md b/docs/en/02_Developer_Guides/06_Testing/How_Tos/01_Write_a_FunctionalTest.md index 4608c185a..b9d66e4e5 100644 --- a/docs/en/02_Developer_Guides/06_Testing/How_Tos/01_Write_a_FunctionalTest.md +++ b/docs/en/02_Developer_Guides/06_Testing/How_Tos/01_Write_a_FunctionalTest.md @@ -11,43 +11,43 @@ response and modify the session within a test. ```php - use SilverStripe\Security\Member; + use SilverStripe\Security\Member; - class HomePageTest extends FunctionalTest - { + class HomePageTest extends FunctionalTest + { - /** - * Test generation of the view - */ - public function testViewHomePage() - { - $page = $this->get('home/'); + /** + * Test generation of the view + */ + public function testViewHomePage() + { + $page = $this->get('home/'); - // Home page should load.. - $this->assertEquals(200, $page->getStatusCode()); + // Home page should load.. + $this->assertEquals(200, $page->getStatusCode()); - // We should see a login form - $login = $this->submitForm("LoginFormID", null, [ - 'Email' => 'test@test.com', - 'Password' => 'wrongpassword' - ]); + // We should see a login form + $login = $this->submitForm("LoginFormID", null, [ + 'Email' => 'test@test.com', + 'Password' => 'wrongpassword' + ]); - // wrong details, should now see an error message - $this->assertExactHTMLMatchBySelector("#LoginForm p.error", [ - "That email address is invalid." - ]); + // wrong details, should now see an error message + $this->assertExactHTMLMatchBySelector("#LoginForm p.error", [ + "That email address is invalid." + ]); - // If we login as a user we should see a welcome message - $me = Member::get()->first(); + // If we login as a user we should see a welcome message + $me = Member::get()->first(); - $this->logInAs($me); - $page = $this->get('home/'); + $this->logInAs($me); + $page = $this->get('home/'); - $this->assertExactHTMLMatchBySelector("#Welcome", [ - 'Welcome Back' - ]); - } - } + $this->assertExactHTMLMatchBySelector("#Welcome", [ + 'Welcome Back' + ]); + } + } ``` diff --git a/docs/en/02_Developer_Guides/06_Testing/How_Tos/02_FixtureFactories.md b/docs/en/02_Developer_Guides/06_Testing/How_Tos/02_FixtureFactories.md index aa8081379..735a93741 100644 --- a/docs/en/02_Developer_Guides/06_Testing/How_Tos/02_FixtureFactories.md +++ b/docs/en/02_Developer_Guides/06_Testing/How_Tos/02_FixtureFactories.md @@ -10,39 +10,39 @@ with information that we need. ```php - use SilverStripe\Core\Injector\Injector; + use SilverStripe\Core\Injector\Injector; - class MyObjectTest extends SapphireTest - { + class MyObjectTest extends SapphireTest + { - protected $factory; + protected $factory; - function __construct() { - parent::__construct(); + function __construct() { + parent::__construct(); - $factory = Injector::inst()->create('FixtureFactory'); + $factory = Injector::inst()->create('FixtureFactory'); - // Defines a "blueprint" for new objects - $factory->define('MyObject', [ - 'MyProperty' => 'My Default Value' - ]); + // Defines a "blueprint" for new objects + $factory->define('MyObject', [ + 'MyProperty' => 'My Default Value' + ]); - $this->factory = $factory; - } + $this->factory = $factory; + } - function testSomething() { - $MyObjectObj = $this->factory->createObject( - 'MyObject', - ['MyOtherProperty' => 'My Custom Value'] - ); + function testSomething() { + $MyObjectObj = $this->factory->createObject( + 'MyObject', + ['MyOtherProperty' => 'My Custom Value'] + ); - echo $MyObjectObj->MyProperty; - // returns "My Default Value" + echo $MyObjectObj->MyProperty; + // returns "My Default Value" - echo $myPageObj->MyOtherProperty; - // returns "My Custom Value" - } - } + echo $myPageObj->MyOtherProperty; + // returns "My Custom Value" + } + } ``` diff --git a/docs/en/02_Developer_Guides/06_Testing/How_Tos/03_Testing_Email.md b/docs/en/02_Developer_Guides/06_Testing/How_Tos/03_Testing_Email.md index 24651a926..87f9cba46 100644 --- a/docs/en/02_Developer_Guides/06_Testing/How_Tos/03_Testing_Email.md +++ b/docs/en/02_Developer_Guides/06_Testing/How_Tos/03_Testing_Email.md @@ -8,24 +8,24 @@ email was sent using this method. ```php - public function MyMethod() - { - $e = new Email(); - $e->To = "someone@example.com"; - $e->Subject = "Hi there"; - $e->Body = "I just really wanted to email you and say hi."; - $e->send(); - } + public function MyMethod() + { + $e = new Email(); + $e->To = "someone@example.com"; + $e->Subject = "Hi there"; + $e->Body = "I just really wanted to email you and say hi."; + $e->send(); + } ``` To test that `MyMethod` sends the correct email, use the [SapphireTest::assertEmailSent()](api:SilverStripe\Dev\SapphireTest::assertEmailSent()) method. ```php - $this->assertEmailSent($to, $from, $subject, $body); + $this->assertEmailSent($to, $from, $subject, $body); - // to assert that the email is sent to the correct person - $this->assertEmailSent("someone@example.com", null, "/th.*e$/"); + // to assert that the email is sent to the correct person + $this->assertEmailSent("someone@example.com", null, "/th.*e$/"); ``` Each of the arguments (`$to`, `$from`, `$subject` and `$body`) can be either one of the following. diff --git a/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md b/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md index 0168939db..d8a537a04 100644 --- a/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md +++ b/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md @@ -12,13 +12,13 @@ The definition of setting an environment type in a `mysite/_config/app.yml` look ```yml - SilverStripe\Control\Director: - environment_type: 'dev' + SilverStripe\Control\Director: + environment_type: 'dev' ``` The definition of setting an environment type in a `.env` file looks like ``` - SS_ENVIRONMENT_TYPE="dev" + SS_ENVIRONMENT_TYPE="dev" ``` The three environment types you can set are `dev`, `test` and `live`. @@ -44,12 +44,12 @@ want to password protect the site. You can enable that by adding this to your `m ```yml - --- - Only: - environment: 'test' - --- - SilverStripe\Security\BasicAuth: - entire_site_protected: true + --- + Only: + environment: 'test' + --- + SilverStripe\Security\BasicAuth: + entire_site_protected: true ``` ### Live Mode @@ -67,29 +67,29 @@ You can check for the current environment type in [config files](../configuratio **mysite/_config/app.yml** ```yml - --- - Only: - environment: 'live' - --- - MyClass: - myvar: live_value - --- - Only: - environment: 'test' - --- - MyClass: - myvar: test_value + --- + Only: + environment: 'live' + --- + MyClass: + myvar: live_value + --- + Only: + environment: 'test' + --- + MyClass: + myvar: test_value ``` Checking for what environment you're running in can also be done in PHP. Your application code may disable or enable certain functionality depending on the environment type. ```php - if (Director::isLive()) { - // is in live - } elseif (Director::isTest()) { - // is in test mode - } elseif (Director::isDev()) { - // is in dev mode - } + if (Director::isLive()) { + // is in live + } elseif (Director::isTest()) { + // is in test mode + } elseif (Director::isDev()) { + // is in dev mode + } ``` diff --git a/docs/en/02_Developer_Guides/07_Debugging/03_Template_debugging.md b/docs/en/02_Developer_Guides/07_Debugging/03_Template_debugging.md index 704997f88..5a4213b44 100644 --- a/docs/en/02_Developer_Guides/07_Debugging/03_Template_debugging.md +++ b/docs/en/02_Developer_Guides/07_Debugging/03_Template_debugging.md @@ -11,10 +11,10 @@ source code comments indicating which template is responsible for rendering each block of html on your page. ```yaml - --- - Only: - environment: 'dev' - --- - SSViewer: - source_file_comments: true + --- + Only: + environment: 'dev' + --- + SSViewer: + source_file_comments: true ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/07_Debugging/index.md b/docs/en/02_Developer_Guides/07_Debugging/index.md index 3f8ec4712..ea79c240f 100644 --- a/docs/en/02_Developer_Guides/07_Debugging/index.md +++ b/docs/en/02_Developer_Guides/07_Debugging/index.md @@ -17,7 +17,7 @@ bottle-necks and identify slow moving parts of your application chain. The [Debug](api:SilverStripe\Dev\Debug) class contains a number of static utility methods for more advanced debugging. - :::php +```php Debug::show($myVariable); // similar to print_r($myVariable) but shows it in a more useful format. @@ -26,6 +26,7 @@ The [Debug](api:SilverStripe\Dev\Debug) class contains a number of static utilit Backtrace::backtrace(); // prints a calls-stack +``` ## API Documentation diff --git a/docs/en/02_Developer_Guides/08_Performance/00_Partial_Caching.md b/docs/en/02_Developer_Guides/08_Performance/00_Partial_Caching.md index de5ac7b71..9a597b31f 100644 --- a/docs/en/02_Developer_Guides/08_Performance/00_Partial_Caching.md +++ b/docs/en/02_Developer_Guides/08_Performance/00_Partial_Caching.md @@ -6,10 +6,10 @@ summary: Cache SilverStripe templates to reduce database queries. Partial caching is a feature that allows the caching of just a portion of a page. ```ss - <% cached 'CacheKey' %> - $DataTable - ... - <% end_cached %> + <% cached 'CacheKey' %> + $DataTable + ... + <% end_cached %> ``` Each cache block has a cache key. A cache key is an unlimited number of comma separated variables and quoted strings. @@ -24,17 +24,17 @@ Here are some more complex examples: ```ss - <% cached 'database', $LastEdited %> - - <% end_cached %> - - <% cached 'loginblock', $CurrentMember.ID %> - - <% end_cached %> + <% cached 'database', $LastEdited %> + + <% end_cached %> + + <% cached 'loginblock', $CurrentMember.ID %> + + <% end_cached %> - <% cached 'loginblock', $LastEdited, $CurrentMember.isAdmin %> - - <% end_cached %> + <% cached 'loginblock', $LastEdited, $CurrentMember.isAdmin %> + + <% end_cached %> ``` An additional global key is incorporated in the cache lookup. The default value for this is @@ -50,8 +50,8 @@ user does not influence your template content, you can update this key as below; ```yaml - SilverStripe\View\SSViewer: - global_key: '$CurrentReadingMode, $Locale' + SilverStripe\View\SSViewer: + global_key: '$CurrentReadingMode, $Locale' ``` ## Aggregates @@ -66,7 +66,7 @@ otherwise. By using aggregates, we do that like this: ```ss - <% cached 'navigation', $List('SiteTree').max('LastEdited'), $List('SiteTree').count() %> + <% cached 'navigation', $List('SiteTree').max('LastEdited'), $List('SiteTree').count() %> ``` The cache for this will update whenever a page is added, removed or edited. @@ -77,7 +77,7 @@ or edited ```ss - <% cached 'categorylist', $List('Category').max('LastEdited'), $List('Category').count() %> + <% cached 'categorylist', $List('Category').max('LastEdited'), $List('Category').count() %> ```
      @@ -98,17 +98,17 @@ For example, a block that shows a collection of rotating slides needs to update ```php - public function SliderCacheKey() - { - $fragments = [ - 'Page-Slides', - $this->ID, - // identify which objects are in the list and their sort order - implode('-', $this->Slides()->Column('ID')), - $this->Slides()->max('LastEdited') - ]; - return implode('-_-', $fragments); - } + public function SliderCacheKey() + { + $fragments = [ + 'Page-Slides', + $this->ID, + // identify which objects are in the list and their sort order + implode('-', $this->Slides()->Column('ID')), + $this->Slides()->max('LastEdited') + ]; + return implode('-_-', $fragments); + } ``` @@ -117,7 +117,7 @@ Then reference that function in the cache key: ```ss - <% cached $SliderCacheKey %> + <% cached $SliderCacheKey %> ``` The example above would work for both a has_many and many_many relationship. @@ -139,7 +139,7 @@ For instance, if we show some blog statistics, but are happy having them be slig ```ss - <% cached 'blogstatistics', $Blog.ID %> + <% cached 'blogstatistics', $Blog.ID %> ``` which will invalidate after the cache lifetime expires. If you need more control than that (cache lifetime is @@ -147,10 +147,10 @@ configurable only on a site-wide basis), you could add a special function to you ```php - public function BlogStatisticsCounter() - { - return (int)(time() / 60 / 5); // Returns a new number every five minutes - } + public function BlogStatisticsCounter() + { + return (int)(time() / 60 / 5); // Returns a new number every five minutes + } ``` @@ -159,7 +159,7 @@ and then use it in the cache key ```ss - <% cached 'blogstatistics', $Blog.ID, $BlogStatisticsCounter %> + <% cached 'blogstatistics', $Blog.ID, $BlogStatisticsCounter %> ``` ## Cache block conditionals @@ -174,7 +174,7 @@ heavy load: ```ss - <% cached 'blogstatistics', $Blog.ID if $HighLoad %> + <% cached 'blogstatistics', $Blog.ID if $HighLoad %> ``` By adding a `HighLoad` function to your `PageController`, you could enable or disable caching dynamically. @@ -185,7 +185,7 @@ To cache the contents of a page for all anonymous users, but dynamically calcula ```ss - <% cached unless $CurrentUser %> + <% cached unless $CurrentUser %> ``` ## Uncached @@ -197,7 +197,7 @@ particular cache block by changing just the tag, leaving the key and conditional ```ss - <% uncached %> + <% uncached %> ``` ## Nested cache blocks @@ -213,15 +213,15 @@ An example: ```ss - <% cached $LastEdited %> - Our wonderful site - - <% cached $Member.ID %> - Welcome $Member.Name - <% end_cached %> - - $ASlowCalculation - <% end_cached %> + <% cached $LastEdited %> + Our wonderful site + + <% cached $Member.ID %> + Welcome $Member.Name + <% end_cached %> + + $ASlowCalculation + <% end_cached %> ``` This will cache the entire outer section until the next time the page is edited, but will display a different welcome @@ -233,15 +233,15 @@ could also write the last example as: ```ss - <% cached $LastEdited %> - Our wonderful site - - <% uncached %> - Welcome $Member.Name - <% end_uncached %> - - $ASlowCalculation - <% end_cached %> + <% cached $LastEdited %> + Our wonderful site + + <% uncached %> + Welcome $Member.Name + <% end_uncached %> + + $ASlowCalculation + <% end_cached %> ```
      @@ -254,15 +254,15 @@ Failing example: ```ss - <% cached $LastEdited %> - - <% loop $Children %> - <% cached $LastEdited %> - $Name - <% end_cached %> - <% end_loop %> - - <% end_cached %> + <% cached $LastEdited %> + + <% loop $Children %> + <% cached $LastEdited %> + $Name + <% end_cached %> + <% end_loop %> + + <% end_cached %> ``` Can be re-written as: @@ -270,15 +270,15 @@ Can be re-written as: ```ss - <% cached $LastEdited %> - - <% cached $AllChildren.max('LastEdited') %> - <% loop $Children %> - $Name - <% end_loop %> - <% end_cached %> - - <% end_cached %> + <% cached $LastEdited %> + + <% cached $AllChildren.max('LastEdited') %> + <% loop $Children %> + $Name + <% end_loop %> + <% end_cached %> + + <% end_cached %> ``` Or: @@ -286,13 +286,13 @@ Or: ```ss - <% cached $LastEdited %> - (other code) - <% end_cached %> - - <% loop $Children %> - <% cached $LastEdited %> - $Name - <% end_cached %> - <% end_loop %> + <% cached $LastEdited %> + (other code) + <% end_cached %> + + <% loop $Children %> + <% cached $LastEdited %> + $Name + <% end_cached %> + <% end_loop %> ``` diff --git a/docs/en/02_Developer_Guides/08_Performance/01_Caching.md b/docs/en/02_Developer_Guides/08_Performance/01_Caching.md index 95c5017eb..050e8bfa2 100644 --- a/docs/en/02_Developer_Guides/08_Performance/01_Caching.md +++ b/docs/en/02_Developer_Guides/08_Performance/01_Caching.md @@ -65,7 +65,7 @@ Cache objects follow the [PSR-16](http://www.php-fig.org/psr/psr-16/) class inte ```php - use Psr\SimpleCache\CacheInterface + use Psr\SimpleCache\CacheInterface $cache = Injector::inst()->get(CacheInterface::class . '.myCache'); diff --git a/docs/en/02_Developer_Guides/08_Performance/02_HTTP_Cache_Headers.md b/docs/en/02_Developer_Guides/08_Performance/02_HTTP_Cache_Headers.md index b2920cce7..750d9d095 100644 --- a/docs/en/02_Developer_Guides/08_Performance/02_HTTP_Cache_Headers.md +++ b/docs/en/02_Developer_Guides/08_Performance/02_HTTP_Cache_Headers.md @@ -18,7 +18,7 @@ headers: ### HTTP::set_cache_age ```php - HTTP::set_cache_age(0); + HTTP::set_cache_age(0); ``` Used to set the max-age component of the cache-control line, in seconds. Set it to 0 to disable caching; the "no-cache" @@ -28,7 +28,7 @@ clause in `Cache-Control` and `Pragma` will be included. ```php - HTTP::register_modification_date('2014-10-10'); + HTTP::register_modification_date('2014-10-10'); ``` Used to set the modification date to something more recent than the default. [DataObject::__construct](api:SilverStripe\ORM\DataObject::__construct) calls diff --git a/docs/en/02_Developer_Guides/08_Performance/05_Resource_Usage.md b/docs/en/02_Developer_Guides/08_Performance/05_Resource_Usage.md index 6cf4bd59c..5e6434f6f 100644 --- a/docs/en/02_Developer_Guides/08_Performance/05_Resource_Usage.md +++ b/docs/en/02_Developer_Guides/08_Performance/05_Resource_Usage.md @@ -24,8 +24,8 @@ SilverStripe can request more resources through `Environment::increaseMemoryLimi
      ```php - public function myBigFunction() - { - Environment::increaseTimeLimitTo(400); - } + public function myBigFunction() + { + Environment::increaseTimeLimitTo(400); + } ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/09_Security/00_Member.md b/docs/en/02_Developer_Guides/09_Security/00_Member.md index 7ddc8bc71..c04e93e0a 100644 --- a/docs/en/02_Developer_Guides/09_Security/00_Member.md +++ b/docs/en/02_Developer_Guides/09_Security/00_Member.md @@ -14,11 +14,11 @@ Returns the full *Member* Object for the current user, returns *null* if user is ```php - if( $member = Security::getCurrentUser() ) { - // Work with $member - } else { - // Do non-member stuff - } + if( $member = Security::getCurrentUser() ) { + // Work with $member + } else { + // Do non-member stuff + } ``` ## Subclassing @@ -32,15 +32,15 @@ You can define subclasses of [Member](api:SilverStripe\Security\Member) to add e ```php - use SilverStripe\Security\Member; + use SilverStripe\Security\Member; - class MyMember extends Member - { - private static $db = [ - "Age" => "Int", - "Address" => "Text", - ]; - } + class MyMember extends Member + { + private static $db = [ + "Age" => "Int", + "Address" => "Text", + ]; + } ``` @@ -61,14 +61,14 @@ parent::getCMSFields() and manipulate the [FieldList](api:SilverStripe\Forms\Fie ```php - public function getCMSFields() - { - $fields = parent::getCMSFields(); - $fields->insertBefore("HTMLEmail", new TextField("Age")); - $fields->removeByName("JobTitle"); - $fields->removeByName("Organisation"); - return $fields; - } + public function getCMSFields() + { + $fields = parent::getCMSFields(); + $fields->insertBefore("HTMLEmail", new TextField("Age")); + $fields->removeByName("JobTitle"); + $fields->removeByName("Organisation"); + return $fields; + } ``` ## Extending Member or DataObject? @@ -89,9 +89,9 @@ class. A better way is to use role extensions to add this behaviour. Add the fol ```yml - Member: - extensions: - - MyMemberExtension + Member: + extensions: + - MyMemberExtension ``` A role extension is simply a subclass of [DataExtension](api:SilverStripe\ORM\DataExtension) that is designed to be used to add behaviour to [Member](api:SilverStripe\Security\Member). @@ -100,35 +100,35 @@ things, you should add appropriate [Permission::checkMember()](api:SilverStripe\ ```php - use SilverStripe\Security\Permission; - use SilverStripe\ORM\DataExtension; + use SilverStripe\Security\Permission; + use SilverStripe\ORM\DataExtension; - class MyMemberExtension extends DataExtension - { - /** - - * Modify the field set to be displayed in the CMS detail pop-up - */ - public function updateCMSFields(FieldList $currentFields) - { - // Only show the additional fields on an appropriate kind of use - if(Permission::checkMember($this->owner->ID, "VIEW_FORUM")) { - // Edit the FieldList passed, adding or removing fields as necessary - } - } - - // define additional properties - private static $db = []; - private static $has_one = []; - private static $has_many = []; - private static $many_many = []; - private static $belongs_many_many = []; - - public function somethingElse() - { - // You can add any other methods you like, which you can call directly on the member object. - } - } + class MyMemberExtension extends DataExtension + { + /** + + * Modify the field set to be displayed in the CMS detail pop-up + */ + public function updateCMSFields(FieldList $currentFields) + { + // Only show the additional fields on an appropriate kind of use + if(Permission::checkMember($this->owner->ID, "VIEW_FORUM")) { + // Edit the FieldList passed, adding or removing fields as necessary + } + } + + // define additional properties + private static $db = []; + private static $has_one = []; + private static $has_many = []; + private static $many_many = []; + private static $belongs_many_many = []; + + public function somethingElse() + { + // You can add any other methods you like, which you can call directly on the member object. + } + } ``` diff --git a/docs/en/02_Developer_Guides/09_Security/03_Authentication.md b/docs/en/02_Developer_Guides/09_Security/03_Authentication.md index a958a4e49..b41e3e5e5 100644 --- a/docs/en/02_Developer_Guides/09_Security/03_Authentication.md +++ b/docs/en/02_Developer_Guides/09_Security/03_Authentication.md @@ -39,9 +39,9 @@ and password to be configured for a single special user outside of the normal me It is advisable to configure this user in your `.env` file inside of the web root, as below: ``` - # Configure a default username and password to access the CMS on all sites in this environment. - SS_DEFAULT_ADMIN_USERNAME="admin" - SS_DEFAULT_ADMIN_PASSWORD="password" + # Configure a default username and password to access the CMS on all sites in this environment. + SS_DEFAULT_ADMIN_USERNAME="admin" + SS_DEFAULT_ADMIN_PASSWORD="password" ``` When a user logs in with these credentials, then a [Member](api:SilverStripe\Security\Member) with the Email 'admin' will be generated in the database, but without any password information. This means that the password can be reset or changed by simply diff --git a/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md b/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md index 5dbe4fd86..b55d1b042 100644 --- a/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md +++ b/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md @@ -26,13 +26,13 @@ come from user input. Example: ```php - $records = DB::prepared_query('SELECT * FROM "MyClass" WHERE "ID" = ?', [3]); - $records = MyClass::get()->where(['"ID" = ?' => 3]); - $records = MyClass::get()->where(['"ID"' => 3]); - $records = DataObject::get_by_id('MyClass', 3); - $records = DataObject::get_one('MyClass', ['"ID" = ?' => 3]); - $records = MyClass::get()->byID(3); - $records = SQLSelect::create()->addWhere(['"ID"' => 3])->execute(); + $records = DB::prepared_query('SELECT * FROM "MyClass" WHERE "ID" = ?', [3]); + $records = MyClass::get()->where(['"ID" = ?' => 3]); + $records = MyClass::get()->where(['"ID"' => 3]); + $records = DataObject::get_by_id('MyClass', 3); + $records = DataObject::get_one('MyClass', ['"ID" = ?' => 3]); + $records = MyClass::get()->byID(3); + $records = SQLSelect::create()->addWhere(['"ID"' => 3])->execute(); ``` @@ -40,20 +40,20 @@ Parameterised updates and inserts are also supported, but the syntax is a little ```php - SQLInsert::create('"MyClass"') - ->assign('"Name"', 'Daniel') - ->addAssignments([ - '"Position"' => 'Accountant', - '"Age"' => [ - 'GREATEST(0,?,?)' => [24, 28] - ] - ]) - ->assignSQL('"Created"', 'NOW()') - ->execute(); - DB::prepared_query( - 'INSERT INTO "MyClass" ("Name", "Position", "Age", "Created") VALUES(?, ?, GREATEST(0,?,?), NOW())' - ['Daniel', 'Accountant', 24, 28] - ); + SQLInsert::create('"MyClass"') + ->assign('"Name"', 'Daniel') + ->addAssignments([ + '"Position"' => 'Accountant', + '"Age"' => [ + 'GREATEST(0,?,?)' => [24, 28] + ] + ]) + ->assignSQL('"Created"', 'NOW()') + ->execute(); + DB::prepared_query( + 'INSERT INTO "MyClass" ("Name", "Position", "Age", "Created") VALUES(?, ?, GREATEST(0,?,?), NOW())' + ['Daniel', 'Accountant', 24, 28] + ); ``` @@ -80,14 +80,14 @@ handled via prepared statements. Example: ```php - // automatically escaped/quoted - $members = Member::get()->filter('Name', $_GET['name']); - // automatically escaped/quoted - $members = Member::get()->filter(['Name' => $_GET['name']]); - // parameterised condition - $members = Member::get()->where(['"Name" = ?' => $_GET['name']]); - // needs to be escaped and quoted manually (note raw2sql called with the $quote parameter set to true) - $members = Member::get()->where(sprintf('"Name" = %s', Convert::raw2sql($_GET['name'], true))); + // automatically escaped/quoted + $members = Member::get()->filter('Name', $_GET['name']); + // automatically escaped/quoted + $members = Member::get()->filter(['Name' => $_GET['name']]); + // parameterised condition + $members = Member::get()->where(['"Name" = ?' => $_GET['name']]); + // needs to be escaped and quoted manually (note raw2sql called with the $quote parameter set to true) + $members = Member::get()->where(sprintf('"Name" = %s', Convert::raw2sql($_GET['name'], true))); ``` @@ -114,19 +114,19 @@ Example: ```php - use SilverStripe\Core\Convert; - use SilverStripe\Forms\Form; + use SilverStripe\Core\Convert; + use SilverStripe\Forms\Form; - class MyForm extends Form - { - public function save($RAW_data, $form) - { - // Pass true as the second parameter of raw2sql to quote the value safely - $SQL_data = Convert::raw2sql($RAW_data, true); // works recursively on an array - $objs = Player::get()->where("Name = " . $SQL_data['name']); - // ... - } - } + class MyForm extends Form + { + public function save($RAW_data, $form) + { + // Pass true as the second parameter of raw2sql to quote the value safely + $SQL_data = Convert::raw2sql($RAW_data, true); // works recursively on an array + $objs = Player::get()->where("Name = " . $SQL_data['name']); + // ... + } + } ``` @@ -137,20 +137,20 @@ Example: ```php - use SilverStripe\Core\Convert; - use SilverStripe\Control\Controller; + use SilverStripe\Core\Convert; + use SilverStripe\Control\Controller; - class MyController extends Controller - { - private static $allowed_actions = ['myurlaction']; - public function myurlaction($RAW_urlParams) - { - // Pass true as the second parameter of raw2sql to quote the value safely - $SQL_urlParams = Convert::raw2sql($RAW_urlParams, true); // works recursively on an array - $objs = Player::get()->where("Name = " . $SQL_data['OtherID']); - // ... - } - } + class MyController extends Controller + { + private static $allowed_actions = ['myurlaction']; + public function myurlaction($RAW_urlParams) + { + // Pass true as the second parameter of raw2sql to quote the value safely + $SQL_urlParams = Convert::raw2sql($RAW_urlParams, true); // works recursively on an array + $objs = Player::get()->where("Name = " . $SQL_data['OtherID']); + // ... + } + } ``` @@ -160,27 +160,27 @@ passing data through, escaping should happen at the end of the chain. ```php - use SilverStripe\Core\Convert; - use SilverStripe\ORM\DB; - use SilverStripe\Control\Controller; + use SilverStripe\Core\Convert; + use SilverStripe\ORM\DB; + use SilverStripe\Control\Controller; - class MyController extends Controller - { - /** - * @param array $RAW_data All names in an indexed array (not SQL-safe) - */ - public function saveAllNames($RAW_data) - { - // $SQL_data = Convert::raw2sql($RAW_data); // premature escaping - foreach($RAW_data as $item) $this->saveName($item); - } - - public function saveName($RAW_name) - { - $SQL_name = Convert::raw2sql($RAW_name, true); - DB::query("UPDATE Player SET Name = {$SQL_name}"); - } - } + class MyController extends Controller + { + /** + * @param array $RAW_data All names in an indexed array (not SQL-safe) + */ + public function saveAllNames($RAW_data) + { + // $SQL_data = Convert::raw2sql($RAW_data); // premature escaping + foreach($RAW_data as $item) $this->saveName($item); + } + + public function saveName($RAW_name) + { + $SQL_name = Convert::raw2sql($RAW_name, true); + DB::query("UPDATE Player SET Name = {$SQL_name}"); + } + } ``` @@ -217,7 +217,7 @@ stripped out To enable filtering, set the HtmlEditorField::$sanitise_server_side [configuration](/developer_guides/configuration/configuration) property to true, e.g. ``` - HtmlEditorField::config()->sanitise_server_side = true + HtmlEditorField::config()->sanitise_server_side = true ``` The built in sanitiser enforces the TinyMCE whitelist rules on the server side, and is sufficient to eliminate the most common XSS vectors. @@ -248,15 +248,15 @@ PHP: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyObject extends DataObject - { - private static $db = [ - 'MyEscapedValue' => 'Text', // Example value: not bold - 'MyUnescapedValue' => 'HTMLText' // Example value: bold - ]; - } + class MyObject extends DataObject + { + private static $db = [ + 'MyEscapedValue' => 'Text', // Example value: not bold + 'MyUnescapedValue' => 'HTMLText' // Example value: bold + ]; + } ``` @@ -264,10 +264,10 @@ Template: ```php -
        -
      • $MyEscapedValue
        • // output: <b>not bold<b> -
      • $MyUnescapedValue
        • // output: bold -
      +
        +
      • $MyEscapedValue
        • // output: <b>not bold<b> +
      • $MyUnescapedValue
        • // output: bold +
      ``` The example below assumes that data wasn't properly filtered when saving to the database, but are escaped before @@ -282,13 +282,13 @@ Template (see above): ```php -
        - // output: foo & "bar" -
      • $Title
        • -
      • $MyEscapedValue
        • // output: <b>not bold<b> -
      • $MyUnescapedValue
        • // output: bold -
      • $MyUnescapedValue.XML
        • // output: <b>bold<b> -
      +
        + // output: foo & "bar" +
      • $Title
        • +
      • $MyEscapedValue
        • // output: <b>not bold<b> +
      • $MyUnescapedValue
        • // output: bold +
      • $MyUnescapedValue.XML
        • // output: <b>bold<b> +
      ``` ### Escaping custom attributes and getters @@ -300,23 +300,23 @@ PHP: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyObject extends DataObject - { - public $Title = 'not bold'; // will be escaped due to Text casting - - $casting = [ - "Title" => "Text", // forcing a casting - 'TitleWithHTMLSuffix' => 'HTMLText' // optional, as HTMLText is the default casting - ]; - - public function TitleWithHTMLSuffix($suffix) - { - // $this->Title is not casted in PHP - return $this->Title . '(' . $suffix. ')'; - } - } + class MyObject extends DataObject + { + public $Title = 'not bold'; // will be escaped due to Text casting + + $casting = [ + "Title" => "Text", // forcing a casting + 'TitleWithHTMLSuffix' => 'HTMLText' // optional, as HTMLText is the default casting + ]; + + public function TitleWithHTMLSuffix($suffix) + { + // $this->Title is not casted in PHP + return $this->Title . '(' . $suffix. ')'; + } + } ``` @@ -324,11 +324,11 @@ Template: ```php -
        -
      • $Title
        • // output: <b>not bold<b> -
      • $Title.RAW
        • // output: not bold -
      • $TitleWithHTMLSuffix
        • // output: not bold: (...) -
      +
        +
      • $Title
        • // output: <b>not bold<b> +
      • $Title.RAW
        • // output: not bold +
      • $TitleWithHTMLSuffix
        • // output: not bold: (...) +
      ``` Note: Avoid generating HTML by string concatenation in PHP wherever possible to minimize risk and separate your @@ -346,23 +346,23 @@ PHP: ```php - use SilverStripe\Core\Convert; - use SilverStripe\Control\Controller; - use SilverStripe\ORM\FieldType\DBText; - use SilverStripe\ORM\FieldType\DBHTMLText; + use SilverStripe\Core\Convert; + use SilverStripe\Control\Controller; + use SilverStripe\ORM\FieldType\DBText; + use SilverStripe\ORM\FieldType\DBHTMLText; - class MyController extends Controller - { - private static $allowed_actions = ['search']; - public function search($request) - { - $htmlTitle = '

      Your results for:' . Convert::raw2xml($request->getVar('Query')) . '

      '; - return $this->customise([ - 'Query' => DBText::create($request->getVar('Query')), - 'HTMLTitle' => DBHTMLText::create($htmlTitle) - ]); - } - } + class MyController extends Controller + { + private static $allowed_actions = ['search']; + public function search($request) + { + $htmlTitle = '

      Your results for:' . Convert::raw2xml($request->getVar('Query')) . '

      '; + return $this->customise([ + 'Query' => DBText::create($request->getVar('Query')), + 'HTMLTitle' => DBHTMLText::create($htmlTitle) + ]); + } + } ``` @@ -370,7 +370,7 @@ Template: ```php -

      $HTMLTitle

      +

      $HTMLTitle

      ``` Whenever you insert a variable into an HTML attribute within a template, use $VarName.ATT, no not $VarName. @@ -386,21 +386,21 @@ PHP: ```php - use SilverStripe\Control\Controller; - use SilverStripe\ORM\FieldType\DBText; + use SilverStripe\Control\Controller; + use SilverStripe\ORM\FieldType\DBText; - class MyController extends Controller - { - private static $allowed_actions = ['search']; - public function search($request) - { - $rssRelativeLink = "/rss?Query=" . urlencode($_REQUEST['query']) . "&sortOrder=asc"; - $rssLink = Controller::join_links($this->Link(), $rssRelativeLink); - return $this->customise([ - "RSSLink" => DBText::create($rssLink), - ]); - } - } + class MyController extends Controller + { + private static $allowed_actions = ['search']; + public function search($request) + { + $rssRelativeLink = "/rss?Query=" . urlencode($_REQUEST['query']) . "&sortOrder=asc"; + $rssLink = Controller::join_links($this->Link(), $rssRelativeLink); + return $this->customise([ + "RSSLink" => DBText::create($rssLink), + ]); + } + } ``` @@ -408,7 +408,7 @@ Template: ```php - RSS feed + RSS feed ``` Some rules of thumb: @@ -457,21 +457,21 @@ Below is an example with different ways you would use this casting technique: ```php - public function CaseStudies() - { - - // cast an ID from URL parameters e.g. (mysite.com/home/action/ID) - $anotherID = (int)Director::urlParam['ID']; - - // perform a calculation, the prerequisite being $anotherID must be an integer - $calc = $anotherID + (5 - 2) / 2; - - // cast the 'category' GET variable as an integer - $categoryID = (int)$_GET['category']; - - // perform a byID(), which ensures the ID is an integer before querying - return CaseStudy::get()->byID($categoryID); - } + public function CaseStudies() + { + + // cast an ID from URL parameters e.g. (mysite.com/home/action/ID) + $anotherID = (int)Director::urlParam['ID']; + + // perform a calculation, the prerequisite being $anotherID must be an integer + $calc = $anotherID + (5 - 2) / 2; + + // cast the 'category' GET variable as an integer + $categoryID = (int)$_GET['category']; + + // perform a byID(), which ensures the ID is an integer before querying + return CaseStudy::get()->byID($categoryID); + } ``` The same technique can be employed anywhere in your PHP code you know something must be of a certain type. A list of PHP @@ -504,10 +504,10 @@ If you need users to access files with this extension, you can bypass the rules for a specific directory. Here's an example for a `.htaccess` file used by the Apache web server: ``` - - Order allow,deny - Allow from all - + + Order allow,deny + Allow from all + ``` ### User uploaded files @@ -555,11 +555,11 @@ a [PasswordValidator](api:SilverStripe\Security\PasswordValidator): ```php - $validator = new PasswordValidator(); - $validator->minLength(7); - $validator->checkHistoricalPasswords(6); - $validator->characterStrength(3, ["lowercase", "uppercase", "digits", "punctuation"]); - Member::set_password_validator($validator); + $validator = new PasswordValidator(); + $validator->minLength(7); + $validator->checkHistoricalPasswords(6); + $validator->characterStrength(3, ["lowercase", "uppercase", "digits", "punctuation"]); + Member::set_password_validator($validator); ``` @@ -585,16 +585,16 @@ controller's `init()` method: ```php - use SilverStripe\Control\Controller; + use SilverStripe\Control\Controller; - class MyController extends Controller - { - public function init() - { - parent::init(); - $this->getResponse()->addHeader('X-Frame-Options', 'SAMEORIGIN'); - } - } + class MyController extends Controller + { + public function init() + { + parent::init(); + $this->getResponse()->addHeader('X-Frame-Options', 'SAMEORIGIN'); + } + } ``` This is a recommended option to secure any controller which displays @@ -608,7 +608,7 @@ allows the configure of a whitelist of hosts that are allowed to access the syst this whitelist in your `.env` file, any request presenting a `Host` header that is _not_ in this list will be blocked with a HTTP 400 error: ``` - SS_ALLOWED_HOSTS="www.mysite.com,mysite.com,subdomain.mysite.com" + SS_ALLOWED_HOSTS="www.mysite.com,mysite.com,subdomain.mysite.com" ``` Please note that if this configuration is defined, you _must_ include _all_ subdomains (eg www.) that will be accessing the site. @@ -625,7 +625,7 @@ into visiting external sites. In order to prevent this kind of attack, it's necessary to whitelist trusted proxy server IPs using the SS_TRUSTED_PROXY_IPS define in your `.env`. ``` - SS_TRUSTED_PROXY_IPS="127.0.0.1,192.168.0.1" + SS_TRUSTED_PROXY_IPS="127.0.0.1,192.168.0.1" ``` If you wish to change the headers that are used to find the proxy information, you should reconfigure the TrustedProxyMiddleware service: @@ -639,9 +639,9 @@ TrustedProxyMiddleware service: ProxySchemeHeaders: X-Forwarded-Protocol ProxyIPHeaders: X-Forwarded-Ip - SS_TRUSTED_PROXY_HOST_HEADER="HTTP_X_FORWARDED_HOST" - SS_TRUSTED_PROXY_IP_HEADER="HTTP_X_FORWARDED_FOR" - SS_TRUSTED_PROXY_PROTOCOL_HEADER="HTTP_X_FORWARDED_PROTOCOL" + SS_TRUSTED_PROXY_HOST_HEADER="HTTP_X_FORWARDED_HOST" + SS_TRUSTED_PROXY_IP_HEADER="HTTP_X_FORWARDED_FOR" + SS_TRUSTED_PROXY_PROTOCOL_HEADER="HTTP_X_FORWARDED_PROTOCOL" ``` At the same time, you'll also need to define which headers you trust from these proxy IPs. Since there are multiple ways through which proxies can pass through HTTP information on the original hostname, IP and protocol, these values need to be adjusted for your specific proxy. The header names match their equivalent `$_SERVER` values. @@ -655,12 +655,12 @@ This behaviour is enabled whenever `SS_TRUSTED_PROXY_IPS` is defined, or if the following in your .htaccess to ensure this behaviour is activated. ``` - - # Ensure that X-Forwarded-Host is only allowed to determine the request - # hostname for servers ips defined by SS_TRUSTED_PROXY_IPS in your .env - # Note that in a future release this setting will be always on. - SetEnv BlockUntrustedIPs true - + + # Ensure that X-Forwarded-Host is only allowed to determine the request + # hostname for servers ips defined by SS_TRUSTED_PROXY_IPS in your .env + # Note that in a future release this setting will be always on. + SetEnv BlockUntrustedIPs true + ``` In a future release this behaviour will be changed to be on by default, and this environment @@ -672,9 +672,9 @@ variable will be no longer necessary, thus it will be necessary to always set SilverStripe recommends the use of TLS(HTTPS) for your application, and you can easily force the use through the director function `forceSSL()` ```php - if (!Director::isDev()) { - Director::forceSSL(); - } + if (!Director::isDev()) { + Director::forceSSL(); + } ``` Forcing HTTPS so requires a certificate to be purchased or obtained through a vendor such as @@ -685,8 +685,8 @@ use a [secure session](https://docs.silverstripe.org/en/3/developer_guides/cooki To do this, you may set the `cookie_secure` parameter to `true` in your `config.yml` for `Session` ```yml - Session: - cookie_secure: true + Session: + cookie_secure: true ``` For other cookies set by your application we should also ensure the users are provided with secure cookies by setting @@ -700,10 +700,10 @@ clear text and can be intercepted and stolen by an attacker who is listening on code. It is best practice to set this flag unless the application is known to use JavaScript to access these cookies as this prevents an attacker who achieves cross-site scripting from accessing these cookies. ```php - - Cookie::set('cookie-name', 'chocolate-chip', $expiry = 30, $path = null, $domain = null, $secure = true, - $httpOnly = false - ); + + Cookie::set('cookie-name', 'chocolate-chip', $expiry = 30, $path = null, $domain = null, $secure = true, + $httpOnly = false + ); ``` ## Security Headers @@ -729,27 +729,27 @@ unauthorised local persons. SilverStripe adds the current date for every request headers to the request for our secure controllers: ```php - use SilverStripe\Control\HTTP; - use SilverStripe\Control\Controller; + use SilverStripe\Control\HTTP; + use SilverStripe\Control\Controller; - class MySecureController extends Controller - { - - public function init() - { - parent::init(); - - // Add cache headers to ensure sensitive content isn't cached. - $this->response->addHeader('Cache-Control', 'max-age=0, must-revalidate, no-transform'); - $this->response->addHeader('Pragma', 'no-cache'); // for HTTP 1.0 support + class MySecureController extends Controller + { + + public function init() + { + parent::init(); + + // Add cache headers to ensure sensitive content isn't cached. + $this->response->addHeader('Cache-Control', 'max-age=0, must-revalidate, no-transform'); + $this->response->addHeader('Pragma', 'no-cache'); // for HTTP 1.0 support - HTTP::set_cache_age(0); - HTTP::add_cache_headers($this->response); - - // Add HSTS header to force TLS for document content - $this->response->addHeader('Strict-Transport-Security', 'max-age=86400; includeSubDomains'); - } - } + HTTP::set_cache_age(0); + HTTP::add_cache_headers($this->response); + + // Add HSTS header to force TLS for document content + $this->response->addHeader('Strict-Transport-Security', 'max-age=86400; includeSubDomains'); + } + } ``` ## Related diff --git a/docs/en/02_Developer_Guides/10_Email/index.md b/docs/en/02_Developer_Guides/10_Email/index.md index ffb90e3ba..3a487030a 100644 --- a/docs/en/02_Developer_Guides/10_Email/index.md +++ b/docs/en/02_Developer_Guides/10_Email/index.md @@ -24,8 +24,8 @@ SilverStripe\Core\Injector\Injector: ```php - $email = new Email($from, $to, $subject, $body); - $email->sendPlain(); + $email = new Email($from, $to, $subject, $body); + $email->sendPlain(); ``` ### Sending combined HTML and plain text @@ -36,8 +36,8 @@ to `*text*`). ```php - $email = new Email($from, $to, $subject, $body); - $email->send(); + $email = new Email($from, $to, $subject, $body); + $email->send(); ```
      @@ -57,8 +57,8 @@ email object additional information using the `setData` and `addData` methods. ```ss -

      Hi $Member.FirstName

      -

      You can go to $Link.

      +

      Hi $Member.FirstName

      +

      You can go to $Link.

      ``` The PHP Logic.. @@ -108,8 +108,8 @@ You can set the default sender address of emails through the `Email.admin_email` ```yaml - SilverStripe\Control\Email\Email: - admin_email: support@silverstripe.org + SilverStripe\Control\Email\Email: + admin_email: support@silverstripe.org ``` @@ -135,11 +135,11 @@ Configuration of those properties looks like the following: ```php - if(Director::isLive()) { - Config::inst()->update('Email', 'bcc_all_emails_to', "client@example.com"); - } else { - Config::inst()->update('Email', 'send_all_emails_to', "developer@example.com"); - } + if(Director::isLive()) { + Config::inst()->update('Email', 'bcc_all_emails_to', "client@example.com"); + } else { + Config::inst()->update('Email', 'send_all_emails_to', "developer@example.com"); + } ``` ### Setting custom "Reply To" email address. @@ -149,8 +149,8 @@ email, do the following. This is encouraged especially when the domain responsib necessarily the same which should be used for return correspondence and should help prevent your message from being marked as spam. ```php - $email = new Email(..); - $email->setReplyTo('me@address.com'); + $email = new Email(..); + $email->setReplyTo('me@address.com'); ``` ### Setting Custom Headers @@ -160,9 +160,9 @@ For email headers which do not have getters or setters (like setTo(), setFrom()) ```php - $email = new Email(...); - $email->getSwiftMessage()->getHeaders()->addTextHeader('HeaderName', 'HeaderValue'); - .. + $email = new Email(...); + $email->getSwiftMessage()->getHeaders()->addTextHeader('HeaderName', 'HeaderValue'); + .. ```
      diff --git a/docs/en/02_Developer_Guides/11_Integration/00_CSV_Import.md b/docs/en/02_Developer_Guides/11_Integration/00_CSV_Import.md index a3489d674..b2c28b0ad 100644 --- a/docs/en/02_Developer_Guides/11_Integration/00_CSV_Import.md +++ b/docs/en/02_Developer_Guides/11_Integration/00_CSV_Import.md @@ -28,16 +28,16 @@ You can use the CsvBulkLoader without subclassing or other customizations, if th in your CSV file match `$db` properties in your dataobject. E.g. a simple import for the [Member](api:SilverStripe\Security\Member) class could have this data in a file: ``` - FirstName,LastName,Email - Donald,Duck,donald@disney.com - Daisy,Duck,daisy@disney.com + FirstName,LastName,Email + Donald,Duck,donald@disney.com + Daisy,Duck,daisy@disney.com ``` The loader would be triggered through the `load()` method: ```php - $loader = new CsvBulkLoader('Member'); - $result = $loader->load(''); + $loader = new CsvBulkLoader('Member'); + $result = $loader->load(''); ``` By the way, you can import [Member](api:SilverStripe\Security\Member) and [Group](api:SilverStripe\Security\Group) data through `http://localhost/admin/security` @@ -49,19 +49,19 @@ The simplest way to use [CsvBulkLoader](api:SilverStripe\Dev\CsvBulkLoader) is t ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class PlayerAdmin extends ModelAdmin - { - private static $managed_models = [ - 'Player' - ]; - private static $model_importers = [ - 'Player' => 'CsvBulkLoader', - ]; - private static $url_segment = 'players'; - } - ?> + class PlayerAdmin extends ModelAdmin + { + private static $managed_models = [ + 'Player' + ]; + private static $model_importers = [ + 'Player' => 'CsvBulkLoader', + ]; + private static $url_segment = 'players'; + } + ?> ``` @@ -77,56 +77,56 @@ You'll need to add a route to your controller to make it accessible via URL ```php - use SilverStripe\Forms\Form; - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\FileField; - use SilverStripe\Forms\FormAction; - use SilverStripe\Forms\RequiredFields; - use SilverStripe\Dev\CsvBulkLoader; - use SilverStripe\Control\Controller; + use SilverStripe\Forms\Form; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\FileField; + use SilverStripe\Forms\FormAction; + use SilverStripe\Forms\RequiredFields; + use SilverStripe\Dev\CsvBulkLoader; + use SilverStripe\Control\Controller; - class MyController extends Controller - { + class MyController extends Controller + { - private static $allowed_actions = ['Form']; + private static $allowed_actions = ['Form']; - protected $template = "BlankPage"; + protected $template = "BlankPage"; - public function Link($action = null) - { - return Controller::join_links('MyController', $action); - } + public function Link($action = null) + { + return Controller::join_links('MyController', $action); + } - public function Form() - { - $form = new Form( - $this, - 'Form', - new FieldList( - new FileField('CsvFile', false) - ), - new FieldList( - new FormAction('doUpload', 'Upload') - ), - new RequiredFields() - ); - return $form; - } + public function Form() + { + $form = new Form( + $this, + 'Form', + new FieldList( + new FileField('CsvFile', false) + ), + new FieldList( + new FormAction('doUpload', 'Upload') + ), + new RequiredFields() + ); + return $form; + } - public function doUpload($data, $form) - { - $loader = new CsvBulkLoader('MyDataObject'); - $results = $loader->load($_FILES['CsvFile']['tmp_name']); - $messages = []; - if($results->CreatedCount()) $messages[] = sprintf('Imported %d items', $results->CreatedCount()); - if($results->UpdatedCount()) $messages[] = sprintf('Updated %d items', $results->UpdatedCount()); - if($results->DeletedCount()) $messages[] = sprintf('Deleted %d items', $results->DeletedCount()); - if(!$messages) $messages[] = 'No changes'; - $form->sessionMessage(implode(', ', $messages), 'good'); + public function doUpload($data, $form) + { + $loader = new CsvBulkLoader('MyDataObject'); + $results = $loader->load($_FILES['CsvFile']['tmp_name']); + $messages = []; + if($results->CreatedCount()) $messages[] = sprintf('Imported %d items', $results->CreatedCount()); + if($results->UpdatedCount()) $messages[] = sprintf('Updated %d items', $results->UpdatedCount()); + if($results->DeletedCount()) $messages[] = sprintf('Deleted %d items', $results->DeletedCount()); + if(!$messages) $messages[] = 'No changes'; + $form->sessionMessage(implode(', ', $messages), 'good'); - return $this->redirectBack(); - } - } + return $this->redirectBack(); + } + } ``` @@ -139,31 +139,31 @@ We're going to use our knowledge from the previous example to import a more soph Sample CSV Content ``` - "Number","Name","Birthday","Team" - 11,"John Doe",1982-05-12,"FC Bayern" - 12,"Jane Johnson", 1982-05-12,"FC Bayern" - 13,"Jimmy Dole",,"Schalke 04" + "Number","Name","Birthday","Team" + 11,"John Doe",1982-05-12,"FC Bayern" + 12,"Jane Johnson", 1982-05-12,"FC Bayern" + 13,"Jimmy Dole",,"Schalke 04" ``` Datamodel for Player ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { - private static $db = [ - 'PlayerNumber' => 'Int', - 'FirstName' => 'Text', - 'LastName' => 'Text', - 'Birthday' => 'Date', - ]; - private static $has_one = [ - 'Team' => 'FootballTeam' - ]; - } - ?> + class Player extends DataObject + { + private static $db = [ + 'PlayerNumber' => 'Int', + 'FirstName' => 'Text', + 'LastName' => 'Text', + 'Birthday' => 'Date', + ]; + private static $has_one = [ + 'Team' => 'FootballTeam' + ]; + } + ?> ``` @@ -171,18 +171,18 @@ Datamodel for FootballTeam: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class FootballTeam extends DataObject - { - private static $db = [ - 'Title' => 'Text', - ]; - private static $has_many = [ - 'Players' => 'Player' - ]; - } - ?> + class FootballTeam extends DataObject + { + private static $db = [ + 'Title' => 'Text', + ]; + private static $has_many = [ + 'Players' => 'Player' + ]; + } + ?> ``` @@ -193,38 +193,38 @@ Sample implementation of a custom loader. Assumes a CSV-file in a certain format * Avoids duplicate imports by a custom `$duplicateChecks` definition * Creates `Team` relations automatically based on the `Gruppe` column in the CSV data ```php - use SilverStripe\Dev\CsvBulkLoader; + use SilverStripe\Dev\CsvBulkLoader; - class PlayerCsvBulkLoader extends CsvBulkLoader - { - public $columnMap = [ - 'Number' => 'PlayerNumber', - 'Name' => '->importFirstAndLastName', - 'Birthday' => 'Birthday', - 'Team' => 'Team.Title', - ]; - public $duplicateChecks = [ - 'Number' => 'PlayerNumber' - ]; - public $relationCallbacks = [ - 'Team.Title' => [ - 'relationname' => 'Team', - 'callback' => 'getTeamByTitle' - ] - ]; - public static function importFirstAndLastName(&$obj, $val, $record) - { - $parts = explode(' ', $val); - if(count($parts) != 2) return false; - $obj->FirstName = $parts[0]; - $obj->LastName = $parts[1]; - } - public static function getTeamByTitle(&$obj, $val, $record) - { - return FootballTeam::get()->filter('Title', $val)->First(); - } - } - ?> + class PlayerCsvBulkLoader extends CsvBulkLoader + { + public $columnMap = [ + 'Number' => 'PlayerNumber', + 'Name' => '->importFirstAndLastName', + 'Birthday' => 'Birthday', + 'Team' => 'Team.Title', + ]; + public $duplicateChecks = [ + 'Number' => 'PlayerNumber' + ]; + public $relationCallbacks = [ + 'Team.Title' => [ + 'relationname' => 'Team', + 'callback' => 'getTeamByTitle' + ] + ]; + public static function importFirstAndLastName(&$obj, $val, $record) + { + $parts = explode(' ', $val); + if(count($parts) != 2) return false; + $obj->FirstName = $parts[0]; + $obj->LastName = $parts[1]; + } + public static function getTeamByTitle(&$obj, $val, $record) + { + return FootballTeam::get()->filter('Title', $val)->First(); + } + } + ?> ``` @@ -232,19 +232,19 @@ Building off of the ModelAdmin example up top, use a custom loader instead of th ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class PlayerAdmin extends ModelAdmin - { - private static $managed_models = [ - 'Player' - ]; - private static $model_importers = [ - 'Player' => 'PlayerCsvBulkLoader', - ]; - private static $url_segment = 'players'; - } - ?> + class PlayerAdmin extends ModelAdmin + { + private static $managed_models = [ + 'Player' + ]; + private static $model_importers = [ + 'Player' => 'PlayerCsvBulkLoader', + ]; + private static $url_segment = 'players'; + } + ?> ``` diff --git a/docs/en/02_Developer_Guides/11_Integration/02_RSSFeed.md b/docs/en/02_Developer_Guides/11_Integration/02_RSSFeed.md index e2a59ab88..732cdc742 100644 --- a/docs/en/02_Developer_Guides/11_Integration/02_RSSFeed.md +++ b/docs/en/02_Developer_Guides/11_Integration/02_RSSFeed.md @@ -24,25 +24,25 @@ An outline of step one looks like: ```php - $feed = new RSSFeed( - $list, - $link, - $title, - $description, - $titleField, - $descriptionField, - $authorField, - $lastModifiedTime, - $etag - ); + $feed = new RSSFeed( + $list, + $link, + $title, + $description, + $titleField, + $descriptionField, + $authorField, + $lastModifiedTime, + $etag + ); - $feed->outputToBrowser(); + $feed->outputToBrowser(); ``` To achieve step two include the following code where ever you want to include the `` tag to the RSS Feed. This will normally go in your `Controllers` `init` method. ```php - RSSFeed::linkToFeed($link, $title); + RSSFeed::linkToFeed($link, $title); ``` ## Examples @@ -56,43 +56,43 @@ You can use [RSSFeed](api:SilverStripe\Control\RSS\RSSFeed) to easily create a f ```php - use SilverStripe\Control\RSS\RSSFeed; - use Page; - use SilverStripe\CMS\Controllers\ContentController; + use SilverStripe\Control\RSS\RSSFeed; + use Page; + use SilverStripe\CMS\Controllers\ContentController; - - .. - class PageController extends ContentController - { + + .. + class PageController extends ContentController + { - private static $allowed_actions = [ - 'rss' - ]; + private static $allowed_actions = [ + 'rss' + ]; - public function init() - { - parent::init(); + public function init() + { + parent::init(); - RSSFeed::linkToFeed($this->Link() . "rss", "10 Most Recently Updated Pages"); - } + RSSFeed::linkToFeed($this->Link() . "rss", "10 Most Recently Updated Pages"); + } - public function rss() - { - $rss = new RSSFeed( - $this->LatestUpdates(), - $this->Link(), - "10 Most Recently Updated Pages", - "Shows a list of the 10 most recently updated pages." - ); + public function rss() + { + $rss = new RSSFeed( + $this->LatestUpdates(), + $this->Link(), + "10 Most Recently Updated Pages", + "Shows a list of the 10 most recently updated pages." + ); - return $rss->outputToBrowser(); - } + return $rss->outputToBrowser(); + } - public function LatestUpdates() - { - return Page::get()->sort("LastEdited", "DESC")->limit(10); - } - } + public function LatestUpdates() + { + return Page::get()->sort("LastEdited", "DESC")->limit(10); + } + } ``` @@ -110,58 +110,58 @@ method is defined and returns a string to the full website URL. ```php - use SilverStripe\Control\Controller; - use SilverStripe\Control\Director; - use SilverStripe\ORM\DataObject; + use SilverStripe\Control\Controller; + use SilverStripe\Control\Director; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { + class Player extends DataObject + { - public function AbsoluteLink() - { - // assumes players can be accessed at yoursite.com/players/2 + public function AbsoluteLink() + { + // assumes players can be accessed at yoursite.com/players/2 - return Controller::join_links( - Director::absoluteBaseUrl(), - 'players', - $this->ID - ); - } - } + return Controller::join_links( + Director::absoluteBaseUrl(), + 'players', + $this->ID + ); + } + } ``` Then in our controller, we add a new action which returns a the XML list of `Players`. ```php - use SilverStripe\Control\RSS\RSSFeed; - use SilverStripe\CMS\Controllers\ContentController; + use SilverStripe\Control\RSS\RSSFeed; + use SilverStripe\CMS\Controllers\ContentController; - class PageController extends ContentController - { + class PageController extends ContentController + { - private static $allowed_actions = [ - 'players' - ]; + private static $allowed_actions = [ + 'players' + ]; - public function init() - { - parent::init(); + public function init() + { + parent::init(); - RSSFeed::linkToFeed($this->Link("players"), "Players"); - } + RSSFeed::linkToFeed($this->Link("players"), "Players"); + } - public function players() - { - $rss = new RSSFeed( - Player::get(), - $this->Link("players"), - "Players" - ); + public function players() + { + $rss = new RSSFeed( + Player::get(), + $this->Link("players"), + "Players" + ); - return $rss->outputToBrowser(); - } - } + return $rss->outputToBrowser(); + } + } ``` @@ -177,22 +177,22 @@ Say from that last example we want to include the Players Team in the XML feed w ```xml - - - - $Title - $Link - - $Description.XML + + + + $Title + $Link + + $Description.XML - <% loop $Entries %> - - $Title.XML - $Team.Title - - <% end_loop %> - - + <% loop $Entries %> + + $Title.XML + $Team.Title + + <% end_loop %> + + ``` `setTemplate` can then be used to tell RSSFeed to use that new template. @@ -201,18 +201,18 @@ Say from that last example we want to include the Players Team in the XML feed w ```php - public function players() - { - $rss = new RSSFeed( - Player::get(), - $this->Link("players"), - "Players" - ); - - $rss->setTemplate('PlayersRss'); + public function players() + { + $rss = new RSSFeed( + Player::get(), + $this->Link("players"), + "Players" + ); + + $rss->setTemplate('PlayersRss'); - return $rss->outputToBrowser(); - } + return $rss->outputToBrowser(); + } ```
      diff --git a/docs/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md b/docs/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md index 63db982d7..3e123d71d 100644 --- a/docs/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md +++ b/docs/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md @@ -8,71 +8,71 @@ form (which is used for `MyDataObject` instances). You can access it through ```php - use SilverStripe\Forms\Form; - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\FileField; - use SilverStripe\Forms\FormAction; - use SilverStripe\Forms\RequiredFields; - use SilverStripe\Dev\CsvBulkLoader; - use SilverStripe\Control\Controller; + use SilverStripe\Forms\Form; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\FileField; + use SilverStripe\Forms\FormAction; + use SilverStripe\Forms\RequiredFields; + use SilverStripe\Dev\CsvBulkLoader; + use SilverStripe\Control\Controller; - class MyController extends Controller - { + class MyController extends Controller + { - private static $allowed_actions = [ - 'Form' - ]; + private static $allowed_actions = [ + 'Form' + ]; - protected $template = "BlankPage"; + protected $template = "BlankPage"; - public function Link($action = null) - { - return Controller::join_links('MyController', $action); - } + public function Link($action = null) + { + return Controller::join_links('MyController', $action); + } - public function Form() - { - $form = new Form( - $this, - 'Form', - new FieldList( - new FileField('CsvFile', false) - ), - new FieldList( - new FormAction('doUpload', 'Upload') - ), - new RequiredFields() - ); - return $form; - } + public function Form() + { + $form = new Form( + $this, + 'Form', + new FieldList( + new FileField('CsvFile', false) + ), + new FieldList( + new FormAction('doUpload', 'Upload') + ), + new RequiredFields() + ); + return $form; + } - public function doUpload($data, $form) - { - $loader = new CsvBulkLoader('MyDataObject'); - $results = $loader->load($_FILES['CsvFile']['tmp_name']); - $messages = []; + public function doUpload($data, $form) + { + $loader = new CsvBulkLoader('MyDataObject'); + $results = $loader->load($_FILES['CsvFile']['tmp_name']); + $messages = []; - if($results->CreatedCount()) { - $messages[] = sprintf('Imported %d items', $results->CreatedCount()); - } + if($results->CreatedCount()) { + $messages[] = sprintf('Imported %d items', $results->CreatedCount()); + } - if($results->UpdatedCount()) { - $messages[] = sprintf('Updated %d items', $results->UpdatedCount()); - } + if($results->UpdatedCount()) { + $messages[] = sprintf('Updated %d items', $results->UpdatedCount()); + } - if($results->DeletedCount()) { - $messages[] = sprintf('Deleted %d items', $results->DeletedCount()); - } + if($results->DeletedCount()) { + $messages[] = sprintf('Deleted %d items', $results->DeletedCount()); + } - if(!$messages) { - $messages[] = 'No changes'; - } + if(!$messages) { + $messages[] = 'No changes'; + } - $form->sessionMessage(implode(', ', $messages), 'good'); + $form->sessionMessage(implode(', ', $messages), 'good'); - return $this->redirectBack(); - } - } + return $this->redirectBack(); + } + } ``` diff --git a/docs/en/02_Developer_Guides/11_Integration/How_Tos/custom_csvbulkloader.md b/docs/en/02_Developer_Guides/11_Integration/How_Tos/custom_csvbulkloader.md index c43940b7b..fffe5a3ed 100644 --- a/docs/en/02_Developer_Guides/11_Integration/How_Tos/custom_csvbulkloader.md +++ b/docs/en/02_Developer_Guides/11_Integration/How_Tos/custom_csvbulkloader.md @@ -5,10 +5,10 @@ title: A custom CSVBulkLoader instance A an implementation of a custom `CSVBulkLoader` loader. In this example. we're provided with a unique CSV file containing a list of football players and the team they play for. The file we have is in the format like below. ``` - "SpielerNummer", "Name", "Geburtsdatum", "Gruppe" - 11, "John Doe", 1982-05-12,"FC Bayern" - 12, "Jane Johnson", 1982-05-12,"FC Bayern" - 13, "Jimmy Dole",,"Schalke 04" + "SpielerNummer", "Name", "Geburtsdatum", "Gruppe" + 11, "John Doe", 1982-05-12,"FC Bayern" + 12, "Jane Johnson", 1982-05-12,"FC Bayern" + 13, "Jimmy Dole",,"Schalke 04" ``` This data needs to be imported into our application. For this, we have two `DataObjects` setup. `Player` contains information about the individual player and a relation set up for managing the `Team`. @@ -17,22 +17,22 @@ information about the individual player and a relation set up for managing the ` ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Player extends DataObject - { - - private static $db = [ - 'PlayerNumber' => 'Int', - 'FirstName' => 'Text', - 'LastName' => 'Text', - 'Birthday' => 'Date' - ]; - - private static $has_one = [ - 'Team' => 'FootballTeam' - ]; - } + class Player extends DataObject + { + + private static $db = [ + 'PlayerNumber' => 'Int', + 'FirstName' => 'Text', + 'LastName' => 'Text', + 'Birthday' => 'Date' + ]; + + private static $has_one = [ + 'Team' => 'FootballTeam' + ]; + } ``` @@ -40,19 +40,19 @@ information about the individual player and a relation set up for managing the ` ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class FootballTeam extends DataObject - { - - private static $db = [ - 'Title' => 'Text' - ]; + class FootballTeam extends DataObject + { + + private static $db = [ + 'Title' => 'Text' + ]; - private static $has_many = [ - 'Players' => 'Player' - ]; - } + private static $has_many = [ + 'Players' => 'Player' + ]; + } ``` @@ -72,42 +72,42 @@ Our final import looks like this. ```php - use SilverStripe\Dev\CsvBulkLoader; + use SilverStripe\Dev\CsvBulkLoader; - class PlayerCsvBulkLoader extends CsvBulkLoader - { + class PlayerCsvBulkLoader extends CsvBulkLoader + { - public $columnMap = [ - 'Number' => 'PlayerNumber', - 'Name' => '->importFirstAndLastName', - 'Geburtsdatum' => 'Birthday', - 'Gruppe' => 'Team.Title', - ]; + public $columnMap = [ + 'Number' => 'PlayerNumber', + 'Name' => '->importFirstAndLastName', + 'Geburtsdatum' => 'Birthday', + 'Gruppe' => 'Team.Title', + ]; - public $duplicateChecks = [ - 'SpielerNummer' => 'PlayerNumber' - ]; + public $duplicateChecks = [ + 'SpielerNummer' => 'PlayerNumber' + ]; - public $relationCallbacks = [ - 'Team.Title' => [ - 'relationname' => 'Team', - 'callback' => 'getTeamByTitle' - ] - ]; + public $relationCallbacks = [ + 'Team.Title' => [ + 'relationname' => 'Team', + 'callback' => 'getTeamByTitle' + ] + ]; - public static function importFirstAndLastName(&$obj, $val, $record) - { - $parts = explode(' ', $val); - if(count($parts) != 2) return false; - $obj->FirstName = $parts[0]; - $obj->LastName = $parts[1]; - } + public static function importFirstAndLastName(&$obj, $val, $record) + { + $parts = explode(' ', $val); + if(count($parts) != 2) return false; + $obj->FirstName = $parts[0]; + $obj->LastName = $parts[1]; + } - public static function getTeamByTitle(&$obj, $val, $record) - { - return FootballTeam::get()->filter('Title', $val)->First(); - } - } + public static function getTeamByTitle(&$obj, $val, $record) + { + return FootballTeam::get()->filter('Title', $val)->First(); + } + } ``` diff --git a/docs/en/02_Developer_Guides/11_Integration/How_Tos/embed_rss.md b/docs/en/02_Developer_Guides/11_Integration/How_Tos/embed_rss.md index 4dee06f42..2acd56b42 100644 --- a/docs/en/02_Developer_Guides/11_Integration/How_Tos/embed_rss.md +++ b/docs/en/02_Developer_Guides/11_Integration/How_Tos/embed_rss.md @@ -11,35 +11,35 @@ First, we write the code to query the API feed. ```php - public function getWellingtonWeather() - { - $fetch = new RestfulService( - 'https://query.yahooapis.com/v1/public/yql' - ); - - $fetch->setQueryString([ - 'q' => 'select * from weather.forecast where woeid in (select woeid from geo.places(1) where text="Wellington, NZ")' - ]); - - // perform the query - $conn = $fetch->request(); + public function getWellingtonWeather() + { + $fetch = new RestfulService( + 'https://query.yahooapis.com/v1/public/yql' + ); + + $fetch->setQueryString([ + 'q' => 'select * from weather.forecast where woeid in (select woeid from geo.places(1) where text="Wellington, NZ")' + ]); + + // perform the query + $conn = $fetch->request(); - // parse the XML body - $msgs = $fetch->getValues($conn->getBody(), "results"); + // parse the XML body + $msgs = $fetch->getValues($conn->getBody(), "results"); - // generate an object our templates can read - $output = new ArrayList(); + // generate an object our templates can read + $output = new ArrayList(); - if($msgs) { - foreach($msgs as $msg) { - $output->push(new ArrayData([ - 'Description' => Convert::xml2raw($msg->channel_item_description) - ])); - } - } + if($msgs) { + foreach($msgs as $msg) { + $output->push(new ArrayData([ + 'Description' => Convert::xml2raw($msg->channel_item_description) + ])); + } + } - return $output; - } + return $output; + } ``` @@ -51,11 +51,11 @@ single field `Description`. ```ss - <% if WellingtonWeather %> - <% loop WellingtonWeather %> - $Description - <% end_loop %> - <% end_if %> + <% if WellingtonWeather %> + <% loop WellingtonWeather %> + $Description + <% end_loop %> + <% end_if %> ``` ## Related diff --git a/docs/en/02_Developer_Guides/12_Search/01_Searchcontext.md b/docs/en/02_Developer_Guides/12_Search/01_Searchcontext.md index ae1bec24e..4c9923c86 100644 --- a/docs/en/02_Developer_Guides/12_Search/01_Searchcontext.md +++ b/docs/en/02_Developer_Guides/12_Search/01_Searchcontext.md @@ -20,16 +20,16 @@ Defining search-able fields on your DataObject. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { + class MyDataObject extends DataObject + { - private static $searchable_fields = [ - 'Name', - 'ProductCode' - ]; - } + private static $searchable_fields = [ + 'Name', + 'ProductCode' + ]; + } ``` @@ -41,38 +41,38 @@ and `MyDate`. The attribute `HiddenProperty` should not be searchable, and `MyDa ```php - use SilverStripe\ORM\Filters\PartialMatchFilter; - use SilverStripe\ORM\Filters\GreaterThanFilter; - use SilverStripe\ORM\Search\SearchContext; - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\Filters\PartialMatchFilter; + use SilverStripe\ORM\Filters\GreaterThanFilter; + use SilverStripe\ORM\Search\SearchContext; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { + class MyDataObject extends DataObject + { - private static $db = [ - 'PublicProperty' => 'Text' - 'HiddenProperty' => 'Text', - 'MyDate' => 'Date' - ]; - - public function getDefaultSearchContext() - { - $fields = $this->scaffoldSearchFields([ - 'restrictFields' => ['PublicProperty','MyDate'] - ]); + private static $db = [ + 'PublicProperty' => 'Text' + 'HiddenProperty' => 'Text', + 'MyDate' => 'Date' + ]; + + public function getDefaultSearchContext() + { + $fields = $this->scaffoldSearchFields([ + 'restrictFields' => ['PublicProperty','MyDate'] + ]); - $filters = [ - 'PublicProperty' => new PartialMatchFilter('PublicProperty'), - 'MyDate' => new GreaterThanFilter('MyDate') - ]; + $filters = [ + 'PublicProperty' => new PartialMatchFilter('PublicProperty'), + 'MyDate' => new GreaterThanFilter('MyDate') + ]; - return new SearchContext( - $this->class, - $fields, - $filters - ); - } - } + return new SearchContext( + $this->class, + $fields, + $filters + ); + } + } ``` @@ -90,41 +90,41 @@ the `$fields` constructor parameter. ```php - use SilverStripe\Forms\Form; - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\FormAction; - use SilverStripe\CMS\Controllers\ContentController; + use SilverStripe\Forms\Form; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\FormAction; + use SilverStripe\CMS\Controllers\ContentController; - - // .. - class PageController extends ContentController - { + + // .. + class PageController extends ContentController + { - public function SearchForm() - { - $context = singleton('MyDataObject')->getCustomSearchContext(); - $fields = $context->getSearchFields(); + public function SearchForm() + { + $context = singleton('MyDataObject')->getCustomSearchContext(); + $fields = $context->getSearchFields(); - $form = new Form($this, "SearchForm", - $fields, - new FieldList( - new FormAction('doSearch') - ) - ); + $form = new Form($this, "SearchForm", + $fields, + new FieldList( + new FormAction('doSearch') + ) + ); - return $form; - } + return $form; + } - public function doSearch($data, $form) - { - $context = singleton('MyDataObject')->getCustomSearchContext(); - $results = $context->getResults($data); + public function doSearch($data, $form) + { + $context = singleton('MyDataObject')->getCustomSearchContext(); + $results = $context->getResults($data); - return $this->customise([ - 'Results' => $results - ])->renderWith('Page_results'); - } - } + return $this->customise([ + 'Results' => $results + ])->renderWith('Page_results'); + } + } ``` @@ -137,24 +137,24 @@ in order to read page limit information. It is also passed the current ```php - public function getResults($searchCriteria = []) - { - $start = ($this->getRequest()->getVar('start')) ? (int)$this->getRequest()->getVar('start') : 0; - $limit = 10; - - $context = singleton('MyDataObject')->getCustomSearchContext(); - $query = $context->getQuery($searchCriteria, null, ['start'=>$start,'limit'=>$limit]); - $records = $context->getResults($searchCriteria, null, ['start'=>$start,'limit'=>$limit]); - - if($records) { - $records = new PaginatedList($records, $this->getRequest()); - $records->setPageStart($start); - $records->setPageLength($limit); - $records->setTotalItems($query->unlimitedRowCount()); - } - - return $records; - } + public function getResults($searchCriteria = []) + { + $start = ($this->getRequest()->getVar('start')) ? (int)$this->getRequest()->getVar('start') : 0; + $limit = 10; + + $context = singleton('MyDataObject')->getCustomSearchContext(); + $query = $context->getQuery($searchCriteria, null, ['start'=>$start,'limit'=>$limit]); + $records = $context->getResults($searchCriteria, null, ['start'=>$start,'limit'=>$limit]); + + if($records) { + $records = new PaginatedList($records, $this->getRequest()); + $records->setPageStart($start); + $records->setPageLength($limit); + $records->setTotalItems($query->unlimitedRowCount()); + } + + return $records; + } ``` @@ -162,14 +162,14 @@ notice that if you want to use this getResults function, you need to change the ```php - public function doSearch($data, $form) - { - $context = singleton('MyDataObject')->getCustomSearchContext(); - $results = $this->getResults($data); - return $this->customise([ - 'Results' => $results - ])->renderWith(['Catalogo_results', 'Page']); - } + public function doSearch($data, $form) + { + $context = singleton('MyDataObject')->getCustomSearchContext(); + $results = $this->getResults($data); + return $this->customise([ + 'Results' => $results + ])->renderWith(['Catalogo_results', 'Page']); + } ``` @@ -189,43 +189,43 @@ Results.PaginationSummary(4) defines how many pages the search will show in the **Next 1 2 *3* 4 5 … 558** ```ss - <% if $Results %> -
        - <% loop $Results %> -
      • $Title, $Autor
        • - <% end_loop %> -
      - <% else %> -

      Sorry, your search query did not return any results.

      - <% end_if %> - - <% if $Results.MoreThanOnePage %> -
      -

      - <% if $Results.NotFirstPage %> - - <% end_if %> - - - <% loop $Results.PaginationSummary(4) %> - <% if $CurrentBool %> - $PageNum - <% else %> - <% if $Link %> - $PageNum - <% else %> - … - <% end_if %> - <% end_if %> - <% end_loop %> - - - <% if $Results.NotLastPage %> - - <% end_if %> -

      -
      - <% end_if %> + <% if $Results %> +
        + <% loop $Results %> +
      • $Title, $Autor
        • + <% end_loop %> +
      + <% else %> +

      Sorry, your search query did not return any results.

      + <% end_if %> + + <% if $Results.MoreThanOnePage %> +
      +

      + <% if $Results.NotFirstPage %> + + <% end_if %> + + + <% loop $Results.PaginationSummary(4) %> + <% if $CurrentBool %> + $PageNum + <% else %> + <% if $Link %> + $PageNum + <% else %> + … + <% end_if %> + <% end_if %> + <% end_loop %> + + + <% if $Results.NotLastPage %> + + <% end_if %> +

      +
      + <% end_if %> ``` ## Available SearchFilters diff --git a/docs/en/02_Developer_Guides/12_Search/02_FulltextSearch.md b/docs/en/02_Developer_Guides/12_Search/02_FulltextSearch.md index cfc31d2b8..f400ed7d8 100644 --- a/docs/en/02_Developer_Guides/12_Search/02_FulltextSearch.md +++ b/docs/en/02_Developer_Guides/12_Search/02_FulltextSearch.md @@ -23,15 +23,15 @@ You can do so by adding this static variable to your class definition: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class MyDataObject extends DataObject - { + class MyDataObject extends DataObject + { - private static $create_table_options = [ - 'MySQLDatabase' => 'ENGINE=MyISAM' - ]; - } + private static $create_table_options = [ + 'MySQLDatabase' => 'ENGINE=MyISAM' + ]; + } ``` @@ -52,28 +52,28 @@ Example DataObject: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class SearchableDataObject extends DataObject - { - - private static $db = [ - "Title" => "Varchar(255)", - "Content" => "HTMLText", - ]; + class SearchableDataObject extends DataObject + { + + private static $db = [ + "Title" => "Varchar(255)", + "Content" => "HTMLText", + ]; - private static $indexes = [ - 'SearchFields' => [ - 'type' => 'fulltext', - 'columns' => ['Title', 'Content'], - ] - ]; + private static $indexes = [ + 'SearchFields' => [ + 'type' => 'fulltext', + 'columns' => ['Title', 'Content'], + ] + ]; - private static $create_table_options = [ - 'MySQLDatabase' => 'ENGINE=MyISAM' - ]; + private static $create_table_options = [ + 'MySQLDatabase' => 'ENGINE=MyISAM' + ]; - } + } ``` @@ -81,7 +81,7 @@ Performing the search: ```php - SearchableDataObject::get()->filter('SearchFields:Fulltext', 'search term'); + SearchableDataObject::get()->filter('SearchFields:Fulltext', 'search term'); ``` If your search index is a single field size, then you may also specify the search filter by the name of the diff --git a/docs/en/02_Developer_Guides/13_i18n/index.md b/docs/en/02_Developer_Guides/13_i18n/index.md index 3622c4ff0..075add26c 100644 --- a/docs/en/02_Developer_Guides/13_i18n/index.md +++ b/docs/en/02_Developer_Guides/13_i18n/index.md @@ -29,9 +29,9 @@ you want to set. ```php - // mysite/_config.php - i18n::set_locale('de_DE'); // Setting the locale to German (Germany) - i18n::set_locale('ca_AD'); // Setting to Catalan (Andorra) + // mysite/_config.php + i18n::set_locale('de_DE'); // Setting the locale to German (Germany) + i18n::set_locale('ca_AD'); // Setting to Catalan (Andorra) ``` Once we set a locale, all the calls to the translator function will return strings according to the set locale value, if @@ -55,11 +55,11 @@ To let browsers know which language they're displaying a document in, you can de ```html - //'Page.ss' (HTML) - + //'Page.ss' (HTML) + - //'Page.ss' (XHTML) - + //'Page.ss' (XHTML) + ``` Setting the `` attribute is the most commonly used technique. There are other ways to specify content languages @@ -72,7 +72,7 @@ and default alignment of paragraphs and tables to browsers. ```html - + ``` ### Date and time formats @@ -82,8 +82,8 @@ You can use these settings for your own view logic. ```php - Config::inst()->update('i18n', 'date_format', 'dd.MM.yyyy'); - Config::inst()->update('i18n', 'time_format', 'HH:mm'); + Config::inst()->update('i18n', 'date_format', 'dd.MM.yyyy'); + Config::inst()->update('i18n', 'time_format', 'HH:mm'); ``` Localization in SilverStripe uses PHP's [intl extension](http://php.net/intl). @@ -107,11 +107,11 @@ In order to add a value, add the following to your `config.yml`: ```yml - i18n: - common_locales: - de_CGN: - name: German (Cologne) - native: Kölsch + i18n: + common_locales: + de_CGN: + name: German (Cologne) + native: Kölsch ``` Similarly, to change an existing language label, you can overwrite one of these keys: @@ -119,10 +119,10 @@ Similarly, to change an existing language label, you can overwrite one of these ```yml - i18n: - common_locales: - en_NZ: - native: Niu Zillund + i18n: + common_locales: + en_NZ: + native: Niu Zillund ``` ### i18n in URLs @@ -155,9 +155,9 @@ followed by `setLocale()` or `setDateFormat()`/`setTimeFormat()`. ```php - $field = new DateField(); - $field->setLocale('de_AT'); // set Austrian/German locale, defaulting format to dd.MM.y - $field->setDateFormat('d.M.y'); // set a more specific date format (single digit day/month) + $field = new DateField(); + $field->setLocale('de_AT'); // set Austrian/German locale, defaulting format to dd.MM.y + $field->setDateFormat('d.M.y'); // set a more specific date format (single digit day/month) ``` ## Translating text @@ -167,10 +167,10 @@ language-dependent and use a translator function call instead. ```php - // without i18n - echo "This is a string"; - // with i18n - echo _t("Namespace.Entity","This is a string"); + // without i18n + echo "This is a string"; + // with i18n + echo _t("Namespace.Entity","This is a string"); ``` All strings passed through the `_t()` function will be collected in a separate language table (see [Collecting text](#collecting-text)), which is the starting point for translations. @@ -252,17 +252,17 @@ Please ensure that any required plurals are exposed via provideI18nEntities. ```php - // Simple string translation - _t('LeftAndMain.FILESIMAGES','Files & Images'); + // Simple string translation + _t('LeftAndMain.FILESIMAGES','Files & Images'); - // Using injection to add variables into the translated strings. - _t('CMSMain.RESTORED', - "Restored {value} successfully", - ['value' => $itemRestored] - ); - - // Plurals are invoked via a `|` pipe-delimeter with a {count} argument - _t('MyObject.PLURALS', 'An object|{count} objects', [ 'count' => '$count ]); + // Using injection to add variables into the translated strings. + _t('CMSMain.RESTORED', + "Restored {value} successfully", + ['value' => $itemRestored] + ); + + // Plurals are invoked via a `|` pipe-delimeter with a {count} argument + _t('MyObject.PLURALS', 'An object|{count} objects', [ 'count' => '$count ]); ``` @@ -282,13 +282,13 @@ the PHP version of the function. ```ss - // Simple string translation - <%t Namespace.Entity "String to translate" %> + // Simple string translation + <%t Namespace.Entity "String to translate" %> - // Using injection to add variables into the translated strings (note that $Name and $Greeting must be available in the current template scope). - <%t Header.Greeting "Hello {name} {greeting}" name=$Name greeting=$Greeting %> - - // Plurals follow the same convention, required a `|` and `{count}` in the default string + // Using injection to add variables into the translated strings (note that $Name and $Greeting must be available in the current template scope). + <%t Header.Greeting "Hello {name} {greeting}" name=$Name greeting=$Greeting %> + + // Plurals follow the same convention, required a `|` and `{count}` in the default string <%t MyObject.PLURALS 'An item|{count} items' count=$Count %> ``` @@ -300,11 +300,11 @@ otherwise it won't pick up locale changes. ```ss - <% cached 'MyIdentifier', $CurrentLocale %> - <% loop $Students %> - $Name - <% end_loop %> - <% end_cached %> + <% cached 'MyIdentifier', $CurrentLocale %> + <% loop $Students %> + $Name + <% end_loop %> + <% end_cached %> ``` ## Collecting text @@ -337,15 +337,15 @@ This default order is configured in `framework/_config/i18n.yml`. This file spe To create a custom module order, you need to specify a config fragment that inserts itself either after or before those items. For example, you may have a number of modules that have to come after the framework/admin, but before anyhting else. To do that, you would use this ```yml - --- - Name: customi18n - Before: 'defaulti18n' - --- - i18n: - module_priority: - - module1 - - module2 - - module3 + --- + Name: customi18n + Before: 'defaulti18n' + --- + i18n: + module_priority: + - module1 + - module2 + - module3 ``` The config option being set is `i18n.module_priority`, and it is a list of module names. @@ -366,19 +366,19 @@ By default, SilverStripe uses a YAML format which is loaded via the Example: framework/lang/en.yml (extract) ```yml - en: - ImageUploader: - Attach: 'Attach {title}' - UploadField: - NOTEADDFILES: 'You can add files once you have saved for the first time.' + en: + ImageUploader: + Attach: 'Attach {title}' + UploadField: + NOTEADDFILES: 'You can add files once you have saved for the first time.' ``` Translation table: framework/lang/de.yml (extract) ```yml - de: - ImageUploader: - ATTACH: '{title} anhängen' - UploadField: - NOTEADDFILES: 'Sie können Dateien hinzufügen sobald Sie das erste mal gespeichert haben' + de: + ImageUploader: + ATTACH: '{title} anhängen' + UploadField: + NOTEADDFILES: 'Sie können Dateien hinzufügen sobald Sie das erste mal gespeichert haben' ``` Note that translations are cached across requests. The cache can be cleared through the `?flush=1` query parameter, @@ -400,7 +400,7 @@ Just point it to a directory instead of a file, and the class will figure out th ```php - Requirements::add_i18n_javascript('/javascript/lang'); + Requirements::add_i18n_javascript('/javascript/lang'); ``` ### Translation Tables in JavaScript @@ -413,13 +413,13 @@ Master Table (`/javascript/lang/en.js`) ```js - if(typeof(ss) == 'undefined' || typeof(ss.i18n) == 'undefined') { - console.error('Class ss.i18n not defined'); - } else { - ss.i18n.addDictionary('en', { - 'MYMODULE.MYENTITY' : "Really delete these articles?" - }); - } + if(typeof(ss) == 'undefined' || typeof(ss.i18n) == 'undefined') { + console.error('Class ss.i18n not defined'); + } else { + ss.i18n.addDictionary('en', { + 'MYMODULE.MYENTITY' : "Really delete these articles?" + }); + } ``` Example Translation Table (`/javascript/lang/de.js`) @@ -427,9 +427,9 @@ Example Translation Table (`/javascript/lang/de.js`) ```js - ss.i18n.addDictionary('de', { - 'MYMODULE.MYENTITY' : "Artikel wirklich löschen?" - }); + ss.i18n.addDictionary('de', { + 'MYMODULE.MYENTITY' : "Artikel wirklich löschen?" + }); ``` For most core modules, these files are generated by a @@ -442,7 +442,7 @@ format which can be processed more easily by external translation providers (see ```js - alert(ss.i18n._t('MYMODULE.MYENTITY')); + alert(ss.i18n._t('MYMODULE.MYENTITY')); ``` ### Advanced Use @@ -456,13 +456,13 @@ The `ss.i18n` object contain a couple functions to help and replace dynamic vari ```js - // MYMODULE.MYENTITY contains "Really delete %s articles by %s?" - alert(ss.i18n.sprintf( - ss.i18n._t('MYMODULE.MYENTITY'), - 42, - 'Douglas Adams' - )); - // Displays: "Really delete 42 articles by Douglas Adams?" + // MYMODULE.MYENTITY contains "Really delete %s articles by %s?" + alert(ss.i18n.sprintf( + ss.i18n._t('MYMODULE.MYENTITY'), + 42, + 'Douglas Adams' + )); + // Displays: "Really delete 42 articles by Douglas Adams?" ``` #### Variable injection with inject() @@ -472,12 +472,12 @@ The `ss.i18n` object contain a couple functions to help and replace dynamic vari ```js - // MYMODULE.MYENTITY contains "Really delete {count} articles by {author}?" - alert(ss.i18n.inject( - ss.i18n._t('MYMODULE.MYENTITY'), - {count: 42, author: 'Douglas Adams'} - )); - // Displays: "Really delete 42 articles by Douglas Adams?" + // MYMODULE.MYENTITY contains "Really delete {count} articles by {author}?" + alert(ss.i18n.inject( + ss.i18n._t('MYMODULE.MYENTITY'), + {count: 42, author: 'Douglas Adams'} + )); + // Displays: "Really delete 42 articles by Douglas Adams?" ``` ## Limitations diff --git a/docs/en/02_Developer_Guides/14_Files/01_File_Management.md b/docs/en/02_Developer_Guides/14_Files/01_File_Management.md index 2750d091f..2ec92a276 100644 --- a/docs/en/02_Developer_Guides/14_Files/01_File_Management.md +++ b/docs/en/02_Developer_Guides/14_Files/01_File_Management.md @@ -41,8 +41,8 @@ Note that this will not allow you to utilise certain file versioning features in ```yaml - \SilverStripe\Assets\Flysystem\FlysystemAssetStore: - legacy_filenames: true + \SilverStripe\Assets\Flysystem\FlysystemAssetStore: + legacy_filenames: true ``` ## Loading content into `DBFile` @@ -52,19 +52,19 @@ within the assets folder). For example, to load a temporary file into a DataObject you could use the below: ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - 'DBFile' - ]; - } + 'DBFile' + ]; + } - // Image could be assigned in other parts of the code using the below - $banner = new Banner(); - $banner->Image->setFromLocalFile($tempfile['path'], 'uploads/banner-file.jpg'); + // Image could be assigned in other parts of the code using the below + $banner = new Banner(); + $banner->Image->setFromLocalFile($tempfile['path'], 'uploads/banner-file.jpg'); ``` diff --git a/docs/en/02_Developer_Guides/14_Files/02_Images.md b/docs/en/02_Developer_Guides/14_Files/02_Images.md index 0466df408..346bec792 100644 --- a/docs/en/02_Developer_Guides/14_Files/02_Images.md +++ b/docs/en/02_Developer_Guides/14_Files/02_Images.md @@ -38,36 +38,36 @@ Here are some examples, assuming the `$Image` object has dimensions of 200x100px ```ss - // Scaling functions - $Image.ScaleWidth(150) // Returns a 150x75px image - $Image.ScaleMaxWidth(100) // Returns a 100x50px image (like ScaleWidth but prevents up-sampling) - $Image.ScaleHeight(150) // Returns a 300x150px image (up-sampled. Try to avoid doing this) - $Image.ScaleMaxHeight(150) // Returns a 200x100px image (like ScaleHeight but prevents up-sampling) - $Image.Fit(300,300) // Returns an image that fits within a 300x300px boundary, resulting in a 300x150px image (up-sampled) - $Image.FitMax(300,300) // Returns a 200x100px image (like Fit but prevents up-sampling) - - // Warning: This method can distort images that are not the correct aspect ratio - $Image.ResizedImage(200, 300) // Forces dimensions of this image to the given values. - - // Cropping functions - $Image.Fill(150,150) // Returns a 150x150px image resized and cropped to fill specified dimensions (up-sampled) - $Image.FillMax(150,150) // Returns a 100x100px image (like Fill but prevents up-sampling) - $Image.CropWidth(150) // Returns a 150x100px image (trims excess pixels off the x axis from the center) - $Image.CropHeight(50) // Returns a 200x50px image (trims excess pixels off the y axis from the center) - - // Padding functions (add space around an image) - $Image.Pad(100,100) // Returns a 100x100px padded image, with white bars added at the top and bottom - $Image.Pad(100, 100, CCCCCC) // Same as above but with a grey background - - // Metadata - $Image.Width // Returns width of image - $Image.Height // Returns height of image - $Image.Orientation // Returns Orientation - $Image.Title // Returns the friendly file name - $Image.Name // Returns the actual file name - $Image.FileName // Returns the actual file name including directory path from web root - $Image.Link // Returns relative URL path to image - $Image.AbsoluteLink // Returns absolute URL path to image + // Scaling functions + $Image.ScaleWidth(150) // Returns a 150x75px image + $Image.ScaleMaxWidth(100) // Returns a 100x50px image (like ScaleWidth but prevents up-sampling) + $Image.ScaleHeight(150) // Returns a 300x150px image (up-sampled. Try to avoid doing this) + $Image.ScaleMaxHeight(150) // Returns a 200x100px image (like ScaleHeight but prevents up-sampling) + $Image.Fit(300,300) // Returns an image that fits within a 300x300px boundary, resulting in a 300x150px image (up-sampled) + $Image.FitMax(300,300) // Returns a 200x100px image (like Fit but prevents up-sampling) + + // Warning: This method can distort images that are not the correct aspect ratio + $Image.ResizedImage(200, 300) // Forces dimensions of this image to the given values. + + // Cropping functions + $Image.Fill(150,150) // Returns a 150x150px image resized and cropped to fill specified dimensions (up-sampled) + $Image.FillMax(150,150) // Returns a 100x100px image (like Fill but prevents up-sampling) + $Image.CropWidth(150) // Returns a 150x100px image (trims excess pixels off the x axis from the center) + $Image.CropHeight(50) // Returns a 200x50px image (trims excess pixels off the y axis from the center) + + // Padding functions (add space around an image) + $Image.Pad(100,100) // Returns a 100x100px padded image, with white bars added at the top and bottom + $Image.Pad(100, 100, CCCCCC) // Same as above but with a grey background + + // Metadata + $Image.Width // Returns width of image + $Image.Height // Returns height of image + $Image.Orientation // Returns Orientation + $Image.Title // Returns the friendly file name + $Image.Name // Returns the actual file name + $Image.FileName // Returns the actual file name including directory path from web root + $Image.Link // Returns relative URL path to image + $Image.AbsoluteLink // Returns absolute URL path to image ``` Image methods are chainable. Example: @@ -75,7 +75,7 @@ Image methods are chainable. Example: ```ss - + ``` ### Padded Image Resize @@ -88,9 +88,9 @@ png images. ```php - $Image.Pad(80, 80, FFFFFF, 50) // white padding with 50% transparency - $Image.Pad(80, 80, FFFFFF, 100) // white padding with 100% transparency - $Image.Pad(80, 80, FFFFFF) // white padding with no transparency + $Image.Pad(80, 80, FFFFFF, 50) // white padding with 50% transparency + $Image.Pad(80, 80, FFFFFF, 100) // white padding with 100% transparency + $Image.Pad(80, 80, FFFFFF) // white padding with no transparency ``` ### Manipulating images in PHP @@ -107,7 +107,7 @@ You can also create your own functions by decorating the `Image` class. ```php - class ImageExtension extends \SilverStripe\Core\Extension + class ImageExtension extends \SilverStripe\Core\Extension { public function Square($width) @@ -136,13 +136,13 @@ You can also create your own functions by decorating the `Image` class. } - :::yml - SilverStripe\Assets\Image: - extensions: - - ImageExtension - SilverStripe\Filesystem\Storage\DBFile: - extensions: - - ImageExtension + :::yml + SilverStripe\Assets\Image: + extensions: + - ImageExtension + SilverStripe\Filesystem\Storage\DBFile: + extensions: + - ImageExtension ``` ### Form Upload @@ -177,12 +177,12 @@ necessary, you can add this to your mysite/config/config.yml file: ```yml - # Configure resampling for File dataobject - File: - force_resample: false - # DBFile can be configured independently - SilverStripe\Filesystem\Storage\DBFile: - force_resample: false + # Configure resampling for File dataobject + File: + force_resample: false + # DBFile can be configured independently + SilverStripe\Filesystem\Storage\DBFile: + force_resample: false ``` #### Resampled image quality diff --git a/docs/en/02_Developer_Guides/14_Files/03_File_Security.md b/docs/en/02_Developer_Guides/14_Files/03_File_Security.md index ede248e9b..30a18757e 100644 --- a/docs/en/02_Developer_Guides/14_Files/03_File_Security.md +++ b/docs/en/02_Developer_Guides/14_Files/03_File_Security.md @@ -265,10 +265,10 @@ appropriate file extensions for your instance. This can be done by setting the ` config. ```yaml - File: - allowed_extensions: - - 7zip - - xzip + File: + allowed_extensions: + - 7zip + - xzip ```
      diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md index cdfc14d1e..97c04b3b4 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md @@ -21,21 +21,21 @@ a category. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Product extends DataObject - { + class Product extends DataObject + { - private static $db = [ - 'Name' => 'Varchar', - 'ProductCode' => 'Varchar', - 'Price' => 'Currency' - ]; + private static $db = [ + 'Name' => 'Varchar', + 'ProductCode' => 'Varchar', + 'Price' => 'Currency' + ]; - private static $has_one = [ - 'Category' => 'Category' - ]; - } + private static $has_one = [ + 'Category' => 'Category' + ]; + } ``` @@ -43,19 +43,19 @@ a category. ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Category extends DataObject - { + class Category extends DataObject + { - private static $db = [ - 'Title' => 'Text' - ]; + private static $db = [ + 'Title' => 'Text' + ]; - private static $has_many = [ - 'Products' => 'Product' - ]; - } + private static $has_many = [ + 'Products' => 'Product' + ]; + } ``` @@ -68,20 +68,20 @@ We'll name it `MyAdmin`, but the class name can be anything you want. ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class MyAdmin extends ModelAdmin - { + class MyAdmin extends ModelAdmin + { - private static $managed_models = [ - 'Product', - 'Category' - ]; + private static $managed_models = [ + 'Product', + 'Category' + ]; - private static $url_segment = 'products'; + private static $url_segment = 'products'; - private static $menu_title = 'My Product Admin'; - } + private static $menu_title = 'My Product Admin'; + } ``` @@ -110,31 +110,31 @@ permissions by default. For most cases, less restrictive checks make sense, e.g. ```php - use SilverStripe\Security\Permission; - use SilverStripe\ORM\DataObject; + use SilverStripe\Security\Permission; + use SilverStripe\ORM\DataObject; - class Category extends DataObject - { - // ... - public function canView($member = null) - { - return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); - } + class Category extends DataObject + { + // ... + public function canView($member = null) + { + return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); + } - public function canEdit($member = null) - { - return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); - } + public function canEdit($member = null) + { + return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); + } - public function canDelete($member = null) - { - return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); - } + public function canDelete($member = null) + { + return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); + } - public function canCreate($member = null) - { - return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); - } + public function canCreate($member = null) + { + return Permission::check('CMS_ACCESS_MyAdmin', 'any', $member); + } ``` ## Searching Records @@ -151,16 +151,16 @@ class (see [SearchContext](../search/searchcontext) docs for details). ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Product extends DataObject - { + class Product extends DataObject + { - private static $searchable_fields = [ - 'Name', - 'ProductCode' - ]; - } + private static $searchable_fields = [ + 'Name', + 'ProductCode' + ]; + } ``` @@ -178,20 +178,20 @@ model class, where you can add or remove columns. To change the title, use [Data ```php - use SilverStripe\ORM\DataObject; + use SilverStripe\ORM\DataObject; - class Product extends DataObject - { + class Product extends DataObject + { - private static $field_labels = [ - 'Price' => 'Cost' // renames the column to "Cost" - ]; + private static $field_labels = [ + 'Price' => 'Cost' // renames the column to "Cost" + ]; - private static $summary_fields = [ - 'Name', - 'Price' - ]; - } + private static $summary_fields = [ + 'Name', + 'Price' + ]; + } ``` @@ -205,23 +205,23 @@ For example, we might want to exclude all products without prices in our sample ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class MyAdmin extends ModelAdmin - { + class MyAdmin extends ModelAdmin + { - public function getList() - { - $list = parent::getList(); + public function getList() + { + $list = parent::getList(); - // Always limit by model class, in case you're managing multiple - if($this->modelClass == 'Product') { - $list = $list->exclude('Price', '0'); - } + // Always limit by model class, in case you're managing multiple + if($this->modelClass == 'Product') { + $list = $list->exclude('Price', '0'); + } - return $list; - } - } + return $list; + } + } ``` You can also customize the search behavior directly on your `ModelAdmin` instance. For example, we might want to have a @@ -231,36 +231,36 @@ checkbox which limits search results to expensive products (over $100). ```php - use SilverStripe\Forms\CheckboxField; - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Forms\CheckboxField; + use SilverStripe\Admin\ModelAdmin; - class MyAdmin extends ModelAdmin - { + class MyAdmin extends ModelAdmin + { - public function getSearchContext() - { - $context = parent::getSearchContext(); + public function getSearchContext() + { + $context = parent::getSearchContext(); - if($this->modelClass == 'Product') { - $context->getFields()->push(new CheckboxField('q[ExpensiveOnly]', 'Only expensive stuff')); - } + if($this->modelClass == 'Product') { + $context->getFields()->push(new CheckboxField('q[ExpensiveOnly]', 'Only expensive stuff')); + } - return $context; - } + return $context; + } - public function getList() - { - $list = parent::getList(); + public function getList() + { + $list = parent::getList(); - $params = $this->getRequest()->requestVar('q'); // use this to access search parameters + $params = $this->getRequest()->requestVar('q'); // use this to access search parameters - if($this->modelClass == 'Product' && isset($params['ExpensiveOnly']) && $params['ExpensiveOnly']) { - $list = $list->exclude('Price:LessThan', '100'); - } + if($this->modelClass == 'Product' && isset($params['ExpensiveOnly']) && $params['ExpensiveOnly']) { + $list = $list->exclude('Price:LessThan', '100'); + } - return $list; - } - } + return $list; + } + } ``` To alter how the results are displayed (via [GridField](api:SilverStripe\Forms\GridField\GridField)), you can also overload the `getEditForm()` method. For @@ -270,34 +270,34 @@ example, to add a new component. ```php - use SilverStripe\Forms\GridField\GridFieldFilterHeader; - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Forms\GridField\GridFieldFilterHeader; + use SilverStripe\Admin\ModelAdmin; - class MyAdmin extends ModelAdmin - { + class MyAdmin extends ModelAdmin + { - private static $managed_models = [ - 'Product', - 'Category' - ]; + private static $managed_models = [ + 'Product', + 'Category' + ]; - // ... - public function getEditForm($id = null, $fields = null) - { - $form = parent::getEditForm($id, $fields); + // ... + public function getEditForm($id = null, $fields = null) + { + $form = parent::getEditForm($id, $fields); - // $gridFieldName is generated from the ModelClass, eg if the Class 'Product' - // is managed by this ModelAdmin, the GridField for it will also be named 'Product' + // $gridFieldName is generated from the ModelClass, eg if the Class 'Product' + // is managed by this ModelAdmin, the GridField for it will also be named 'Product' - $gridFieldName = $this->sanitiseClassName($this->modelClass); - $gridField = $form->Fields()->fieldByName($gridFieldName); + $gridFieldName = $this->sanitiseClassName($this->modelClass); + $gridField = $form->Fields()->fieldByName($gridFieldName); - // modify the list view. - $gridField->getConfig()->addComponent(new GridFieldFilterHeader()); + // modify the list view. + $gridField->getConfig()->addComponent(new GridFieldFilterHeader()); - return $form; - } - } + return $form; + } + } ``` @@ -308,31 +308,31 @@ to only one specific `GridField`: ```php - use SilverStripe\Forms\GridField\GridFieldFilterHeader; - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Forms\GridField\GridFieldFilterHeader; + use SilverStripe\Admin\ModelAdmin; - class MyAdmin extends ModelAdmin - { + class MyAdmin extends ModelAdmin + { - private static $managed_models = [ - 'Product', - 'Category' - ]; + private static $managed_models = [ + 'Product', + 'Category' + ]; - public function getEditForm($id = null, $fields = null) - { - $form = parent::getEditForm($id, $fields); + public function getEditForm($id = null, $fields = null) + { + $form = parent::getEditForm($id, $fields); - $gridFieldName = 'Product'; - $gridField = $form->Fields()->fieldByName($gridFieldName); + $gridFieldName = 'Product'; + $gridField = $form->Fields()->fieldByName($gridFieldName); - if ($gridField) { - $gridField->getConfig()->addComponent(new GridFieldFilterHeader()); - } + if ($gridField) { + $gridField->getConfig()->addComponent(new GridFieldFilterHeader()); + } - return $form; - } - } + return $form; + } + } ``` @@ -354,21 +354,21 @@ To customize the exported columns, create a new method called `getExportFields` ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class MyAdmin extends ModelAdmin - { - // ... + class MyAdmin extends ModelAdmin + { + // ... - public function getExportFields() - { - return [ - 'Name' => 'Name', - 'ProductCode' => 'Product Code', - 'Category.Title' => 'Category' - ]; - } - } + public function getExportFields() + { + return [ + 'Name' => 'Name', + 'ProductCode' => 'Product Code', + 'Category.Title' => 'Category' + ]; + } + } ``` diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md index b62f4dd35..83f9e4ada 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md @@ -57,16 +57,16 @@ The CMS interface can be accessed by default through the `admin/` URL. You can c ```yml - --- - Name: myadmin - After: - - '#adminroutes' - --- - Director: - rules: - 'admin': '' - 'newAdmin': 'AdminRootController' - --- + --- + Name: myadmin + After: + - '#adminroutes' + --- + Director: + rules: + 'admin': '' + 'newAdmin': 'AdminRootController' + --- ``` When extending the CMS or creating modules, you can take advantage of various functions that will return the configured admin URL (by default 'admin/' is returned): @@ -75,7 +75,7 @@ In PHP you should use: ```php - AdminRootController::admin_url() + AdminRootController::admin_url() ``` When writing templates use: @@ -83,7 +83,7 @@ When writing templates use: ```ss - $AdminURL + $AdminURL ``` And in JavaScript, this is avaible through the `ss` namespace @@ -91,7 +91,7 @@ And in JavaScript, this is avaible through the `ss` namespace ```js - ss.config.adminUrl + ss.config.adminUrl ``` ### Multiple Admin URL and overrides @@ -162,45 +162,45 @@ Basic example form in a CMS controller subclass: ```php - use SilverStripe\Forms\TabSet; - use SilverStripe\Forms\FieldList; - use SilverStripe\Forms\Tab; - use SilverStripe\Forms\TextField; - use SilverStripe\Forms\FormAction; - use SilverStripe\Admin\LeftAndMain; - use SilverStripe\Admin\LeftAndMainFormRequestHandler; + use SilverStripe\Forms\TabSet; + use SilverStripe\Forms\FieldList; + use SilverStripe\Forms\Tab; + use SilverStripe\Forms\TextField; + use SilverStripe\Forms\FormAction; + use SilverStripe\Admin\LeftAndMain; + use SilverStripe\Admin\LeftAndMainFormRequestHandler; - class MyAdmin extends LeftAndMain - { - function getEditForm() { - return Form::create( - $this, - 'EditForm', - new FieldList( - TabSet::create( - 'Root', - Tab::create('Main', - TextField::create('MyText') - ) - )->setTemplate('CMSTabset') - ), - new FieldList( - FormAction::create('doSubmit') - ) - ) - // Use a custom request handler - ->setRequestHandler( - LeftAndMainFormRequestHandler::create($form) - ) - // JS and CSS use this identifier - ->setHTMLID('Form_EditForm') - // Render correct responses on validation errors - ->setResponseNegotiator($this->getResponseNegotiator()); - // Required for correct CMS layout - ->addExtraClass('cms-edit-form') - ->setTemplate($this->getTemplatesWithSuffix('_EditForm')); - } - } + class MyAdmin extends LeftAndMain + { + function getEditForm() { + return Form::create( + $this, + 'EditForm', + new FieldList( + TabSet::create( + 'Root', + Tab::create('Main', + TextField::create('MyText') + ) + )->setTemplate('CMSTabset') + ), + new FieldList( + FormAction::create('doSubmit') + ) + ) + // Use a custom request handler + ->setRequestHandler( + LeftAndMainFormRequestHandler::create($form) + ) + // JS and CSS use this identifier + ->setHTMLID('Form_EditForm') + // Render correct responses on validation errors + ->setResponseNegotiator($this->getResponseNegotiator()); + // Required for correct CMS layout + ->addExtraClass('cms-edit-form') + ->setTemplate($this->getTemplatesWithSuffix('_EditForm')); + } + } ``` Note: Usually you don't need to worry about these settings, @@ -307,12 +307,12 @@ Firstly, `reactRouter` must be passed as a boolean flag to indicate that this se controlled by the react section, and thus should suppress registration of a page.js route for this section. ```php - public function getClientConfig() - { - return array_merge(parent::getClientConfig(), [ - 'reactRouter' => true - ]); - } + public function getClientConfig() + { + return array_merge(parent::getClientConfig(), [ + 'reactRouter' => true + ]); + } ``` @@ -321,33 +321,33 @@ with the reactRouteRegister component. This will need to be done on the `DOMCont to ensure routes are registered before window.load is invoked. ```js - import { withRouter } from 'react-router'; - import ConfigHelpers from 'lib/Config'; - import reactRouteRegister from 'lib/ReactRouteRegister'; - import MyAdmin from './MyAdmin'; - - document.addEventListener('DOMContentLoaded', () => { - const sectionConfig = ConfigHelpers.getSection('MyAdmin'); - - reactRouteRegister.add({ - path: sectionConfig.url, - component: withRouter(MyAdminComponent), - childRoutes: [ - { path: 'form/:id/:view', component: MyAdminComponent }, - ], - }); - }); + import { withRouter } from 'react-router'; + import ConfigHelpers from 'lib/Config'; + import reactRouteRegister from 'lib/ReactRouteRegister'; + import MyAdmin from './MyAdmin'; + + document.addEventListener('DOMContentLoaded', () => { + const sectionConfig = ConfigHelpers.getSection('MyAdmin'); + + reactRouteRegister.add({ + path: sectionConfig.url, + component: withRouter(MyAdminComponent), + childRoutes: [ + { path: 'form/:id/:view', component: MyAdminComponent }, + ], + }); + }); ``` Child routes can be registered post-boot by using `ReactRouteRegister` in the same way. ```js - // Register a nested url under `sectionConfig.url` - const sectionConfig = ConfigHelpers.getSection('MyAdmin'); - reactRouteRegister.add({ - path: 'nested', - component: NestedComponent, - }, [ sectionConfig.url ]); + // Register a nested url under `sectionConfig.url` + const sectionConfig = ConfigHelpers.getSection('MyAdmin'); + reactRouteRegister.add({ + path: 'nested', + component: NestedComponent, + }, [ sectionConfig.url ]); ``` ## PJAX: Partial template replacement through Ajax @@ -375,54 +375,57 @@ in a single Ajax request. ```php - use SilverStripe\Admin\LeftAndMain; + use SilverStripe\Admin\LeftAndMain; - // mysite/code/MyAdmin.php - class MyAdmin extends LeftAndMain - { - private static $url_segment = 'myadmin'; - public function getResponseNegotiator() - { - $negotiator = parent::getResponseNegotiator(); - $controller = $this; - // Register a new callback - $negotiator->setCallback('MyRecordInfo', function() use(&$controller) { - return $controller->MyRecordInfo(); - }); - return $negotiator; - } - public function MyRecordInfo() - { - return $this->renderWith('MyRecordInfo'); - } - } + // mysite/code/MyAdmin.php + class MyAdmin extends LeftAndMain + { + private static $url_segment = 'myadmin'; + public function getResponseNegotiator() + { + $negotiator = parent::getResponseNegotiator(); + $controller = $this; + // Register a new callback + $negotiator->setCallback('MyRecordInfo', function() use(&$controller) { + return $controller->MyRecordInfo(); + }); + return $negotiator; + } + public function MyRecordInfo() + { + return $this->renderWith('MyRecordInfo'); + } + } ``` ```js - // MyAdmin.ss - <% include SilverStripe\\Admin\\CMSBreadcrumbs %> -
      Static content (not affected by update)
      - <% include MyRecordInfo %> - - Update record info - + // MyAdmin.ss + <% include SilverStripe\\Admin\\CMSBreadcrumbs %> +
      Static content (not affected by update)
      + <% include MyRecordInfo %> + + Update record info + +``` - :::ss - // MyRecordInfo.ss -
      - Current Record: $currentPage.Title -
      +```ss + // MyRecordInfo.ss +
      + Current Record: $currentPage.Title +
      ``` A click on the link will cause the following (abbreviated) ajax HTTP request: + ``` - GET /admin/myadmin HTTP/1.1 - X-Pjax:MyRecordInfo,Breadcrumbs - X-Requested-With:XMLHttpRequest + GET /admin/myadmin HTTP/1.1 + X-Pjax:MyRecordInfo,Breadcrumbs + X-Requested-With:XMLHttpRequest ``` ... and result in the following response: + ``` - {"MyRecordInfo": "getResponse()->addHeader('X-Controller', 'MyOtherController'); - return $html; - } - } + class MyController extends LeftAndMain + { + class myaction() + { + // ... + $this->getResponse()->addHeader('X-Controller', 'MyOtherController'); + return $html; + } + } ``` Built-in headers are: @@ -569,12 +572,12 @@ which is picked up by the menu: ```php - public function mycontrollermethod() - { - // .. logic here - $this->getResponse()->addHeader('X-Controller', 'AssetAdmin'); - return 'my response'; - } + public function mycontrollermethod() + { + // .. logic here + $this->getResponse()->addHeader('X-Controller', 'AssetAdmin'); + return 'my response'; + } ``` This is usually handled by the existing [LeftAndMain](api:SilverStripe\Admin\LeftAndMain) logic, @@ -623,29 +626,29 @@ Form template with custom tab navigation (trimmed down): ```ss -
      + -
      - <% if Fields.hasTabset %> - <% with Fields.fieldByName('Root') %> -
      -
        - <% loop Tabs %> -
      • $Title
        • - <% end_loop %> -
      -
      - <% end_with %> - <% end_if %> -
      +
      + <% if Fields.hasTabset %> + <% with Fields.fieldByName('Root') %> +
      +
        + <% loop Tabs %> +
      • $Title
        • + <% end_loop %> +
      +
      + <% end_with %> + <% end_if %> +
      -
      -
      - <% loop Fields %>$FieldHolder<% end_loop %> -
      -
      +
      +
      + <% loop Fields %>$FieldHolder<% end_loop %> +
      +
      -
      + ``` Tabset template without tab navigation (e.g. `CMSTabset.ss`) @@ -653,19 +656,19 @@ Tabset template without tab navigation (e.g. `CMSTabset.ss`) ```ss -
      - <% loop Tabs %> - <% if Tabs %> - $FieldHolder - <% else %> -
      - <% loop Fields %> - $FieldHolder - <% end_loop %> -
      - <% end_if %> - <% end_loop %> -
      +
      + <% loop Tabs %> + <% if Tabs %> + $FieldHolder + <% else %> +
      + <% loop Fields %> + $FieldHolder + <% end_loop %> +
      + <% end_if %> + <% end_loop %> +
      ``` Lazy loading works based on the `href` attribute of the tab navigation. @@ -679,20 +682,20 @@ and load the HTML content into the main view. Example: ```ss -
      - -
      +
      + +
      ``` The URL endpoints `{$AdminURL}mytabs/tab1` and `{$AdminURL}mytabs/tab2` diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_CMS_Layout.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_CMS_Layout.md index 0b403362d..fff88e1bf 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_CMS_Layout.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_CMS_Layout.md @@ -24,7 +24,7 @@ The easiest way to update the layout of the CMS is to call `redraw` on the top-l ```js - $('.cms-container').redraw(); + $('.cms-container').redraw(); ``` This causes the framework to: @@ -66,12 +66,12 @@ Layout manager will automatically apply algorithms to the children of `.cms-cont ```html -
      - <%-- content utilising border's north, south, east, west and center classes --%> -
      +
      + <%-- content utilising border's north, south, east, west and center classes --%> +
      ``` For detailed discussion on available algorithms refer to @@ -113,7 +113,7 @@ Use provided factory method to generate algorithm instances. ```js - jLayout.threeColumnCompressor(, ); + jLayout.threeColumnCompressor(, ); ``` The parameters are as follows: diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md index 65f1b9434..eeafcdbd8 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md @@ -53,27 +53,27 @@ Note how the configuration happens in different entwine namespaces ```js - (function($) { - $.entwine('ss.preview', function($){ - $('.cms-preview').entwine({ - DefaultMode: 'content', - getSizes: function() { - var sizes = this._super(); - sizes.mobile.width = '400px'; - return sizes; - } - }); - }); - $.entwine('ss', function($){ - $('.cms-container').entwine({ - getLayoutOptions: function() { - var opts = this._super(); - opts.minPreviewWidth = 600; - return opts; - } - }); - }); - }(jQuery)); + (function($) { + $.entwine('ss.preview', function($){ + $('.cms-preview').entwine({ + DefaultMode: 'content', + getSizes: function() { + var sizes = this._super(); + sizes.mobile.width = '400px'; + return sizes; + } + }); + }); + $.entwine('ss', function($){ + $('.cms-container').entwine({ + getLayoutOptions: function() { + var opts = this._super(); + opts.minPreviewWidth = 600; + return opts; + } + }); + }); + }(jQuery)); ``` Load the file in the CMS via setting adding 'mysite/javascript/MyLeftAndMain.Preview.js' @@ -82,9 +82,9 @@ to the `LeftAndMain.extra_requirements_javascript` [configuration value](../conf ```yml - LeftAndMain: - extra_requirements_javascript: - - mysite/javascript/MyLeftAndMain.Preview.js + LeftAndMain: + extra_requirements_javascript: + - mysite/javascript/MyLeftAndMain.Preview.js ``` In order to find out which configuration values are available, the source code @@ -115,8 +115,8 @@ States are the site stages: _live_, _stage_ etc. Preview states are picked up from the `SilverStripeNavigator`. You can invoke the state change by calling: ```js - $('.cms-preview').entwine('.ss.preview').changeState('StageLink'); - ``` + $('.cms-preview').entwine('.ss.preview').changeState('StageLink'); + ``` Note the state names come from `SilverStripeNavigatorItems` class names - thus the _Link_ in their names. This call will also redraw the state selector to fit @@ -126,8 +126,8 @@ list of supported states. You can get the current state by calling: ```js - $('.cms-preview').entwine('.ss.preview').getCurrentStateName(); - ``` + $('.cms-preview').entwine('.ss.preview').getCurrentStateName(); + ``` ## Preview sizes @@ -145,14 +145,14 @@ has the benefit of redrawing the related selector and maintaining a consistent internal state: ```js - $('.cms-preview').entwine('.ss.preview').changeSize('auto'); - ``` + $('.cms-preview').entwine('.ss.preview').changeSize('auto'); + ``` You can find out current size by calling: ```js - $('.cms-preview').entwine('.ss.preview').getCurrentSizeName(); - ``` + $('.cms-preview').entwine('.ss.preview').getCurrentSizeName(); + ``` ## Preview modes @@ -161,15 +161,15 @@ algorithm, see [layout reference](cms_layout) for more details. You can change modes by calling: ```js - $('.cms-preview').entwine('.ss.preview').changeMode('preview'); - ``` + $('.cms-preview').entwine('.ss.preview').changeMode('preview'); + ``` Currently active mode is stored on the `.cms-container` along with related internal states of the layout. You can reach it by calling: ```js - $('.cms-container').entwine('.ss').getLayoutOptions().mode; - ``` + $('.cms-container').entwine('.ss').getLayoutOptions().mode; + ```
      Caveat: the `.preview-mode-selector` appears twice, once in the preview and diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md index a88f8fb4e..c75a806ee 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md @@ -8,7 +8,7 @@ SilverStripe lets you customise the style of content in the CMS. This is done by ```php - HtmlEditorConfig::get('cms')->setOption('content_css', project() . '/css/editor.css'); + HtmlEditorConfig::get('cms')->setOption('content_css', project() . '/css/editor.css'); ``` Will load the `mysite/css/editor.css` file. @@ -17,7 +17,7 @@ If using this config option in `mysite/_config.php`, you will have to instead ca ```php - HtmlEditorConfig::get('cms')->setOption('content_css', project() . '/css/editor.css'); + HtmlEditorConfig::get('cms')->setOption('content_css', project() . '/css/editor.css'); ``` Any CSS classes within this file will be automatically added to the `WYSIWYG` editors 'style' dropdown. For instance, to @@ -26,9 +26,9 @@ add the color 'red' as an option within the `WYSIWYG` add the following to the ` ```css - .red { - color: red; - } + .red { + color: red; + } ```
      diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Javascript_Development.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Javascript_Development.md index bdee4c12d..f473003f6 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Javascript_Development.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Javascript_Development.md @@ -47,11 +47,11 @@ You should write all your custom jQuery code in a closure. ```javascript - (function($) { - $(document).ready(function(){ - // your code here. - }) - })(jQuery); + (function($) { + $(document).ready(function(){ + // your code here. + }) + })(jQuery); ``` ## jQuery Plugins @@ -76,31 +76,31 @@ Example: A plugin to highlight a collection of elements with a configurable fore ```js - // create closure - (function($) { - // plugin definition - $.fn.hilight = function(options) { - // build main options before element iteration - var opts = $.extend({}, $.fn.hilight.defaults, options); - // iterate and reformat each matched element - return this.each(function() { - $this = $(this); - // build element specific options - var o = $.meta ? $.extend({}, opts, $this.data()) : opts; - // update element styles - $this.css({ - backgroundColor: o.background, - color: o.foreground - }); - }); - }; - // plugin defaults - $.fn.hilight.defaults = { - foreground: "red", - background: "yellow" - }; - // end of closure - })(jQuery); + // create closure + (function($) { + // plugin definition + $.fn.hilight = function(options) { + // build main options before element iteration + var opts = $.extend({}, $.fn.hilight.defaults, options); + // iterate and reformat each matched element + return this.each(function() { + $this = $(this); + // build element specific options + var o = $.meta ? $.extend({}, opts, $this.data()) : opts; + // update element styles + $this.css({ + backgroundColor: o.background, + color: o.foreground + }); + }); + }; + // plugin defaults + $.fn.hilight.defaults = { + foreground: "red", + background: "yellow" + }; + // end of closure + })(jQuery); ``` Usage: @@ -108,16 +108,16 @@ Usage: ```js - (function($) { - // Highlight all buttons with default colours - jQuery(':button').highlight(); + (function($) { + // Highlight all buttons with default colours + jQuery(':button').highlight(); - // Highlight all buttons with green background - jQuery(':button').highlight({background: "green"}); + // Highlight all buttons with green background + jQuery(':button').highlight({background: "green"}); - // Set all further highlight() calls to have a green background - $.fn.hilight.defaults.background = "green"; - })(jQuery); + // Set all further highlight() calls to have a green background + $.fn.hilight.defaults.background = "green"; + })(jQuery); ``` ## jQuery UI Widgets @@ -140,31 +140,31 @@ Example: Highlighter ```js - (function($) { - $.widget("ui.myHighlight", { - getBlink: function () { - return this._getData('blink'); - }, - setBlink: function (blink) { - this._setData('blink', blink); - if(blink) this.element.wrapInner(''); - else this.element.html(this.element.children().html()); - }, - _init: function() { - // grab the default value and use it - this.element.css('background',this.options.background); - this.element.css('color',this.options.foreground); - this.setBlink(this.options.blink); - } - }); - // For demonstration purposes, this is also possible with jQuery.css() - $.ui.myHighlight.getter = "getBlink"; - $.ui.myHighlight.defaults = { - foreground: "red", - background: "yellow", - blink: false - }; - })(jQuery); + (function($) { + $.widget("ui.myHighlight", { + getBlink: function () { + return this._getData('blink'); + }, + setBlink: function (blink) { + this._setData('blink', blink); + if(blink) this.element.wrapInner(''); + else this.element.html(this.element.children().html()); + }, + _init: function() { + // grab the default value and use it + this.element.css('background',this.options.background); + this.element.css('color',this.options.foreground); + this.setBlink(this.options.blink); + } + }); + // For demonstration purposes, this is also possible with jQuery.css() + $.ui.myHighlight.getter = "getBlink"; + $.ui.myHighlight.defaults = { + foreground: "red", + background: "yellow", + blink: false + }; + })(jQuery); ``` Usage: @@ -172,22 +172,22 @@ Usage: ```js - (function($) { - // call with default options - $(':button').myHighlight(); + (function($) { + // call with default options + $(':button').myHighlight(); - // call with custom options - $(':button').myHighlight({background: "green"}); + // call with custom options + $(':button').myHighlight({background: "green"}); - // set defaults for all future instances - $.ui.myHighlight.defaults.background = "green"; + // set defaults for all future instances + $.ui.myHighlight.defaults.background = "green"; - // Adjust property after initialization - $(':button').myHighlight('setBlink', true); + // Adjust property after initialization + $(':button').myHighlight('setBlink', true); - // Get property - $(':button').myHighlight('getBlink'); - })(jQuery); + // Get property + $(':button').myHighlight('getBlink'); + })(jQuery); ``` ### jQuery.Entwine @@ -206,16 +206,16 @@ Example: Highlighter ```js - (function($) { - $(':button').entwine({ - Foreground: 'red', - Background: 'yellow', - highlight: function() { - this.css('background', this.getBackground()); - this.css('color', this.getForeground()); - } - }); - })(jQuery); + (function($) { + $(':button').entwine({ + Foreground: 'red', + Background: 'yellow', + highlight: function() { + this.css('background', this.getBackground()); + this.css('color', this.getForeground()); + } + }); + })(jQuery); ``` Usage: @@ -223,16 +223,16 @@ Usage: ```js - (function($) { - // call with default options - $(':button').entwine().highlight(); + (function($) { + // call with default options + $(':button').entwine().highlight(); - // set options for existing and new instances - $(':button').entwine().setBackground('green'); + // set options for existing and new instances + $(':button').entwine().setBackground('green'); - // get property - $(':button').entwine().getBackground(); - })(jQuery); + // get property + $(':button').entwine().getBackground(); + })(jQuery); ``` This is a deliberately simple example, the strength of jQuery.entwine over simple jQuery plugins lies in its public @@ -256,11 +256,11 @@ Global properties are evil. They are accessible by other scripts, might be overw ```js - // you can't rely on '$' being defined outside of the closure - (function($) { - var myPrivateVar; // only available inside the closure - // inside here you can use the 'jQuery' object as '$' - })(jQuery); + // you can't rely on '$' being defined outside of the closure + (function($) { + var myPrivateVar; // only available inside the closure + // inside here you can use the 'jQuery' object as '$' + })(jQuery); ``` You can run `[jQuery.noConflict()](http://docs.jquery.com/Core/jQuery.noConflict)` to avoid namespace clashes. @@ -274,10 +274,10 @@ the `window.onload` and `document.ready` events. ```js - // DOM elements might not be available here - $(document).ready(function() { - // The DOM is fully loaded here - }); + // DOM elements might not be available here + $(document).ready(function() { + // The DOM is fully loaded here + }); ``` See [jQuery FAQ: Launching Code on Document @@ -295,15 +295,15 @@ Example: Add a 'loading' classname to all pressed buttons ```js - // manual binding, only applies to existing elements - $('input[[type=submit]]').on('click', function() { - $(this).addClass('loading'); - }); + // manual binding, only applies to existing elements + $('input[[type=submit]]').on('click', function() { + $(this).addClass('loading'); + }); - // binding, applies to any inserted elements as well - $('.cms-container').on('click', 'input[[type=submit]]', function() { - $(this).addClass('loading'); - }); + // binding, applies to any inserted elements as well + $('.cms-container').on('click', 'input[[type=submit]]', function() { + $(this).addClass('loading'); + }); ``` ### Assume Element Collections @@ -314,12 +314,12 @@ makes sense). Encapsulate your code by nesting your jQuery commands inside a `jQ ```js - $('div.MyGridField').each(function() { - // This is the over code for the tr elements inside a GridField. - $(this).find('tr').hover( - // ... - ); - }); + $('div.MyGridField').each(function() { + // This is the over code for the tr elements inside a GridField. + $(this).find('tr').hover( + // ... + ); + }); ``` ### Use plain HTML and jQuery.data() to store data @@ -334,12 +334,12 @@ Through CSS properties ```js - $('form :input').bind('change', function(e) { - $(this.form).addClass('isChanged'); - }); - $('form').bind('submit', function(e) { - if($(this).hasClass('isChanged')) return false; - }); + $('form :input').bind('change', function(e) { + $(this.form).addClass('isChanged'); + }); + $('form').bind('submit', function(e) { + if($(this).hasClass('isChanged')) return false; + }); ``` Through jQuery.data() @@ -347,13 +347,13 @@ Through jQuery.data() ```js - $('form :input').bind('change', function(e) { - $(this.form).data('isChanged', true); - }); - $('form').bind('submit', function(e) { - alert($(this).data('isChanged')); - if($(this).data('isChanged')) return false; - }); + $('form :input').bind('change', function(e) { + $(this.form).data('isChanged', true); + }); + $('form').bind('submit', function(e) { + alert($(this).data('isChanged')); + if($(this).data('isChanged')) return false; + }); ``` See [interactive example on jsbin.com](http://jsbin.com/opuva) @@ -367,22 +367,22 @@ Example: Restricted numeric value field ```ss - + ``` ```js - $('.restricted-text').bind('change', function(e) { - if( - e.target.value < $(this).metadata().min - || e.target.value > $(this).metadata().max - ) { - alert('Invalid value'); - return false; - } - }); + $('.restricted-text').bind('change', function(e) { + if( + e.target.value < $(this).metadata().min + || e.target.value > $(this).metadata().max + ) { + alert('Invalid value'); + return false; + } + }); ``` See [interactive example on jsbin.com](http://jsbin.com/axafa) @@ -408,34 +408,34 @@ Template: ```ss -
        - <% loop $Results %> -
      • $Title
        • - <% end_loop %> -
      +
        + <% loop $Results %> +
      • $Title
        • + <% end_loop %> +
      ``` PHP: ```php - class MyController - { - public function autocomplete($request) - { - $results = Page::get()->filter("Title", $request->getVar('title')); - if(!$results) return new HTTPResponse("Not found", 404); + class MyController + { + public function autocomplete($request) + { + $results = Page::get()->filter("Title", $request->getVar('title')); + if(!$results) return new HTTPResponse("Not found", 404); - // Use HTTPResponse to pass custom status messages - $this->getResponse()->setStatusCode(200, "Found " . $results->Count() . " elements"); + // Use HTTPResponse to pass custom status messages + $this->getResponse()->setStatusCode(200, "Found " . $results->Count() . " elements"); - // render all results with a custom template - $vd = new ViewableData(); - return $vd->customise([ - "Results" => $results - ])->renderWith('AutoComplete'); - } - } + // render all results with a custom template + $vd = new ViewableData(); + return $vd->customise([ + "Results" => $results + ])->renderWith('AutoComplete'); + } + } ``` @@ -444,13 +444,13 @@ HTML ```ss -
      -
      - - - - +
      +
      + + + + ``` JavaScript: @@ -458,23 +458,23 @@ JavaScript: ```js - $('.autocomplete input').on('change', function() { - var resultsEl = $(this).siblings('.results'); - resultsEl.load( - // get form action, using the jQuery.metadata plugin - $(this).parent().metadata().url, - // submit all form values - $(this.form).serialize(), - // callback after data is loaded - function(data, status) { - resultsEl.show(); - // get all record IDs from the new HTML - var ids = jQuery('.results').find('li').map(function() { - return $(this).attr('id').replace(/Record\-/,''); - }); - } - ); - }); + $('.autocomplete input').on('change', function() { + var resultsEl = $(this).siblings('.results'); + resultsEl.load( + // get form action, using the jQuery.metadata plugin + $(this).parent().metadata().url, + // submit all form values + $(this.form).serialize(), + // callback after data is loaded + function(data, status) { + resultsEl.show(); + // get all record IDs from the new HTML + var ids = jQuery('.results').find('li').map(function() { + return $(this).attr('id').replace(/Record\-/,''); + }); + } + ); + }); ``` Although they are the minority of cases, there are times when a simple HTML fragment isn't enough. For example, if you @@ -499,20 +499,20 @@ Example: Trigger custom 'validationfailed' event on form submission for each emp ```js - $('form').bind('submit', function(e) { - // $(this) refers to form - $(this).find(':input').each(function() { - // $(this) in here refers to input field - if(!$(this).val()) $(this).trigger('validationfailed'); - }); - return false; - }); + $('form').bind('submit', function(e) { + // $(this) refers to form + $(this).find(':input').each(function() { + // $(this) in here refers to input field + if(!$(this).val()) $(this).trigger('validationfailed'); + }); + return false; + }); - // listen to custom event on each field - $('form :input').bind('validationfailed',function(e) { - // $(this) refers to input field - alert($(this).attr('name')); - }); + // listen to custom event on each field + $('form :input').bind('validationfailed',function(e) { + // $(this) refers to input field + alert($(this).attr('name')); + }); ``` See [interactive example on jsbin.com](http://jsbin.com/ipeca). @@ -558,52 +558,52 @@ Example: jQuery.entwine ```js - /** + /** - * Available Custom Events: - *
        - *
      • ajaxsubmit
        • - *
      • validate
        • - *
      • reloadeditform
        • - *
      - * - * @class Main LeftAndMain interface with some control panel and an edit form. - * @name ss.LeftAndMain - */ - $('.LeftAndMain').entwine('ss', function($){ - return/** @lends ss.LeftAndMain */ { - /** + * Available Custom Events: + *
        + *
      • ajaxsubmit
        • + *
      • validate
        • + *
      • reloadeditform
        • + *
      + * + * @class Main LeftAndMain interface with some control panel and an edit form. + * @name ss.LeftAndMain + */ + $('.LeftAndMain').entwine('ss', function($){ + return/** @lends ss.LeftAndMain */ { + /** - * Reference to some property - * @type Number - */ - MyProperty: 123, + * Reference to some property + * @type Number + */ + MyProperty: 123, - /** + /** - * Renders the provided data into an unordered list. - * - * @param {Object} data - * @param {String} status - * @return {String} HTML unordered list - */ - publicMethod: function(data, status) { - return '
        ' - + /... - + '
      '; - }, + * Renders the provided data into an unordered list. + * + * @param {Object} data + * @param {String} status + * @return {String} HTML unordered list + */ + publicMethod: function(data, status) { + return '
        ' + + /... + + '
      '; + }, - /** + /** - * Won't show in documentation, but still worth documenting. - * - * @return {String} Something else. - */ - _privateMethod: function() { - // ... - } - }; - ]]); + * Won't show in documentation, but still worth documenting. + * + * @return {String} Something else. + */ + _privateMethod: function() { + // ... + } + }; + ]]); ``` ### Unit Testing @@ -619,27 +619,27 @@ Example: QUnit test (from [jquery.com](http://docs.jquery.com/QUnit#Using_QUnit) ```js - test("a basic test example", function() { - ok( true, "this test is fine" ); - var value = "hello"; - equals( "hello", value, "We expect value to be hello" ); - }); + test("a basic test example", function() { + ok( true, "this test is fine" ); + var value = "hello"; + equals( "hello", value, "We expect value to be hello" ); + }); ``` Example: JSpec Shopping cart test (from [visionmedia.github.com](http://visionmedia.github.com/jspec/)) ``` - describe 'ShoppingCart' - before_each - cart = new ShoppingCart - end - describe 'addProduct' - it 'should add a product' - cart.addProduct('cookie') - cart.addProduct('icecream') - cart.should.have 2, 'products' - end - end - end + describe 'ShoppingCart' + before_each + cart = new ShoppingCart + end + describe 'addProduct' + it 'should add a product' + cart.addProduct('cookie') + cart.addProduct('icecream') + cart.should.have 2, 'products' + end + end + end ``` ## Related diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_ReactJS_Redux_and_GraphQL.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_ReactJS_Redux_and_GraphQL.md index 29a1af9be..4bc4f562f 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_ReactJS_Redux_and_GraphQL.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_ReactJS_Redux_and_GraphQL.md @@ -23,19 +23,19 @@ React's job is to render UI. Its UI elements are known as "components" and repre ```js - + ``` Might actually render HTML that looks like this: ```html
      -
      - -
      -
      -

      Angkor Wat/a>

      -
      +
      + +
      +
      +

      Angkor Wat/a>

      +
      ``` @@ -91,18 +91,18 @@ engine. ``` query GetUser($ID: Int!) { - user { - name - email - blogPosts { - title - comments(Limit: 5) { - author - comment - } - } + user { + name + email + blogPosts { + title + comments(Limit: 5) { + author + comment + } + } - } + } } ``` @@ -110,21 +110,21 @@ The above query is almost self-descriptive. It gets a user by ID, returns his or ```js { - "user": { - "name": "Test user", - "email": "me@example.com", - "blogPosts": [ - { - "title": "How to be awesome at GraphQL", - "comments": [ - { - "author": "Uncle Cheese", - "comment": "Nice stuff, bro" - } - ] - } - ] - } + "user": { + "name": "Test user", + "email": "me@example.com", + "blogPosts": [ + { + "title": "How to be awesome at GraphQL", + "comments": [ + { + "author": "Uncle Cheese", + "comment": "Nice stuff, bro" + } + ] + } + ] + } } ``` @@ -176,10 +176,10 @@ Where `next()` is the next customisation in the "chain" of middleware. Before in ```js import thirdPartyLogger from 'third-party-logger'; const addLoggingMiddleware = (next) => (error) => { - if (error.type === LoggingService.CRITICAL) { - thirdpartyLogger.send(error.message); - } - return next(error); + if (error.type === LoggingService.CRITICAL) { + thirdpartyLogger.send(error.message); + } + return next(error); } ``` @@ -198,18 +198,18 @@ import LoggingService from './LoggingService'; import thirdPartyLogger from 'third-party-logger'; const addLoggingMiddleware = (next) => (error) => { - // Critical errors go to a thirdparty service - if (error.type === LoggingService.CRITICAL) { - thirdPartyLogger.send(error.message); - } - // Other errors get logged, but not to our thirdparty - else if (error.type === LoggingService.ERROR) { - next(error); - } - // Minor errors are ignored - else { - // Do nothing! - } + // Critical errors go to a thirdparty service + if (error.type === LoggingService.CRITICAL) { + thirdPartyLogger.send(error.message); + } + // Other errors get logged, but not to our thirdparty + else if (error.type === LoggingService.ERROR) { + next(error); + } + // Minor errors are ignored + else { + // Do nothing! + } } ``` @@ -253,12 +253,12 @@ __someone-elses-module/js/main.js__ ```js Injector.transform( - 'my-transformation', - (updater) => { - updater.component('MyComponent', MyCustomComponent); - updater.reducer('myCustom', MyCustomReducer); + 'my-transformation', + (updater) => { + updater.component('MyComponent', MyCustomComponent); + updater.reducer('myCustom', MyCustomReducer); - } + } ); ``` @@ -296,13 +296,13 @@ __my-module/js/main.js__ ```js Injector.transform( - 'my-transformation', - (updater) => { - updater.component('MyComponent', MyCustomComponent); - updater.reducer('myCustom', MyCustomReducer); + 'my-transformation', + (updater) => { + updater.component('MyComponent', MyCustomComponent); + updater.reducer('myCustom', MyCustomReducer); - }, - { after: 'another-module' } + }, + { after: 'another-module' } ); ``` @@ -349,17 +349,17 @@ Likewise, services can be applied for specific contexts. ```js Injector.transform('my-transform', (updater) => { - // Applies to all text fields in AssetAdmin - updater.component('TextField.AssetAdmin', MyTextField); + // Applies to all text fields in AssetAdmin + updater.component('TextField.AssetAdmin', MyTextField); - // Applies to all text fields in AssetAdmin editform - updater.component('TextField.AssetAdmin.FileEditForm', MyTextField); + // Applies to all text fields in AssetAdmin editform + updater.component('TextField.AssetAdmin.FileEditForm', MyTextField); - // Applies to any textfield named "Title" in AssetAdmin - updater.component('TextField.AssetAdmin.*.Title', MyTextField); + // Applies to any textfield named "Title" in AssetAdmin + updater.component('TextField.AssetAdmin.*.Title', MyTextField); - // Applies to any textfield named "Title" in any admin - updater.component('TextField.*.*.Title', MyTextField); + // Applies to any textfield named "Title" in any admin + updater.component('TextField.*.*.Title', MyTextField); }) ``` @@ -379,16 +379,16 @@ Using the `PhotoItem` example above, let's create a customised `PhotoItem` that ```js const enhancedPhoto = (PhotoItem) => (props) => { - const badge = props.isNew ? -
      New!
      : - null; + const badge = props.isNew ? +
      New!
      : + null; - return ( -
      - {badge} - -
      - ); + return ( +
      + {badge} + +
      + ); } const EnhancedPhotoItem = enhancedPhoto(PhotoItem); @@ -401,21 +401,21 @@ function. ```js const enhancedPhoto = (PhotoItem) => { - return class EnhancedPhotoItem extends React.Component { - render() { - const badge = this.props.isNew ? -
      New!
      : - null; + return class EnhancedPhotoItem extends React.Component { + render() { + const badge = this.props.isNew ? +
      New!
      : + null; - return ( -
      - {badge} - -
      - ); + return ( +
      + {badge} + +
      + ); - } - } + } + } } ``` @@ -509,17 +509,17 @@ Most behavioural and aesthetic customisations will happen via a mutation of the ```js Injector.transform( - 'my-custom-form', - (updater) => { - updater.form.alterSchema( - 'AssetAdmin.*', - (form) => + 'my-custom-form', + (updater) => { + updater.form.alterSchema( + 'AssetAdmin.*', + (form) => form.updateField('Title', { myCustomProp: true }) .getState() - ) - } + ) + } ); ``` diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Alternating_Button.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Alternating_Button.md index 6911357fc..d11fbf67a 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Alternating_Button.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Alternating_Button.md @@ -28,21 +28,21 @@ Here is the configuration code for the button: ```php - public function getCMSActions() - { - $fields = parent::getCMSActions(); + public function getCMSActions() + { + $fields = parent::getCMSActions(); - $fields->fieldByName('MajorActions')->push( - $cleanupAction = FormAction::create('cleanup', 'Cleaned') - // Set up an icon for the neutral state that will use the default text. - ->setAttribute('data-icon', 'accept') - // Initialise the alternate constructive state. - ->setAttribute('data-icon-alternate', 'addpage') - ->setAttribute('data-text-alternate', 'Clean-up now') - ); + $fields->fieldByName('MajorActions')->push( + $cleanupAction = FormAction::create('cleanup', 'Cleaned') + // Set up an icon for the neutral state that will use the default text. + ->setAttribute('data-icon', 'accept') + // Initialise the alternate constructive state. + ->setAttribute('data-icon-alternate', 'addpage') + ->setAttribute('data-text-alternate', 'Clean-up now') + ); - return $fields; - } + return $fields; + } ``` You can control the state of the button from the backend by applying `ss-ui-alternate` class to the `FormAction`. To @@ -55,15 +55,15 @@ Here we initialise the button based on the backend check, and assume that the bu ```php - public function getCMSActions() - { - // ... - if ($this->needsCleaning()) { - // Will initialise the button into alternate state. - $cleanupAction->addExtraClass('ss-ui-alternate'); - } - // ... - } + public function getCMSActions() + { + // ... + if ($this->needsCleaning()) { + // Will initialise the button into alternate state. + $cleanupAction->addExtraClass('ss-ui-alternate'); + } + // ... + } ``` ## Frontend support @@ -81,7 +81,7 @@ First of all, you can toggle the state of the button - execute this code in the ```js - jQuery('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').button('toggleAlternate'); + jQuery('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').button('toggleAlternate'); ``` Another, more useful, scenario is to check the current state. @@ -89,7 +89,7 @@ Another, more useful, scenario is to check the current state. ```js - jQuery('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').button('option', 'showingAlternate'); + jQuery('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').button('option', 'showingAlternate'); ``` You can also force the button into a specific state by using UI options. @@ -97,7 +97,7 @@ You can also force the button into a specific state by using UI options. ```js - jQuery('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').button({showingAlternate: true}); + jQuery('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').button({showingAlternate: true}); ``` This will allow you to react to user actions in the CMS and give immediate feedback. Here is an example taken from the @@ -107,23 +107,23 @@ CMS core that tracks the changes to the input fields and reacts by enabling the ```js - /** - * Enable save buttons upon detecting changes to content. - * "changed" class is added by jQuery.changetracker. - */ - $('.cms-edit-form .changed').entwine({ - // This will execute when the class is added to the element. - onmatch: function(e) { - var form = this.closest('.cms-edit-form'); - form.find('#Form_EditForm_action_save').button({showingAlternate: true}); - form.find('#Form_EditForm_action_publish').button({showingAlternate: true}); - this._super(e); - }, - // Entwine requires us to define this, even if we don't use it. - onunmatch: function(e) { - this._super(e); - } - }); + /** + * Enable save buttons upon detecting changes to content. + * "changed" class is added by jQuery.changetracker. + */ + $('.cms-edit-form .changed').entwine({ + // This will execute when the class is added to the element. + onmatch: function(e) { + var form = this.closest('.cms-edit-form'); + form.find('#Form_EditForm_action_save').button({showingAlternate: true}); + form.find('#Form_EditForm_action_publish').button({showingAlternate: true}); + this._super(e); + }, + // Entwine requires us to define this, even if we don't use it. + onunmatch: function(e) { + this._super(e); + } + }); ``` ## Frontend hooks @@ -157,26 +157,26 @@ cases. ```js - (function($) { + (function($) { - $.entwine('mysite', function($){ - $('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').entwine({ - /** - * onafterrefreshalternate is SS-specific jQuery UI hook that is executed - * every time the button is rendered (including on initialisation). - */ - onbuttonafterrefreshalternate: function() { - if (this.button('option', 'showingAlternate')) { - this.addClass('ss-ui-action-constructive'); - } - else { - this.removeClass('ss-ui-action-constructive'); - } - } - }); - }); + $.entwine('mysite', function($){ + $('.cms-edit-form .btn-toolbar #Form_EditForm_action_cleanup').entwine({ + /** + * onafterrefreshalternate is SS-specific jQuery UI hook that is executed + * every time the button is rendered (including on initialisation). + */ + onbuttonafterrefreshalternate: function() { + if (this.button('option', 'showingAlternate')) { + this.addClass('ss-ui-action-constructive'); + } + else { + this.removeClass('ss-ui-action-constructive'); + } + } + }); + }); - }(jQuery)); + }(jQuery)); ``` ## Summary diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Formfield_Help_Text.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Formfield_Help_Text.md index e3996f76c..677fb7d37 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Formfield_Help_Text.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/CMS_Formfield_Help_Text.md @@ -11,8 +11,8 @@ at the last position within the field, and expects unescaped HTML content. ```php - TextField::create('MyText', 'My Text Label') - ->setDescription('More detailed help'); + TextField::create('MyText', 'My Text Label') + ->setDescription('More detailed help'); ``` To show the help text as a tooltip instead of inline, @@ -20,9 +20,9 @@ add a `.cms-description-tooltip` class. ```php - TextField::create('MyText', 'My Text Label') - ->setDescription('More detailed help') - ->addExtraClass('cms-description-tooltip'); + TextField::create('MyText', 'My Text Label') + ->setDescription('More detailed help') + ->addExtraClass('cms-description-tooltip'); ``` Tooltips are only supported @@ -40,9 +40,9 @@ by clicking the 'info' icon displayed alongside the field. ```php - TextField::create('MyText', 'My Text Label') - ->setDescription('More detailed help') - ->addExtraClass('cms-description-toggle'); + TextField::create('MyText', 'My Text Label') + ->setDescription('More detailed help') + ->addExtraClass('cms-description-toggle'); ``` If you want to provide a custom icon for toggling the description, you can do that @@ -50,10 +50,10 @@ by setting an additional `RightTitle`. ```php - TextField::create('MyText', 'My Text Label') - ->setDescription('More detailed help') - ->addExtraClass('cms-description-toggle') - ->setRightTitle('      My custom icon'); + TextField::create('MyText', 'My Text Label') + ->setDescription('More detailed help') + ->addExtraClass('cms-description-toggle') + ->setRightTitle('My custom icon'); ``` Note: For more advanced help text we recommend using diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md index 5a096886f..703e0fc28 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md @@ -22,13 +22,13 @@ black-and-transparent PNG graphics. In this case we'll place the icon in ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class ProductAdmin extends ModelAdmin - { - // ... - private static $menu_icon = 'mysite/images/product-icon.png'; - } + class ProductAdmin extends ModelAdmin + { + // ... + private static $menu_icon = 'mysite/images/product-icon.png'; + } ``` ### Defining a Custom Title @@ -39,13 +39,13 @@ controller, removing the "Admin" bit at the end. ```php - use SilverStripe\Admin\ModelAdmin; + use SilverStripe\Admin\ModelAdmin; - class ProductAdmin extends ModelAdmin - { - // ... - private static $menu_title = 'My Custom Admin'; - } + class ProductAdmin extends ModelAdmin + { + // ... + private static $menu_title = 'My Custom Admin'; + } ``` In order to localize the menu title in different languages, use the @@ -66,36 +66,36 @@ button configuration. ```php - use SilverStripe\Admin\CMSMenu; - use SilverStripe\Admin\LeftAndMainExtension; + use SilverStripe\Admin\CMSMenu; + use SilverStripe\Admin\LeftAndMainExtension; - class CustomLeftAndMain extends LeftAndMainExtension - { + class CustomLeftAndMain extends LeftAndMainExtension + { - public function init() - { - // unique identifier for this item. Will have an ID of Menu-$ID - $id = 'LinkToGoogle'; + public function init() + { + // unique identifier for this item. Will have an ID of Menu-$ID + $id = 'LinkToGoogle'; - // your 'nice' title - $title = 'Google'; + // your 'nice' title + $title = 'Google'; - // the link you want to item to go to - $link = 'http://google.com'; + // the link you want to item to go to + $link = 'http://google.com'; - // priority controls the ordering of the link in the stack. The - // lower the number, the lower in the list - $priority = -2; + // priority controls the ordering of the link in the stack. The + // lower the number, the lower in the list + $priority = -2; - // Add your own attributes onto the link. In our case, we want to - // open the link in a new window (not the original) - $attributes = [ - 'target' => '_blank' - ]; + // Add your own attributes onto the link. In our case, we want to + // open the link in a new window (not the original) + $attributes = [ + 'target' => '_blank' + ]; - CMSMenu::add_link($id, $title, $link, $priority, $attributes); - } - } + CMSMenu::add_link($id, $title, $link, $priority, $attributes); + } + } ``` @@ -105,7 +105,7 @@ class. For more information about configuring extensions see the ```php - LeftAndMain::add_extension('CustomLeftAndMain') + LeftAndMain::add_extension('CustomLeftAndMain') ``` ## Related diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Pages_List.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Pages_List.md index 10da41df7..cbcd5f0be 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Pages_List.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Pages_List.md @@ -19,21 +19,21 @@ hypothetical `NewsPageHolder` type, which contains `NewsPage` children. ```php - use Page; + use Page; - // mysite/code/NewsPageHolder.php - class NewsPageHolder extends Page - { - private static $allowed_children = ['NewsPage']; - } + // mysite/code/NewsPageHolder.php + class NewsPageHolder extends Page + { + private static $allowed_children = ['NewsPage']; + } - // mysite/code/NewsPage.php - class NewsPage extends Page - { - private static $has_one = [ - 'Author' => 'Member', - ]; - } + // mysite/code/NewsPage.php + class NewsPage extends Page + { + private static $has_one = [ + 'Author' => 'Member', + ]; + } ``` @@ -45,41 +45,41 @@ or across page types with common characteristics. ```php - use Page; - use SilverStripe\Core\Extension; + use Page; + use SilverStripe\Core\Extension; - // mysite/code/NewsPageHolderCMSMainExtension.php - class NewsPageHolderCMSMainExtension extends Extension - { - function updateListView($listView) { - $parentId = $listView->getController()->getRequest()->requestVar('ParentID'); - $parent = ($parentId) ? Page::get()->byId($parentId) : new Page(); + // mysite/code/NewsPageHolderCMSMainExtension.php + class NewsPageHolderCMSMainExtension extends Extension + { + function updateListView($listView) { + $parentId = $listView->getController()->getRequest()->requestVar('ParentID'); + $parent = ($parentId) ? Page::get()->byId($parentId) : new Page(); - // Only apply logic for this page type - if($parent && $parent instanceof NewsPageHolder) { - $gridField = $listView->Fields()->dataFieldByName('Page'); - if($gridField) { - // Sort by created - $list = $gridField->getList(); - $gridField->setList($list->sort('Created', 'DESC')); - // Add author to columns - $cols = $gridField->getConfig()->getComponentByType('GridFieldDataColumns'); - if($cols) { - $fields = $cols->getDisplayFields($gridField); - $fields['Author.Title'] = 'Author'; - $cols->setDisplayFields($fields); - } - } - } - } - } + // Only apply logic for this page type + if($parent && $parent instanceof NewsPageHolder) { + $gridField = $listView->Fields()->dataFieldByName('Page'); + if($gridField) { + // Sort by created + $list = $gridField->getList(); + $gridField->setList($list->sort('Created', 'DESC')); + // Add author to columns + $cols = $gridField->getConfig()->getComponentByType('GridFieldDataColumns'); + if($cols) { + $fields = $cols->getDisplayFields($gridField); + $fields['Author.Title'] = 'Author'; + $cols->setDisplayFields($fields); + } + } + } + } + } ``` Now you just need to enable the extension in your [configuration file](../../configuration). ```yml - // mysite/_config/config.yml - LeftAndMain: - extensions: - - NewsPageHolderCMSMainExtension + // mysite/_config/config.yml + LeftAndMain: + extensions: + - NewsPageHolderCMSMainExtension ``` You're all set! Don't forget to flush the caches by appending `?flush=all` to the URL. diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md index d43d1f136..1a0b96491 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md @@ -23,24 +23,24 @@ code like this: ```ss - ... - - ... + ... + + ... ``` By applying the proper style sheet, the snippet html above could produce the look of: @@ -66,22 +66,22 @@ __Example: using a subclass__ ```php - use SilverStripe\CMS\Model\SiteTree; + use SilverStripe\CMS\Model\SiteTree; - class Page extends SiteTree - { - public function getScheduledToPublish() - { - // return either true or false - } + class Page extends SiteTree + { + public function getScheduledToPublish() + { + // return either true or false + } - public function getStatusFlags($cached = true) - { - $flags = parent::getStatusFlags($cached); - $flags['scheduledtopublish'] = "Scheduled To Publish"; - return $flags; - } - } + public function getStatusFlags($cached = true) + { + $flags = parent::getStatusFlags($cached); + $flags['scheduledtopublish'] = "Scheduled To Publish"; + return $flags; + } + } ``` The above subclass of [SiteTree](api:SilverStripe\CMS\Model\SiteTree) will add a new flag for indicating its diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_React_Components.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_React_Components.md index 7244bda8e..fed07b012 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_React_Components.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_React_Components.md @@ -123,7 +123,7 @@ const CharacterCounter = (TextField) => (props) => {
      {showWarning && - Characters remaining: {remainingChars} + Characters remaining: {remainingChars} }
      ); diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_Site_Reports.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_Site_Reports.md index 000ed26ff..22edf2642 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_Site_Reports.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_Site_Reports.md @@ -34,34 +34,34 @@ The following example will create a report to list every page on the current sit ###CustomSideReport.php ```php - use Page; - use SilverStripe\Reports\Report; + use Page; + use SilverStripe\Reports\Report; - class CustomSideReport_NameOfReport extends Report - { - - // the name of the report - public function title() - { - return 'All Pages'; - } - - // what we want the report to return - public function sourceRecords($params = null) - { - return Page::get()->sort('Title'); - } - - // which fields on that object we want to show - public function columns() - { - $fields = [ - 'Title' => 'Title' - ]; - - return $fields; - } - } + class CustomSideReport_NameOfReport extends Report + { + + // the name of the report + public function title() + { + return 'All Pages'; + } + + // what we want the report to return + public function sourceRecords($params = null) + { + return Page::get()->sort('Title'); + } + + // which fields on that object we want to show + public function columns() + { + $fields = [ + 'Title' => 'Title' + ]; + + return $fields; + } + } ``` diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md index 92c59fa4e..addfbc2ba 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md @@ -31,17 +31,17 @@ the CMS logic. Add a new section into the `
        ` ```ss - ... - - ... + ... + + ... ``` Refresh the CMS interface with `admin/?flush=all`, and you should see those @@ -57,7 +57,7 @@ with the CMS interface. Paste the following content into a new file called ```css - .bookmarked-link.first {margin-top: 1em;} + .bookmarked-link.first {margin-top: 1em;} ``` Load the new CSS file into the CMS, by setting the `LeftAndMain.extra_requirements_css` @@ -66,9 +66,9 @@ Load the new CSS file into the CMS, by setting the `LeftAndMain.extra_requiremen ```yml - LeftAndMain: - extra_requirements_css: - - mysite/css/BookmarkedPages.css + LeftAndMain: + extra_requirements_css: + - mysite/css/BookmarkedPages.css ``` ## Create a "bookmark" flag on pages @@ -80,23 +80,23 @@ and insert the following code. ```php - use SilverStripe\Forms\CheckboxField; - use SilverStripe\ORM\DataExtension; + use SilverStripe\Forms\CheckboxField; + use SilverStripe\ORM\DataExtension; - class BookmarkedPageExtension extends DataExtension - { + class BookmarkedPageExtension extends DataExtension + { - private static $db = [ - 'IsBookmarked' => 'Boolean' - ]; + private static $db = [ + 'IsBookmarked' => 'Boolean' + ]; - public function updateCMSFields(FieldList $fields) - { - $fields->addFieldToTab('Root.Main', - new CheckboxField('IsBookmarked', "Show in CMS bookmarks?") - ); - } - } + public function updateCMSFields(FieldList $fields) + { + $fields->addFieldToTab('Root.Main', + new CheckboxField('IsBookmarked', "Show in CMS bookmarks?") + ); + } + } ``` @@ -105,9 +105,9 @@ Enable the extension in your [configuration file](../../configuration) ```yml - SiteTree: - extensions: - - BookmarkedPageExtension + SiteTree: + extensions: + - BookmarkedPageExtension ``` In order to add the field to the database, run a `dev/build/?flush=all`. @@ -124,17 +124,17 @@ Add the following code to a new file `mysite/code/BookmarkedLeftAndMainExtension ```php - use Page; - use SilverStripe\Admin\LeftAndMainExtension; + use Page; + use SilverStripe\Admin\LeftAndMainExtension; - class BookmarkedPagesLeftAndMainExtension extends LeftAndMainExtension - { + class BookmarkedPagesLeftAndMainExtension extends LeftAndMainExtension + { - public function BookmarkedPages() - { - return Page::get()->filter("IsBookmarked", 1); - } - } + public function BookmarkedPages() + { + return Page::get()->filter("IsBookmarked", 1); + } + } ``` Enable the extension in your [configuration file](../../configuration) @@ -142,9 +142,9 @@ Enable the extension in your [configuration file](../../configuration) ```yml - LeftAndMain: - extensions: - - BookmarkedPagesLeftAndMainExtension + LeftAndMain: + extensions: + - BookmarkedPagesLeftAndMainExtension ``` As the last step, replace the hardcoded links with our list from the database. @@ -154,14 +154,14 @@ and replace it with the following: ```ss -
          - - <% loop $BookmarkedPages %> -
        • -
        • Edit "$Title"
          • - - <% end_loop %> -
        +
          + + <% loop $BookmarkedPages %> +
        • +
        • Edit "$Title"
          • + + <% end_loop %> +
        ``` ## Extending the CMS actions @@ -196,7 +196,7 @@ button group (`CompositeField`) in a similar fashion. ```php - $fields->unshift(FormAction::create('normal', 'Normal button')); + $fields->unshift(FormAction::create('normal', 'Normal button')); ``` We can affect the existing button group by manipulating the `CompositeField` @@ -204,7 +204,7 @@ already present in the `FieldList`. ```php - $fields->fieldByName('MajorActions')->push(FormAction::create('grouped', 'New group button')); + $fields->fieldByName('MajorActions')->push(FormAction::create('grouped', 'New group button')); ``` Another option is adding actions into the drop-up - best place for placing @@ -212,7 +212,7 @@ infrequently used minor actions. ```php - $fields->addFieldToTab('ActionMenus.MoreOptions', FormAction::create('minor', 'Minor action')); + $fields->addFieldToTab('ActionMenus.MoreOptions', FormAction::create('minor', 'Minor action')); ``` We can also easily create new drop-up menus by defining new tabs within the @@ -220,7 +220,7 @@ We can also easily create new drop-up menus by defining new tabs within the ```php - $fields->addFieldToTab('ActionMenus.MyDropUp', FormAction::create('minor', 'Minor action in a new drop-up')); + $fields->addFieldToTab('ActionMenus.MyDropUp', FormAction::create('minor', 'Minor action in a new drop-up')); ```
        @@ -244,20 +244,20 @@ applicable controller actions to it: ```php - use SilverStripe\Admin\LeftAndMainExtension; + use SilverStripe\Admin\LeftAndMainExtension; - class CustomActionsExtension extends LeftAndMainExtension - { - - private static $allowed_actions = [ - 'sampleAction' - ]; - - public function sampleAction() - { - // Create the web - } - + class CustomActionsExtension extends LeftAndMainExtension + { + + private static $allowed_actions = [ + 'sampleAction' + ]; + + public function sampleAction() + { + // Create the web + } + } ``` @@ -267,16 +267,16 @@ The extension then needs to be registered: ```yaml - LeftAndMain: - extensions: - - CustomActionsExtension + LeftAndMain: + extensions: + - CustomActionsExtension ``` You can now use these handlers with your buttons: ```php - $fields->push(FormAction::create('sampleAction', 'Perform Sample Action')); + $fields->push(FormAction::create('sampleAction', 'Perform Sample Action')); ``` ## Summary diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md index 46b32d864..6c7c4d30c 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md @@ -5,16 +5,16 @@ also another tool at your disposal: The [Extension](api:SilverStripe\Core\Extens ```php - use SilverStripe\Core\Extension; + use SilverStripe\Core\Extension; - class MyAdminExtension extends Extension - { - // ... - public function updateEditForm(&$form) - { - $form->Fields()->push(/* ... */) - } - } + class MyAdminExtension extends Extension + { + // ... + public function updateEditForm(&$form) + { + $form->Fields()->push(/* ... */) + } + } ``` Now enable this extension through your `[config.yml](/topics/configuration)` file. @@ -22,9 +22,9 @@ Now enable this extension through your `[config.yml](/topics/configuration)` fil ```yml - MyAdmin: - extensions: - - MyAdminExtension + MyAdmin: + extensions: + - MyAdminExtension ``` The following extension points are available: `updateEditForm()`, `updateSearchContext()`, diff --git a/docs/en/02_Developer_Guides/16_Execution_Pipeline/01_Flushable.md b/docs/en/02_Developer_Guides/16_Execution_Pipeline/01_Flushable.md index 36426645f..2abd1ac0e 100644 --- a/docs/en/02_Developer_Guides/16_Execution_Pipeline/01_Flushable.md +++ b/docs/en/02_Developer_Guides/16_Execution_Pipeline/01_Flushable.md @@ -20,31 +20,31 @@ This example uses [Cache](api:Cache) in some custom code, and the same cache is ```php - use SilverStripe\ORM\DataObject; - use SilverStripe\Core\Injector\Injector; - use SilverStripe\Core\Flushable; - use Psr\SimpleCache\CacheInterface; + use SilverStripe\ORM\DataObject; + use SilverStripe\Core\Injector\Injector; + use SilverStripe\Core\Flushable; + use Psr\SimpleCache\CacheInterface; - class MyClass extends DataObject implements Flushable - { - - public static function flush() - { - Injector::inst()->get(CacheInterface::class . '.mycache')->clear(); - } - - public function MyCachedContent() - { - $cache = Injector::inst()->get(CacheInterface::class . '.mycache') - $something = $cache->get('mykey'); - if(!$something) { - $something = 'value to be cached'; - $cache->set('mykey', $something); - } - return $something; - } - - } + class MyClass extends DataObject implements Flushable + { + + public static function flush() + { + Injector::inst()->get(CacheInterface::class . '.mycache')->clear(); + } + + public function MyCachedContent() + { + $cache = Injector::inst()->get(CacheInterface::class . '.mycache') + $something = $cache->get('mykey'); + if(!$something) { + $something = 'value to be cached'; + $cache->set('mykey', $something); + } + return $something; + } + + } ``` ### Using with filesystem @@ -54,18 +54,18 @@ useful in an example like `GD` or `Imagick` generating resampled images, but we flush so they are re-created on demand. ```php - use SilverStripe\ORM\DataObject; - use SilverStripe\Core\Flushable; + use SilverStripe\ORM\DataObject; + use SilverStripe\Core\Flushable; - class MyClass extends DataObject implements Flushable - { - - public static function flush() - { - foreach(glob(ASSETS_PATH . '/_tempfiles/*.jpg') as $file) { - unlink($file); - } - } - - } + class MyClass extends DataObject implements Flushable + { + + public static function flush() + { + foreach(glob(ASSETS_PATH . '/_tempfiles/*.jpg') as $file) { + unlink($file); + } + } + + } ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/17_CLI/index.md b/docs/en/02_Developer_Guides/17_CLI/index.md index 74b66d362..67ce6319b 100644 --- a/docs/en/02_Developer_Guides/17_CLI/index.md +++ b/docs/en/02_Developer_Guides/17_CLI/index.md @@ -10,8 +10,8 @@ The main entry point for any command line execution is `framework/cli-script.php rebuild from the command line, use this command: ```bash - cd your-webroot/ - php framework/cli-script.php dev/build + cd your-webroot/ + php framework/cli-script.php dev/build ```
        @@ -34,8 +34,8 @@ when running the command php -v, then you may not have php-cli installed so sake `sake` can be invoked using `./framework/sake`. For easier access, copy the `sake` file into `/usr/bin/sake`. ``` - cd your-webroot/ - sudo ./framework/sake installsake + cd your-webroot/ + sudo ./framework/sake installsake ```
        This currently only works on UNIX like systems, not on Windows. @@ -60,23 +60,23 @@ Sake can run any controller by passing the relative URL to that controller. ```bash - sake / - # returns the homepage + sake / + # returns the homepage - sake dev/ - # shows a list of development operations + sake dev/ + # shows a list of development operations ``` Sake is particularly useful for running build tasks. ```bash - sake dev/build "flush=1" + sake dev/build "flush=1" ``` It can also be handy if you have a long running script.. ```bash - sake dev/tasks/MyReallyLongTask + sake dev/tasks/MyReallyLongTask ``` ### Running processes @@ -93,28 +93,28 @@ This code provides a good template: ```php - use SilverStripe\Control\Controller; + use SilverStripe\Control\Controller; - class MyProcess extends Controller - { + class MyProcess extends Controller + { - private static $allowed_actions = [ - 'index' - ]; + private static $allowed_actions = [ + 'index' + ]; - function index() { - set_time_limit(0); + function index() { + set_time_limit(0); - while(memory_get_usage() < 32*1024*1024) { - if($this->somethingToDo()) { - $this->doSomething(); - sleep(1) - } else { - sleep(300); - } - } - } - } + while(memory_get_usage() < 32*1024*1024) { + if($this->somethingToDo()) { + $this->doSomething(); + sleep(1) + } else { + sleep(300); + } + } + } + } ``` @@ -123,8 +123,8 @@ Then the process can be managed through `sake` ```bash - sake -start MyProcess - sake -stop MyProcess + sake -start MyProcess + sake -stop MyProcess ```
        @@ -138,8 +138,8 @@ Parameters can be added to the command. All parameters will be available in `$_G ```bash - cd your-webroot/ - php framework/cli-script.php myurl myparam=1 myotherparam=2 + cd your-webroot/ + php framework/cli-script.php myurl myparam=1 myotherparam=2 ``` Or if you're using `sake` @@ -147,7 +147,7 @@ Or if you're using `sake` ```bash - sake myurl "myparam=1&myotherparam=2" + sake myurl "myparam=1&myotherparam=2" ``` ## Running Regular Tasks With Cron @@ -158,5 +158,5 @@ On a UNIX machine, you can typically run a scheduled task with a [cron job](http The following will run `MyTask` every minute. ```bash - * * * * * /your/site/folder/sake dev/tasks/MyTask + * * * * * /your/site/folder/sake dev/tasks/MyTask ``` \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/01_Cookies.md b/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/01_Cookies.md index 850db5518..7656d357e 100644 --- a/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/01_Cookies.md +++ b/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/01_Cookies.md @@ -15,9 +15,9 @@ Sets the value of cookie with configuration. ```php - Cookie::set($name, $value, $expiry = 90, $path = null, $domain = null, $secure = false, $httpOnly = false); + Cookie::set($name, $value, $expiry = 90, $path = null, $domain = null, $secure = false, $httpOnly = false); - // Cookie::set('MyApplicationPreference', 'Yes'); + // Cookie::set('MyApplicationPreference', 'Yes'); ``` ### get @@ -26,10 +26,10 @@ Returns the value of cookie. ```php - Cookie::get($name); + Cookie::get($name); - // Cookie::get('MyApplicationPreference'); - // returns 'Yes' + // Cookie::get('MyApplicationPreference'); + // returns 'Yes' ``` ### force_expiry @@ -38,9 +38,9 @@ Clears a given cookie. ```php - Cookie::force_expiry($name, $path = null, $domain = null); + Cookie::force_expiry($name, $path = null, $domain = null); - // Cookie::force_expiry('MyApplicationPreference') + // Cookie::force_expiry('MyApplicationPreference') ``` ## Cookie_Backend @@ -54,15 +54,15 @@ from the browser. ```php - $myCookies = [ - 'cookie1' => 'value1', - ]; + $myCookies = [ + 'cookie1' => 'value1', + ]; - $newBackend = new CookieJar($myCookies); + $newBackend = new CookieJar($myCookies); - Injector::inst()->registerService($newBackend, 'Cookie_Backend'); + Injector::inst()->registerService($newBackend, 'Cookie_Backend'); - Cookie::get('cookie1'); + Cookie::get('cookie1'); ``` @@ -74,9 +74,9 @@ create a new service for you using the `$_COOKIE` superglobal. ```php - Injector::inst()->unregisterNamedObject('Cookie_Backend'); + Injector::inst()->unregisterNamedObject('Cookie_Backend'); - Cookie::get('cookiename'); // will return $_COOKIE['cookiename'] if set + Cookie::get('cookiename'); // will return $_COOKIE['cookiename'] if set ``` Alternatively, if you know that the superglobal has been changed (or you aren't sure it hasn't) you can attempt to use @@ -84,11 +84,11 @@ the current `CookieJar` service to tell you what it was like when it was registe ```php - //store the cookies that were loaded into the `CookieJar` - $recievedCookie = Cookie::get_inst()->getAll(false); + //store the cookies that were loaded into the `CookieJar` + $recievedCookie = Cookie::get_inst()->getAll(false); - //set a new `CookieJar` - Injector::inst()->registerService(new CookieJar($recievedCookie), 'CookieJar'); + //set a new `CookieJar` + Injector::inst()->registerService(new CookieJar($recievedCookie), 'CookieJar'); ``` ### Using your own Cookie_Backend @@ -98,13 +98,13 @@ If you need to implement your own Cookie_Backend you can use the injector system ```yml - --- - Name: mycookie - After: '#cookie' - --- - Injector: - Cookie_Backend: - class: MyCookieJar + --- + Name: mycookie + After: '#cookie' + --- + Injector: + Cookie_Backend: + class: MyCookieJar ``` To be a valid backend your class must implement the [Cookie_Backend](api:SilverStripe\Control\Cookie_Backend) interface. @@ -120,12 +120,12 @@ Using the `Cookie_Backend` we can do this like such: ```php - Cookie::set('CookieName', 'CookieVal'); + Cookie::set('CookieName', 'CookieVal'); - Cookie::get('CookieName'); //gets the cookie as we set it + Cookie::get('CookieName'); //gets the cookie as we set it - //will return the cookie as it was when it was sent in the request - Cookie::get('CookieName', false); + //will return the cookie as it was when it was sent in the request + Cookie::get('CookieName', false); ``` ### Accessing all the cookies at once @@ -134,9 +134,9 @@ One can also access all of the cookies in one go using the `Cookie_Backend` ```php - Cookie::get_inst()->getAll(); //returns all the cookies including ones set during the current process + Cookie::get_inst()->getAll(); //returns all the cookies including ones set during the current process - Cookie::get_inst()->getAll(false); //returns all the cookies in the request + Cookie::get_inst()->getAll(false); //returns all the cookies in the request ``` ## API Documentation diff --git a/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md b/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md index d7be7eb2d..d47116da3 100644 --- a/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md +++ b/docs/en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md @@ -19,10 +19,10 @@ use SilverStripe\Control\Controller; class MyController extends Controller { - public function MySession() - { - return $this->getRequest()->getSession(); - } + public function MySession() + { + return $this->getRequest()->getSession(); + } } ``` @@ -37,7 +37,7 @@ $session = $request->getSession(); ```php - $session->set('MyValue', 6); + $session->set('MyValue', 6); ``` Saves the value of to session data. You can also save arrays or serialized objects in session (but note there may be @@ -45,12 +45,12 @@ size restrictions as to how much you can save). ```php - // saves an array - $session->set('MyArrayOfValues', ['1','2','3']); + // saves an array + $session->set('MyArrayOfValues', ['1','2','3']); - // saves an object (you'll have to unserialize it back) - $object = new Object(); - $session->set('MyObject', serialize($object)); + // saves an object (you'll have to unserialize it back) + $object = new Object(); + $session->set('MyObject', serialize($object)); ``` @@ -62,14 +62,14 @@ can use this anywhere in your PHP files. ```php - echo $session->get('MyValue'); - // returns 6 + echo $session->get('MyValue'); + // returns 6 - $data = $session->get('MyArrayOfValues'); - // $data = array(1,2,3) + $data = $session->get('MyArrayOfValues'); + // $data = array(1,2,3) - $object = unserialize($session->get('MyObject', $object)); - // $object = Object() + $object = unserialize($session->get('MyObject', $object)); + // $object = Object() ``` @@ -77,8 +77,8 @@ can use this anywhere in your PHP files. You can also get all the values in the session at once. This is useful for debugging. ```php - $session->getAll(); - // returns an array of all the session values. + $session->getAll(); + // returns an array of all the session values. ``` @@ -87,13 +87,13 @@ You can also get all the values in the session at once. This is useful for debug Once you have accessed a value from the Session it doesn't automatically wipe the value from the Session, you have to specifically remove it. ```php - $session->clear('MyValue'); + $session->clear('MyValue'); ``` Or you can clear every single value in the session at once. Note SilverStripe stores some of its own session data including form and page comment information. None of this is vital but `clear_all` will clear everything. ```php - $session->clearAll(); + $session->clearAll(); ``` ## Secure Session Cookie diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index 408c30179..390d19d75 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -15,8 +15,8 @@ For projects managed through Composer, update the version number of `framework` ```json "require": { - "silverstripe/framework": "^4.0", - "silverstripe/cms": "^4.0" + "silverstripe/framework": "^4.0", + "silverstripe/cms": "^4.0" } ``` diff --git a/docs/en/04_Changelogs/2.3.0.md b/docs/en/04_Changelogs/2.3.0.md index 7d70ed146..4214dd165 100644 --- a/docs/en/04_Changelogs/2.3.0.md +++ b/docs/en/04_Changelogs/2.3.0.md @@ -114,19 +114,19 @@ specifies "these are arguments to the controller". In other words, change this: - :::php +```php Director::addRules(50, array( 'admin/ImageEditor/$Action' => 'ImageEditor', )); - +``` To this: - :::php +```php Director::addRules(50, array( 'admin/ImageEditor//$Action' => 'ImageEditor', )); - +``` ### Decorators @@ -213,8 +213,9 @@ In most cases this won't have any effect on existing forms, although you might g like Validator.js and behaviour.js. If you want to disable JavaScript validation across forms, add the following to your _config.php: - :::php +```php Validator::set_javascript_validation_handler('none'); +``` See http://open.silverstripe.com/changeset/69688 diff --git a/docs/en/04_Changelogs/2.3.2.md b/docs/en/04_Changelogs/2.3.2.md index ee5ce8ed6..fa4536834 100644 --- a/docs/en/04_Changelogs/2.3.2.md +++ b/docs/en/04_Changelogs/2.3.2.md @@ -73,7 +73,7 @@ can access them. In particular the following static variables have been changed Because of this, you will need to change the static definitions in your ModelAdmin subclasses. For example, you should change this: - :::php +```php class MyCatalogAdmin extends ModelAdmin { @@ -84,11 +84,11 @@ change this: ... } - +``` To this: - :::php +```php class MyCatalogAdmin extends ModelAdmin { @@ -99,7 +99,7 @@ To this: ... } - +``` #### Deprecated Translatable::enable() diff --git a/docs/en/04_Changelogs/2.4.0.md b/docs/en/04_Changelogs/2.4.0.md index 36dc3fbfb..413fbc81c 100644 --- a/docs/en/04_Changelogs/2.4.0.md +++ b/docs/en/04_Changelogs/2.4.0.md @@ -129,9 +129,9 @@ post](http://www.silverstripe.org/preview-of-silverstripe-2-4-hierarchical-urls- You can enable it manually for existing websites. Existing URLs will automatically change to the nested format without republication (your old URLs should redirect automatically). - :::php +```php SiteTree::enable_nested_urls(); - +``` ### SiteTree->Link() instead of SiteTree->URLSegment diff --git a/docs/en/04_Changelogs/3.1.19.md b/docs/en/04_Changelogs/3.1.19.md index 763b3a304..e2cbda487 100644 --- a/docs/en/04_Changelogs/3.1.19.md +++ b/docs/en/04_Changelogs/3.1.19.md @@ -13,12 +13,12 @@ use SilverStripe\Security\MemberAuthenticator\MemberLoginForm; class CustomLoginForm extends MemberLoginForm { - public function __construct($controller, $name, $fields = null, $actions = null, $checkCurrentUser = true) - { - parent::__construct($controller, $name, $fields, $actions, $checkCurrentUser); + public function __construct($controller, $name, $fields = null, $actions = null, $checkCurrentUser = true) + { + parent::__construct($controller, $name, $fields, $actions, $checkCurrentUser); - $this->disableSecurityToken(); - } + $this->disableSecurityToken(); + } } ``` diff --git a/docs/en/04_Changelogs/3.2.4.md b/docs/en/04_Changelogs/3.2.4.md index d11b52cab..87c4fa596 100644 --- a/docs/en/04_Changelogs/3.2.4.md +++ b/docs/en/04_Changelogs/3.2.4.md @@ -13,12 +13,12 @@ use SilverStripe\Security\MemberAuthenticator\MemberLoginForm; class CustomLoginForm extends MemberLoginForm { - public function __construct($controller, $name, $fields = null, $actions = null, $checkCurrentUser = true) - { - parent::__construct($controller, $name, $fields, $actions, $checkCurrentUser); + public function __construct($controller, $name, $fields = null, $actions = null, $checkCurrentUser = true) + { + parent::__construct($controller, $name, $fields, $actions, $checkCurrentUser); - $this->disableSecurityToken(); - } + $this->disableSecurityToken(); + } } ``` diff --git a/docs/en/04_Changelogs/3.3.2.md b/docs/en/04_Changelogs/3.3.2.md index 6ef64c184..02e4ed9d1 100644 --- a/docs/en/04_Changelogs/3.3.2.md +++ b/docs/en/04_Changelogs/3.3.2.md @@ -13,12 +13,12 @@ use SilverStripe\Security\MemberAuthenticator\MemberLoginForm; class CustomLoginForm extends MemberLoginForm { - public function __construct($controller, $name, $fields = null, $actions = null, $checkCurrentUser = true) - { - parent::__construct($controller, $name, $fields, $actions, $checkCurrentUser); + public function __construct($controller, $name, $fields = null, $actions = null, $checkCurrentUser = true) + { + parent::__construct($controller, $name, $fields, $actions, $checkCurrentUser); - $this->disableSecurityToken(); - } + $this->disableSecurityToken(); + } } ``` diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index 75235a9a4..6ccf9e757 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -116,7 +116,7 @@ For example, the below shows how you would update a query with a hard-coded tabl ```diff public function countDuplicates($model, $fieldToCheck) { - $query = new SilverStripe\ORM\Queries\SQLSelect(); + $query = new SilverStripe\ORM\Queries\SQLSelect(); + $table = SilverStripe\ORM\DataObject::getSchema()->tableForField($model, $field); - $query->setFrom("\"{$model}\""); + $query->setFrom("\"{$table}\""); @@ -605,11 +605,11 @@ use SilverStripe\Core\Convert; class MyObject extends ViewableData { - public function getSomeHTML - { - $title = Convert::raw2xml($this->Title); - return "

        {$title}

        "; - } + public function getSomeHTML + { + $title = Convert::raw2xml($this->Title); + return "

        {$title}

        "; + } } ``` @@ -618,15 +618,15 @@ After: ```php class MyObject extends SilverStripe\View\ViewableData { - private static $casting = [ - 'SomeHTML' => 'HTMLText' - ]; + private static $casting = [ + 'SomeHTML' => 'HTMLText' + ]; - public function getSomeHTML + public function getSomeHTML { - $title = SilverStripe\Core\Convert::raw2xml($this->Title); - return "

        {$title}

        "; - } + $title = SilverStripe\Core\Convert::raw2xml($this->Title); + return "

        {$title}

        "; + } } ``` @@ -852,12 +852,12 @@ is intended to upload images for manipulation. ```diff -if($file instanceof Image) { -- $upload = new UploadField(); -- $upload->setAllowedFileCategories('image'); +- $upload = new UploadField(); +- $upload->setAllowedFileCategories('image'); -} +if ($file->getIsImage()) { -+ $upload = new UploadField(); -+ $upload->setAllowedFileCategories('image/supported'); ++ $upload = new UploadField(); ++ $upload->setAllowedFileCategories('image/supported'); +} ``` @@ -867,12 +867,12 @@ an `Image` datatype, or refer to `DBFile('image/supported')`. ```php class MyObject extends SilverStripe\ORM\DataObject { - private static $has_one = [ - "ImageObject" => "Image" - ]; - private static $db = [ - "ImageField" => "DBFile('image/supported')" - ]; + private static $has_one = [ + "ImageObject" => "Image" + ]; + private static $db = [ + "ImageField" => "DBFile('image/supported')" + ]; } ``` @@ -889,18 +889,18 @@ You would need to upgrade your code as below. ```diff -function importTempFile($tmp) -{ -- copy($tmp, ASSETS_PATH . '/imported/' . basename($tmp)); -- $file = new File(); -- $file->setFilename('assets/imported/'.basename($tmp)); -- $file->write(); +- copy($tmp, ASSETS_PATH . '/imported/' . basename($tmp)); +- $file = new File(); +- $file->setFilename('assets/imported/'.basename($tmp)); +- $file->write(); -} +public function importTempFile($tmp) +{ + Versioned::reading_stage('Stage'); + $file = new File(); + $file->setFromLocalFile($tmp, 'imported/' . basename($tmp)); -+ $file->write(); -+ $file->doPublish(); ++ $file->write(); ++ $file->doPublish(); +} ``` @@ -939,15 +939,15 @@ Before: // in MyImageExtension.php class MyImageExtension extends SilverStripe\ORM\DataExtension { - public function GalleryThumbnail($height) + public function GalleryThumbnail($height) { - return $this->getFormattedImage('GalleryThumbnail', $height); - } + return $this->getFormattedImage('GalleryThumbnail', $height); + } - public function generateGalleryThumbnail(Image_Backend $backend, $height) + public function generateGalleryThumbnail(Image_Backend $backend, $height) { - return $backend->paddedResize(300, $height); - } + return $backend->paddedResize(300, $height); + } } // in _config.php @@ -962,17 +962,17 @@ use SilverStripe\Assets\File; // in MyImageExtension.php class MyImageExtension extends SilverStripe\Core\Extension { - public function GalleryThumbnail($height) + public function GalleryThumbnail($height) { - // Generates the manipulation key - $variant = $this->owner->variantName(__FUNCTION__, $height); + // Generates the manipulation key + $variant = $this->owner->variantName(__FUNCTION__, $height); - // Instruct the backend to search for an existing variant with this key, - // and include a callback used to generate this image if it doesn't exist - return $this->owner->manipulateImage($variant, function (Image_Backend $backend) use ($height) { - return $backend->paddedResize(300, $height); - }); - } + // Instruct the backend to search for an existing variant with this key, + // and include a callback used to generate this image if it doesn't exist + return $this->owner->manipulateImage($variant, function (Image_Backend $backend) use ($height) { + return $backend->paddedResize(300, $height); + }); + } } // in _config.php @@ -1007,7 +1007,7 @@ class MyShortcodeUser extends Object { - private $content; + private $content; public function Content($arguments, $parser, $shortcode) { @@ -1027,7 +1027,7 @@ class MyShortcodeUser extends Object { - private $content; + private $content; public function Content($arguments, $parser, $shortcode) { @@ -1048,17 +1048,17 @@ use SilverStripe\ORM\FieldType\DBComposite; class MyAddressField extends DBComposite { - private static $composite_db = [ - 'Street' => 'Varchar(200)', - 'Suburb' => 'Varchar(100)', - 'City' => 'Varchar(100)', - 'Country' => 'Varchar(100)' - ]; + private static $composite_db = [ + 'Street' => 'Varchar(200)', + 'Suburb' => 'Varchar(100)', + 'City' => 'Varchar(100)', + 'Country' => 'Varchar(100)' + ]; - public function scaffoldFormField($title = null, $params = null) + public function scaffoldFormField($title = null, $params = null) { - new SilverStripe\Forms\TextField($this->getName(), $title); - } + new SilverStripe\Forms\TextField($this->getName(), $title); + } } ``` @@ -1114,11 +1114,11 @@ Before: ```php function augmentSQL(SQLQuery &$query, DataQuery &$dataQuery = null) { - $locale = Translatable::get_current_locale(); - if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere()))) { - $qry = sprintf('"Locale" = \'%s\'', Convert::raw2sql($locale)); - $query->addWhere($qry); - } + $locale = Translatable::get_current_locale(); + if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere()))) { + $qry = sprintf('"Locale" = \'%s\'', Convert::raw2sql($locale)); + $query->addWhere($qry); + } } ``` @@ -1127,12 +1127,12 @@ After: ```php public function augmentSQL(SQLSelect $query, DataQuery $dataQuery = null) { - $locale = Translatable::get_current_locale(); - if (!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhereParameterised($parameters)))) { - $query->addWhere([ - '"Locale"' => $locale - ]); - } + $locale = Translatable::get_current_locale(); + if (!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhereParameterised($parameters)))) { + $query->addWhere([ + '"Locale"' => $locale + ]); + } } ``` @@ -1242,9 +1242,9 @@ use SilverStripe\ORM\DataObject; */ class MyStagedModel extends SilverStripe\ORM\DataObject { - private staic $extensions = [ - "SilverStripe\\ORM\\Versioning\\Versioned('StagedVersioned')" - ]; + private staic $extensions = [ + "SilverStripe\\ORM\\Versioning\\Versioned('StagedVersioned')" + ]; } /** @@ -1252,9 +1252,9 @@ class MyStagedModel extends SilverStripe\ORM\DataObject */ class MyVersionedModel extends DataObject { - private static $extensions = [ - "SilverStripe\\ORM\\Versioning\\Versioned('Versioned')" - ]; + private static $extensions = [ + "SilverStripe\\ORM\\Versioning\\Versioned('Versioned')" + ]; } ``` diff --git a/docs/en/05_Contributing/01_Code.md b/docs/en/05_Contributing/01_Code.md index 71062ab8e..31db7224a 100644 --- a/docs/en/05_Contributing/01_Code.md +++ b/docs/en/05_Contributing/01_Code.md @@ -213,14 +213,14 @@ Further guidelines: Example: Bad commit message ``` - finally fixed this dumb rendering bug that Joe talked about ... LOL - also added another form field for password validation + finally fixed this dumb rendering bug that Joe talked about ... LOL + also added another form field for password validation ``` Example: Good commit message ``` - BUG Formatting through prepValueForDB() + BUG Formatting through prepValueForDB() - Added prepValueForDB() which is called on DBField->writeToManipulation() - to ensure formatting of value before insertion to DB on a per-DBField type basis (fixes #1234). - Added documentation for DBField->writeToManipulation() (related to a4bd42fd). + Added prepValueForDB() which is called on DBField->writeToManipulation() + to ensure formatting of value before insertion to DB on a per-DBField type basis (fixes #1234). + Added documentation for DBField->writeToManipulation() (related to a4bd42fd). ``` diff --git a/docs/en/05_Contributing/04_Release_Process.md b/docs/en/05_Contributing/04_Release_Process.md index 419b9e4b6..c8acc6d6f 100644 --- a/docs/en/05_Contributing/04_Release_Process.md +++ b/docs/en/05_Contributing/04_Release_Process.md @@ -63,15 +63,15 @@ Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::i ```php - /** - * Returns true if your are in development mode - * @deprecated 4.0 Use {@link Env::is_dev()} instead. - */ - public function isDev() - { - Deprecation::notice('4.0', 'Use Env::is_dev() instead'); - return Env::is_dev(); - } + /** + * Returns true if your are in development mode + * @deprecated 4.0 Use {@link Env::is_dev()} instead. + */ + public function isDev() + { + Deprecation::notice('4.0', 'Use Env::is_dev() instead'); + return Env::is_dev(); + } ``` This change could be committed to a minor release like *3.2.0*, and remains deprecated in all subsequent minor releases diff --git a/docs/en/05_Contributing/06_Documentation.md b/docs/en/05_Contributing/06_Documentation.md index 160e6bbef..01ce1b3c0 100644 --- a/docs/en/05_Contributing/06_Documentation.md +++ b/docs/en/05_Contributing/06_Documentation.md @@ -91,9 +91,9 @@ sparingly. Code for a Tip box: ``` -
        - ... -
        +
        + ... +
        ```
        "Notification box": A notification box is good for technical notifications relating to the main text. For example, notifying users about a deprecated feature. @@ -101,9 +101,9 @@ Code for a Tip box: Code for a Notification box: ``` -
        - ... -
        +
        + ... +
        ```
        "Warning box": A warning box is useful for highlighting a severe bug or a technical issue requiring a user's attention. For example, suppose a rare edge case sometimes leads to a variable being overwritten incorrectly. A warning box can be used to alert the user to this case so they can write their own code to handle it. @@ -111,9 +111,9 @@ Code for a Notification box: Code for a Warning box: ``` -
        - ... -
        +
        + ... +
        ``` See [markdown extra documentation](http://michelf.com/projects/php-markdown/extra/#html) for more restrictions on placing HTML blocks inside Markdown. diff --git a/docs/en/05_Contributing/08_Translation_Process.md b/docs/en/05_Contributing/08_Translation_Process.md index db656a9b1..0488d6376 100644 --- a/docs/en/05_Contributing/08_Translation_Process.md +++ b/docs/en/05_Contributing/08_Translation_Process.md @@ -72,12 +72,12 @@ Translations need to be reviewed before being committed, which is a process that merging back translations into all supported release branches as well as the `master` branch. The following script should be applied to the oldest release branch, and then merged forward into newer branches: ```bash - - tx pull + + tx pull - # Manually review changes through git diff, then commit - git add lang/* - git commit -m "Updated translations" + # Manually review changes through git diff, then commit + git add lang/* + git commit -m "Updated translations" ```
        @@ -91,7 +91,7 @@ conversion step involved in order to get those translations syncing with Transif `mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files. ```js - ss.i18n.addDictionary('de', {'MyNamespace.MyKey': 'My Translation'}); + ss.i18n.addDictionary('de', {'MyNamespace.MyKey': 'My Translation'}); ``` But Transifex only accepts structured formats like JSON. @@ -103,30 +103,30 @@ But Transifex only accepts structured formats like JSON. First of all, you need to create those source files in JSON, and store them in `mymodule/javascript/lang/src/*.js`. In your `.tx/config` you can configure this path as a separate master location. ```ruby - [main] - host = https://www.transifex.com + [main] + host = https://www.transifex.com - [silverstripe-mymodule.master] - file_filter = lang/.yml - source_file = lang/en.yml - source_lang = en - type = YML + [silverstripe-mymodule.master] + file_filter = lang/.yml + source_file = lang/en.yml + source_lang = en + type = YML - [silverstripe-mymodule.master-js] - file_filter = javascript/lang/src/.js - source_file = javascript/lang/src/en.js - source_lang = en - type = KEYVALUEJSON + [silverstripe-mymodule.master-js] + file_filter = javascript/lang/src/.js + source_file = javascript/lang/src/en.js + source_lang = en + type = KEYVALUEJSON ``` Then you can upload the source files via a normal `tx push`. Once translations come in, you need to convert the source files back into the JS files SilverStripe can actually read. This requires an installation of our [buildtools](https://github.com/silverstripe/silverstripe-buildtools). ``` - tx pull - (cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module) - git add javascript/lang/* - git commit -m "Updated javascript translations" + tx pull + (cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module) + git add javascript/lang/* + git commit -m "Updated javascript translations" ``` # Related diff --git a/docs/en/05_Contributing/14_PHP_Coding_Conventions.md b/docs/en/05_Contributing/14_PHP_Coding_Conventions.md index cb6a7c129..600cf1f87 100644 --- a/docs/en/05_Contributing/14_PHP_Coding_Conventions.md +++ b/docs/en/05_Contributing/14_PHP_Coding_Conventions.md @@ -27,10 +27,10 @@ As opposed to other variables, these should be declared as lower case with under ```php - class MyClass - { - private static $my_config_variable = 'foo'; - } + class MyClass + { + private static $my_config_variable = 'foo'; + } ``` ## Prefer identical (===) comparisons over equality (==) @@ -40,15 +40,15 @@ Read more in the PHP documentation for [comparison operators](http://php.net/man ```php - // good - only need to cast to (int) if $a might not already be an int - if ((int)$a === 100) { - doThis(); - } - - // bad - if ($a == 100) { - doThis(); - } + // good - only need to cast to (int) if $a might not already be an int + if ((int)$a === 100) { + doThis(); + } + + // bad + if ($a == 100) { + doThis(); + } ``` ## Separation of Logic and Presentation @@ -57,28 +57,28 @@ Try to avoid using PHP's ability to mix HTML into the code. ```php - // PHP code - public function getTitle() - { - return "

        Bad Example

        "; - } + // PHP code + public function getTitle() + { + return "

        Bad Example

        "; + } - // Template code - $Title + // Template code + $Title ``` Better: Keep HTML in template files: ```php - // PHP code - public function getTitle() - { - return "Better Example"; - } + // PHP code + public function getTitle() + { + return "Better Example"; + } - // Template code -

        $Title

        + // Template code +

        $Title

        ``` ## Comments @@ -97,21 +97,21 @@ Example: ```php - /** - * My short description for this class. - * My longer description with - * multiple lines and richer formatting. - * - * Usage: - * - * $c = new MyClass(); - * $c->myMethod(); - * - * - * @package custom - */ - class MyClass extends Class - { + /** + * My short description for this class. + * My longer description with + * multiple lines and richer formatting. + * + * Usage: + * + * $c = new MyClass(); + * $c->myMethod(); + * + * + * @package custom + */ + class MyClass extends Class + { /** * My Method. * This method returns something cool. {@link MyParentMethod} has other cool stuff in it. @@ -124,7 +124,7 @@ Example: // ... } - } + } ``` ## Class Member Ordering @@ -148,7 +148,7 @@ with the column or table name escaped with double quotes as below. ```php - MyClass::get()->where(["\"Score\" > ?" => 50]); + MyClass::get()->where(["\"Score\" > ?" => 50]); ``` @@ -159,7 +159,7 @@ are single quoted. ```php - MyClass::get()->where("\"Title\" = 'my title'"); + MyClass::get()->where("\"Title\" = 'my title'"); ``` Use [ANSI SQL](http://en.wikipedia.org/wiki/SQL#Standardization) format where possible.