Skip to content

Commit

Permalink
DOC Update syntax for callout blocks
Browse files Browse the repository at this point in the history
  • Loading branch information
GuySartorelli committed Jan 30, 2024
1 parent 00ba6a0 commit 182deb4
Show file tree
Hide file tree
Showing 129 changed files with 1,510 additions and 1,925 deletions.
5 changes: 2 additions & 3 deletions en/00_Getting_Started/00_Server_Requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,8 @@ also needs write access for the webserver user to the following locations:
[schema introspection](/developer_guides/graphql/tips_and_tricks#schema-introspection). You should treat this folder
the same way you treat the `.graphql-generated` folder.

[info]
If you are still using silverstripe/graphql 3.x, you do not need the `.graphql-generated` or `public/_graphql` directories.
[/info]
> [!NOTE]
> If you are still using silverstripe/graphql 3.x, you do not need the `.graphql-generated` or `public/_graphql` directories.

If you aren't explicitly [packaging](#building-packaging-deployment)
your Silverstripe CMS project during your deployment process, additional write access may be required to generate supporting
Expand Down
9 changes: 4 additions & 5 deletions en/00_Getting_Started/02_Composer.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,11 +70,10 @@ a [version constraint](http://getcomposer.org/doc/01-basic-usage.md#the-require-
composer require silverstripe/blog ^2
```

[warning]
**Version constraints:** `master` is not a legal version string - it's a branch name. These are different things. The
version string that would get you the branch is `dev-master`. The version string that would get you a numeric branch is
a little different. The version string for the `4` branch is `4.x-dev`.
[/warning]
> [!WARNING]
> **Version constraints:** `master` is not a legal version string - it's a branch name. These are different things. The
> version string that would get you the branch is `dev-master`. The version string that would get you a numeric branch is
> a little different. The version string for the `4` branch is `4.x-dev`.
## Updating dependencies

Expand Down
10 changes: 4 additions & 6 deletions en/00_Getting_Started/03_Environment_Management.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,8 @@ use SilverStripe\Core\Environment;
Environment::setEnv('API_KEY', 'AABBCCDDEEFF012345');
```

[warning]
`Environment::getEnv()` will return `false` whether the variable was explicitly set as `false` or simply wasn't set at all. You can use [`Environment::hasEnv()`](api:SilverStripe\Core\Environment::hasEnv()) to check whether an environment variable was set or not.
[/warning]
> [!WARNING]
> `Environment::getEnv()` will return `false` whether the variable was explicitly set as `false` or simply wasn't set at all. You can use [`Environment::hasEnv()`](api:SilverStripe\Core\Environment::hasEnv()) to check whether an environment variable was set or not.
### Using environment variables in config

Expand All @@ -74,9 +73,8 @@ SilverStripe\Core\Injector\Injector:
ThisWillNotSubstitute: 'lorem `REGULAR_TEXT` ipsum'
```
[info]
Environment variables cannot be used outside of Injector config as of version 4.2.
[/info]
> [!NOTE]
> Environment variables cannot be used outside of Injector config as of version 4.2.
## Including an extra `.env` file

Expand Down
56 changes: 24 additions & 32 deletions en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,9 @@ It **won't** do any of the following
- Rename any tables that it doesn't recognize. This allows other applications to coexist in the same database, as long as
their table names don't match a Silverstripe CMS data class.

[notice]
You need to be logged in as an administrator to perform this command, unless your site is in [dev mode](../debugging),
or the command is run through [CLI](../cli).
[/notice]
> [!WARNING]
> You need to be logged in as an administrator to perform this command, unless your site is in [dev mode](../debugging),
> or the command is run through [CLI](../cli).
When rebuilding the database schema through the [ClassLoader](api:SilverStripe\Core\Manifest\ClassLoader) the following additional properties are
automatically set on the `DataObject`.
Expand Down Expand Up @@ -127,9 +126,8 @@ Or, a better way is to use the `create` method.
$player = Player::create();
```

[notice]
Using the `create()` method provides chainability, which can add elegance and brevity to your code, e.g. `Player::create()->write()`. More importantly, however, it will look up the class in the [Injector](../extending/injector) so that the class can be overridden by [dependency injection](http://en.wikipedia.org/wiki/Dependency_injection).
[/notice]
> [!WARNING]
> Using the `create()` method provides chainability, which can add elegance and brevity to your code, e.g. `Player::create()->write()`. More importantly, however, it will look up the class in the [Injector](../extending/injector) so that the class can be overridden by [dependency injection](http://en.wikipedia.org/wiki/Dependency_injection).
Database columns and properties can be set as class properties on the object. The Silverstripe CMS ORM handles the saving
of the values through a custom `__set()` method.
Expand Down Expand Up @@ -175,6 +173,9 @@ echo $player->dbObject('LastEdited')->Ago();
The `ORM` uses a "fluent" syntax, where you specify a query by chaining together different methods. Two common methods
are `filter()` and `sort()`:

> [!NOTE]
> Provided `filter` values are automatically escaped and do not require any escaping.
```php
$members = Player::get()->filter([
'FirstName' => 'Sam',
Expand All @@ -183,15 +184,10 @@ $members = Player::get()->filter([
// returns a `DataList` containing all the `Player` records that have the `FirstName` of 'Sam'
```

[info]
Provided `filter` values are automatically escaped and do not require any escaping.
[/info]

[info]
`DataObject::get()->byID()` and `DataObject::get_by_id()` achieve similar results, but the object returned by `DataObject::get_by_id()` is cached against a `static` property within `DataObject`.

`DataObject::get_by_id()` is a legacy ORM method, and it is recommended that you use `DataObject::get()->byID()` wherever possible
[/info]
> [!NOTE]
> `DataObject::get()->byID()` and `DataObject::get_by_id()` achieve similar results, but the object returned by `DataObject::get_by_id()` is cached against a `static` property within `DataObject`.
>
> `DataObject::get_by_id()` is a legacy ORM method, and it is recommended that you use `DataObject::get()->byID()` wherever possible
## Lazy loading

Expand Down Expand Up @@ -445,11 +441,10 @@ $teams = Team::get()->filter('Players.Sum(PointsScored):LessThan', 300);
It is also possible to filter by a PHP callback, this will force the data model to fetch all records and loop them in
PHP, thus `filter()` or `filterAny()` are to be preferred over `filterByCallback()`.

[notice]
Because `filterByCallback()` has to run in PHP, it has a significant performance tradeoff, and should not be used on large recordsets.

`filterByCallback()` will always return an `ArrayList`.
[/notice]
> [!WARNING]
> Because `filterByCallback()` has to run in PHP, it has a significant performance tradeoff, and should not be used on large recordsets.
>
> `filterByCallback()` will always return an `ArrayList`.
The first parameter to the callback is the item, the second parameter is the list itself. The callback will run once
for each record, if the callback returns true, this record will be added to the list of returned items.
Expand Down Expand Up @@ -557,9 +552,8 @@ offset, if not provided as an argument, will default to 0.
$members = Member::get()->sort('Surname')->limit(10, 4);
```

[alert]
Note that the `limit` argument order is different from a MySQL LIMIT clause.
[/alert]
> [!CAUTION]
> Note that the `limit` argument order is different from a MySQL LIMIT clause.
### Mapping classes to tables with `DataObjectSchema`

Expand Down Expand Up @@ -657,10 +651,9 @@ $members = Member::get()
->innerJoin('Group_Members', '"Rel"."MemberID" = "Member"."ID"', 'Rel');
```

[alert]
Passing a *$join* statement will filter results further by the JOINs performed against the foreign table. It will
**not** return the additionally joined data.
[/alert]
> [!CAUTION]
> Passing a *$join* statement will filter results further by the JOINs performed against the foreign table. It will
> **not** return the additionally joined data.
### Default values

Expand All @@ -680,10 +673,9 @@ class Player extends DataObject
}
```

[notice]
Note: Alternatively you can set defaults directly in the database-schema (rather than the object-model). See
[Data Types and Casting](/developer_guides/model/data_types_and_casting) for details.
[/notice]
> [!WARNING]
> Note: Alternatively you can set defaults directly in the database-schema (rather than the object-model). See
> [Data Types and Casting](/developer_guides/model/data_types_and_casting) for details.
## Subclasses

Expand Down
69 changes: 31 additions & 38 deletions en/02_Developer_Guides/00_Model/02_Relations.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,29 +148,26 @@ class Fan extends DataObject
}
```

[warning]
Note: The use of polymorphic relationships can affect query performance, especially
on joins, and also increases the complexity of the database and necessary user code.
They should be used sparingly, and only where additional complexity would otherwise
be necessary. For example additional parent classes for each respective relationship, or
duplication of code.
[/warning]
> [!WARNING]
> Note: The use of polymorphic relationships can affect query performance, especially
> on joins, and also increases the complexity of the database and necessary user code.
> They should be used sparingly, and only where additional complexity would otherwise
> be necessary. For example additional parent classes for each respective relationship, or
> duplication of code.
## `has_many`

Defines 1-to-many joins. As you can see from the previous example, `$has_many` goes hand in hand with `$has_one`.

[alert]
Please specify a $has_one-relationship on the related child-class as well, in order to have the necessary accessors
available on both ends. To add a $has_one-relationship on core classes, yml config settings can be used:

```yml
SilverStripe\Assets\Image:
has_one:
App\Model\MyDataObject: MyDataObject
```
[/alert]
> [!CAUTION]
> Please specify a $has_one-relationship on the related child-class as well, in order to have the necessary accessors
> available on both ends. To add a $has_one-relationship on core classes, yml config settings can be used:
>
> ```yml
> SilverStripe\Assets\Image:
> has_one:
> App\Model\MyDataObject: MyDataObject
> ```
```php
namespace App\Model;
Expand Down Expand Up @@ -324,18 +321,16 @@ Defines many-to-many joins, which uses a third table created between the two to
There are two ways in which this can be declared, which are described below, depending on
how the developer wishes to manage this join table.
[warning]
Please specify a $belongs_many_many-relationship on the related class as well, in order
to have the necessary accessors available on both ends. You can use `RelationValidationService` for validation of relationships. This tool will point out the relationships which may need a review.

Example configuration:

```yml
SilverStripe\Dev\Validation\RelationValidationService:
output_enabled: true
```
[/warning]
> [!WARNING]
> Please specify a $belongs_many_many-relationship on the related class as well, in order
> to have the necessary accessors available on both ends. You can use `RelationValidationService` for validation of relationships. This tool will point out the relationships which may need a review.
>
> Example configuration:
>
> ```yml
> SilverStripe\Dev\Validation\RelationValidationService:
> output_enabled: true
> ```
Much like the `has_one` relationship, `many_many` can be navigated through the `ORM` as well.
The only difference being you will get an instance of [ManyManyList](api:SilverStripe\ORM\ManyManyList) or
Expand Down Expand Up @@ -690,10 +685,9 @@ If your object is versioned, cascade_deletes will also act as "cascade unpublish
on a parent object will trigger unpublish on the child, similarly to how `owns` causes triggered publishing.
See the [versioning docs](/developer_guides/model/versioning) for more information on ownership.
[alert]
Declaring cascade_deletes implies delete permissions on the listed objects.
Built-in controllers using delete operations check canDelete() on the owner, but not on the owned object.
[/alert]
> [!CAUTION]
> Declaring cascade_deletes implies delete permissions on the listed objects.
> Built-in controllers using delete operations check canDelete() on the owner, but not on the owned object.
## Cascading duplications
Expand Down Expand Up @@ -793,10 +787,9 @@ class Team extends DataObject
}
```
[notice]
Adding new records to a filtered `RelationList` like in the example above doesn't automatically set the filtered
criteria on the added record.
[/notice]
> [!WARNING]
> Adding new records to a filtered `RelationList` like in the example above doesn't automatically set the filtered
> criteria on the added record.
## Relations on unsaved objects
Expand Down
7 changes: 3 additions & 4 deletions en/02_Developer_Guides/00_Model/05_Extending_DataObjects.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,10 +88,9 @@ class Player extends DataObject
}
```

[notice]
Note: There are no separate methods for `onBeforeCreate()` and `onBeforeUpdate()`. Please check `$this->isInDb()` to toggle
these two modes, as shown in the example above.
[/notice]
> [!WARNING]
> Note: There are no separate methods for `onBeforeCreate()` and `onBeforeUpdate()`. Please check `$this->isInDb()` to toggle
> these two modes, as shown in the example above.
## Related lessons

Expand Down
16 changes: 7 additions & 9 deletions en/02_Developer_Guides/00_Model/07_Permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,9 @@ The API provides four methods for this purpose: `canEdit()`, `canCreate()`, `can
Since they're PHP methods, they can contain arbitrary logic matching your own requirements. They can optionally receive
a `$member` argument, and default to the currently logged in member (through `Security::getCurrentUser()`).

[notice]
By default, all `DataObject` subclasses can only be edited, created and viewed by users with the 'ADMIN' permission
code.
[/notice]
> [!WARNING]
> By default, all `DataObject` subclasses can only be edited, created and viewed by users with the 'ADMIN' permission
> code.
```php
namespace App\Model;
Expand Down Expand Up @@ -49,11 +48,10 @@ class MyDataObject extends DataObject
}
```

[alert]
These checks are not enforced on low-level ORM operations such as `write()` or `delete()`, but rather rely on being
checked in the invoking code. The CMS default sections as well as custom interfaces like [ModelAdmin](api:SilverStripe\Admin\ModelAdmin) or
[GridField](api:SilverStripe\Forms\GridField\GridField) already enforce these permissions.
[/alert]
> [!CAUTION]
> These checks are not enforced on low-level ORM operations such as `write()` or `delete()`, but rather rely on being
> checked in the invoking code. The CMS default sections as well as custom interfaces like [ModelAdmin](api:SilverStripe\Admin\ModelAdmin) or
> [GridField](api:SilverStripe\Forms\GridField\GridField) already enforce these permissions.
## API documentation

Expand Down
7 changes: 3 additions & 4 deletions en/02_Developer_Guides/00_Model/08_SQL_Select.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,9 @@ various assumptions the ORM and code based on it have:
We'll explain some ways to use `SELECT` with the full power of SQL,
but still maintain a connection to the ORM where possible.

[warning]
Please read our [security topic](/developer_guides/security) to find out
how to properly prepare user input and variables for use in queries
[/warning]
> [!WARNING]
> Please read our [security topic](/developer_guides/security) to find out
> how to properly prepare user input and variables for use in queries
## Usage

Expand Down
Loading

0 comments on commit 182deb4

Please sign in to comment.