DOC Update syntax for callout blocks #449
Conversation
| > [!NOTE] | ||
| > Provided `filter` values are automatically escaped and do not require any escaping. |
There was a problem hiding this comment.
Moved this from below to satisfy MD028 - can't have two block quotes immediately after one another.
| > [!WARNING] | ||
| > Versioning only works if you are adding the extension to the base class. That is, the first subclass | ||
| > of `DataObject`. Adding this extension to children of the base class will have unpredictable behaviour. |
There was a problem hiding this comment.
Moved this from below to satisfy MD028 - can't have two block quotes immediately after one another.
| > [!WARNING] | ||
| > Using `@silverstripe/webpack-config` will keep your transpiled bundle size smaller and ensure you are using the correct versions of `react-apollo` and `graphql-tag`, as these will automatically be added as [webpack externals](https://webpack.js.org/configuration/externals/). If you are not using that npm package, it is very important you use the correct versions of those dependencies. | ||
|
|
There was a problem hiding this comment.
Moved this from above to satisfy MD028 - can't have two block quotes immediately after one another.
| > [!WARNING] | ||
| > If you define a `searchable_fields` configuration, *do not* specify fields that are not stored in the database (such as methods), as this will cause an error. |
There was a problem hiding this comment.
Moved this from above to satisfy MD028 - can't have two block quotes immediately after one another.
| > [!WARNING] | ||
| > If you wish to pass parameters to getter functions, you must use the full method name, e.g. $getThing('param'). Also, parameters must be literals, and cannot be other template variables (`$getThing($variable)` will not work) |
There was a problem hiding this comment.
Moved this from below to satisfy MD028 - can't have two block quotes immediately after one another.
| [notice] | ||
| See the [SearchFilter](../model/searchfilters) documentation for more information about filters to use such as the | ||
| `GreaterThanFilter`. | ||
| [/notice] | ||
| > [!WARNING] | ||
| > In case you need multiple contexts, consider name-spacing your request parameters by using `FieldList->namespace()` on | ||
| > the `$fields` constructor parameter. | ||
|
|
||
| [notice] | ||
| In case you need multiple contexts, consider name-spacing your request parameters by using `FieldList->namespace()` on | ||
| the `$fields` constructor parameter. | ||
| [/notice] | ||
| See the [SearchFilter](../model/searchfilters) documentation for more information about filters to use such as the `GreaterThanFilter`. |
There was a problem hiding this comment.
Reduced to one notice, and one remark that isn't in a callout block. The "see this for more information" doesn't need a callout.
Before this change it violated MD028 - can't have two block quotes immediately after one another.
| > [!NOTE] | ||
| > For the below example to work it is necessary to have the Injector service `App\Cache\Service.memcached` defined somewhere in the configs. |
There was a problem hiding this comment.
Moved this from below to satisfy MD028 - can't have two block quotes immediately after one another.
| [warning] | ||
| If you use the same aggregate in a template more than once, it will be recalculated every time | ||
| unless you move it out into a separate | ||
| [controller method](../templates/partial_template_caching/#cache-key-calculated-in-controller). | ||
| [Object Caching](../templates/caching/#object-caching) only works for single variables and not for chained expressions. | ||
| [/warning] |
There was a problem hiding this comment.
Folded this into the other warning to satisfy MD028 - can't have two block quotes immediately after one another.
| > [!NOTE] | ||
| > The use of the fully qualified classname is necessary. | ||
| > | ||
| > The use of both `.max('LastEdited')` and `.count()` makes sure we check for any object | ||
| > edited or deleted since the cache was last built. |
There was a problem hiding this comment.
Folded the two notes together to satisfy MD028 - can't have two block quotes immediately after one another.
| > [!WARNING] | ||
| > You will need to make sure the user running the PHP process has write access to the log file, wherever you choose to put it. |
There was a problem hiding this comment.
Moved this from below to satisfy MD028 - can't have two block quotes immediately after one another.
| [notice] | ||
| Caveat: `layout` is also triggered when a DOM element is replaced with AJAX in `LeftAndMain::handleAjaxResponse`. In | ||
| this case it is triggered on the parent of the element being replaced so jLayout has a chance to rebuild its algorithms. | ||
| Calling the top level `layout` is not enough as it will wrongly descend down the detached element's hierarchy. | ||
| [/notice] | ||
|
|
||
| [notice] | ||
| Caveat: invocation order of the `redraws` is crucial here, generally going from innermost to outermost elements. For | ||
| example, the tab panels have be applied in the CMS form before the form itself is layouted with its sibling panels to | ||
| avoid incorrect dimensions. | ||
| [/notice] | ||
| > [!WARNING] | ||
| > There are some caveats to this: | ||
| > | ||
| > `layout` is also triggered when a DOM element is replaced with AJAX in `LeftAndMain::handleAjaxResponse`. In | ||
| > this case it is triggered on the parent of the element being replaced so jLayout has a chance to rebuild its algorithms. | ||
| > Calling the top level `layout` is not enough as it will wrongly descend down the detached element's hierarchy. | ||
| > | ||
| > The invocation order of the `redraws` is crucial here, generally going from innermost to outermost elements. For | ||
| > example, the tab panels have be applied in the CMS form before the form itself is layouted with its sibling panels to | ||
| > avoid incorrect dimensions. |
There was a problem hiding this comment.
I've merged these together to satisfy MD028 - can't have two block quotes immediately after one another.
IMPORTANT
This should not be merged until all of the associated PRs have all been approved. Only merge when all of the PRs are ready to go, to minimise the amount of time spent with broken callout blocks.
Description
Converts all of the legacy callout blocks to the new syntax. Note that we're not doing CMS 3.
There will be a separate PR for CMS 5. Lots of the changes will be the same, but there's been enough change between majors that a direct merge up will be a pain in the butt, so I've done two separate PRs. Once they're both merged the merge-up process will literally be to throw away the differences and keep the CMS 5 copy.
Note that most of the callout blocks will be converted as per silverstripe/doc.silverstripe.org#282 (comment) - but there are some which were intentionally changed. I will note those with comments.
If I haven't added a comment on something that has been converted differently than that table suggests, assume I messed up.
Issues
Pull request checklist