silverstripe/developer-docs

Developer documentation for Silverstripe CMS

developer-docs's Issues

Migrate update content to changelogs for CMS 5

I started out listing breaking changes in the update docs (with the intention that it would be used to create a more how-to style document later on), and then ended up putting a more how-to write up in the changelogs because that's the kind of content we normally add there - because we normally aren't doing major releases.

I think we should be listing the explicit breaking changes (removed x, use y instead) in the changelog, and then anything that requires further explanation should be in the upgrade docs.

This issue exists both to facilitate discussion about that in case anyone disagrees, and then to actually set up the docs in whichever manner is agreed upon.

Acceptance criteria

• It is clear for CMS 5 which content goes into the update docs and what content goes into the changelog
• CMS5 upgrade guide should be folded back into changelog
• Update existing PR that adds entry to the upgrade guide to target the changelog instead (BLOCKED pending the attached PR being merged)

PRs

• #84

Requirements::add_i18n_javascript() don't work with paths from ModuleResourceLoader::resourceURL()

Affected Version

SS 4.3

Description

Cannot add i18 javascript using ModuleResourceLoader::resourceURL()

Steps to Reproduce

I try to add

Requirements::add_i18n_javascript(
    ModuleResourceLoader::resourceURL('dnadesign/silverstripe-elemental:lang')
);

resourceURL() returns /resources/vendor/dnadesign/silverstripe-elemental/lang

This is treated as absolute path in Director::getAbsFile, therefor the lang file isn't loaded cause the file isn't found.

i18n and translation doc needs updated to account for namespace

A lot of the examples on these two articles need to be updated to account for the fact that our classes are namespaced now.

https://docs.silverstripe.org/en/4/developer_guides/i18n/
https://docs.silverstripe.org/en/4/developer_guides/templates/translations/

Example of lies we are telling

<%t Member.WELCOME 'Welcome {name} to {site}' name=$Member.Name site="Foobar.com" %>

_t('LeftAndMain.FILESIMAGES','Files & Images');

en:
  ImageUploader:
    Attach: 'Attach {title}'
  UploadField:
    NOTEADDFILES: 'You can add files once you have saved for the first time.'

Use relative URLs in docs when linking to other documentation.

There are lots of links in the documentation that use absolute URLs to other documentation where a relative URL should be used. This will be a problem when migrating docs to a new major release branch, where they will then be pointing to documentation for the wrong major.

There are also absolute URLs for links to API (https://api.silverstripe.org/4/Some/Class.html) which should use the (Some\Class)[api:Some\Class] syntax.

Refactor Release doc

Looking at the Making a SilverStripe core release, it's horribly out of date.

For the most part we are going off internal documentation that we haven't shared with the wider public.

The internal release doc would not make much sense as is without some guidance from a CMS Squad member.

I'm thinking either we scrap this entire doc article or we update it to be more generic so people have a general overview of what we do when we do a release.

Acceptance criteria

• Doc is reviewed and bits that are still relevant are identified and move to a suitable place.
• There's some generic doc explaining how we perform Silverstripe CMS. The doc provides a high level overview and is easy to comprehend.

Notes

• spinoff from https://github.com/silverstripe/developer-docs/pull/9/files#r920613700

`assertPartialHTMLMatchBySelector` docs confusion

Affected Version

4.10

Description

The functional test docs suggest that $this->assertPartialHTMLMatchBySelector will test the element content, but the code actually tests against the outerHTML.

That is to say, the example code in the docs will always fail

$this->assertPartialHTMLMatchBySelector("#MyForm_ID p.error", [
    "That email address is invalid."
]);

it would need to be changed to something like this if we expect it to ever work

$this->assertPartialHTMLMatchBySelector("#MyForm_ID p.error", [
    "<p class=\"error\">That email address is invalid.</p>"
]);

---

In my case the result I'm getting is

        $this->assertPartialHTMLMatchBySelector('#SaleAdEditForm_getForm_Create_your_account', ['Create your account']);

1) SaleAdEditorPageTest::testCreateAccountWithListing
Failed asserting the CSS selector '#SaleAdEditForm_getForm_Create_your_account' has a partial match to the expected elements:
'Create your account'

Instead the following elements were found:
'<h2 id="SaleAdEditForm_getForm_Create_your_account">Create your account</h2>'
Failed asserting that false is true.

Add docs for fields that are supported in JS (`FormBuilder`) context

Affected Version

N/A

Description

Currently we support scaffolding forms in JavaScript in modules like asset-admin and elemental. Currently for developers it's not clear at a glance which fields are actually supported. For instance we know that GridField is not supported and ListBoxField is partially supported.

We should add some docs to help developers understand the current support/limitations of the JS form scaffolding functionality.

Review all front-end-related documentation

Our front-end documentation is fractured, outdated, and in some cases potentially misleading. It could do with a review.

Some things to consider:

• https://docs.silverstripe.org/en/4/developer_guides/customising_the_admin_interface/reactjs_redux_and_graphql/#introduction-to-the-react-layer says the react API isn't part of our semver commitment, but that seems to be the only place that mentions it. It certainly isn't mentioned in our major release policy, which is the place where most people will look for that sort of information.
• It would be nice if there was a clearer structure to the doc - currently it seems to find information about javascript development in the CMS we have to traverse all over the place. These should be collected in a single section, ideally (see #41)
  • In particular, the react injector documentation is very difficult to parse. It needs to be split into multiple pages. At the very least, there should be one page that focuses on the API of the react injector, and another that provides concrete step-by-step examples of how to use it in a specific narrow-scope project. At the moment those are mixed together, which ultimately means the step-by-step guide is hard to follow at best, and the documentation about the API isn't clear nor complete. See #215 (comment)
• A lot of our graphql js stuff is outdated (see #62)

Public theme set and template inheritance

Affected Version

4.4

Description

4.1.0 bought in the new $public theme set and I’m finding that the suggested theme order in the change log (https://docs.silverstripe.org/en/4/changelogs/4.1.0/#public-theme) is causing some template inheritance issues when a module is overriding a template that I’m also overriding in my theme.

  themes:
    - '$public'
    - 'mytheme'
    - '$default'

For example https://github.com/unclecheese/silverstripe-display-logic overrides the SilverStripe\Forms\OptionsetField template and I’m also overriding that in my theme. If I put my theme at the top of the list that gets around it but I'm unsure after reading the docs whether that is going to cause any issues. I don’t use the likes of the themedCSS methods so perhaps it doesn’t really matter?

This may even be expected behaviour but thought i'd log anyway for clarity.

Provide a security best practices cheatsheet

Our doc provide a Security page with a dump of best practices. That page is not very readable.

It probably would help to review that page with an eye towards updating the list. We should also aim to separate advice about generic server set up and coding best practices.

We could also aim to structure the list of steps as a "Cheat Sheet" that people can easily reference.

Also relevant is the grahql security and best practices doc

Needs "How to Debug CMS errors" documentation

When I first started using Silverstripe and got any sort of saving/canView errors in the CMS in my own code, I had no idea that I could open the Google Chrome/Firefox developer tools and check the network tab to read the errors, and so I used to always try and quickly retrieve the error before it 'faded away'.

If we want to build a bigger community we need to think about the people that are just dipping their toes into web development too.

https://docs.silverstripe.org/en/3.3/developer_guides/debugging/

Improve Injector Doc

Injector docs are improved and easier to maintained.

Acceptance criteria

• Bernie's change are reviewed and are fit for purpose

Pull request

• #105

Documentation for Access Control and Page Security is invalid

Affected Version

Documentation site

Description

On the documentation site, the Access Control page doesn't contain a lot of useful information, and reads more like a stream of consciousness while someone was reading the code, rather than a useful developer guide. The whole page has this sort of content, but the 'Permission checking is at class level' section is probably the worst offender.

The page should ideally be re-written to properly cover the Access Control model that SilverStripe implements.

I'll try to do this in a PR, but no guarantees - adding this issue in case I don't get a chance to re-write it.

Limit with DataList::filterByCallback is inconsistent.

Affected Version: 4.9+

Description

If you call limit on a DataList, and then call filterByCallback, the data query will first be executed, which gets a limited number of results from the database. This limited result set is then filtered using the callback, which may result in even less results being returned.

This was pointed out by @christopherdarling in the below comment, which perhaps explains it a little more clearly:

that's true but this does unearth the issue of the order you call these methods for example;

1. if you do Page::get()->filterByCallback(fn () => true)->limit(10)->count();, filterByCallback() loops over the entire set of Page rows (possibly 1000's) to do the filter comparison even after the 10th valid item is found which isn't necessary. I think this code change avoids that
2. if you do Page::get()->limit(10)->filterByCallback(fn ($item) => $item->URLSegment !== 'home')->count(); I get 9 records because we're filtering on the 10 records from the database and 1 fails this filter
3. if you do Page::get()->reverse()->limit(10)->filterByCallback(fn ($item) => $item->URLSegment !== 'home')->count(); I get 10 records (where the filter doesn't remove any rows)

Originally posted by @christopherdarling in silverstripe/silverstripe-framework#10248 (comment)

Update docs from graphql 3 to graphql 4 compatability

There are several sections in the docs outside the explicit graphql section that refer to graphql, e.g. https://docs.silverstripe.org/en/4/developer_guides/model/versioning/#expose-graphql-scaffolding

These currently are written with graphql 3 compatability. They should be updated for graphql 4 compatability.

Acceptance criteria

• All graphql v3 examples in the CMS 4 docs are updated
  • to ensure they still actually work
  • to also include graphql v4 examples
• All graphql v3 examples in the CMS 5 docs are removed (leaving the graphql v4 examples)
  • There are no mentions of "graphql v4"

OLD CMS 4 PRs

Once these are all merged, reassign to me so I can update the CMS 5 docs

• #184
• silverstripe/silverstripe-admin#1473
• #187
• #197

OLD CMS 5 PRs

• silverstripe/silverstripe-admin#1481

CMS 4 PRs

Once these are all merged, reassign to me so I can update the CMS 5 docs and code if necessary

• #211
• #215
• silverstripe/silverstripe-admin#1498

CMS 5 PRs

• #196
• #247
• silverstripe/silverstripe-admin#1500

Document release branch creation process

The Making a core release docs don't spell out how to handle new minor release branches (e.g. branching off 4 to 4.4), and how that affects branch aliases in recipes/installer, as well as the dependencies in those.

Option A: Set recipes/installer constraints on major release branch (e.g. 4) to the branch-alias. Example: silverstripe/installer:4.x-dev requires silverstripe/recipe-cms:4.5.x-dev

Option B: Set recipes/installer constraints on major release branch (e.g. 4) to the major release branch of the dependency. Example: silverstripe/installer:4.x-dev requires silverstripe/recipe-cms:4.x-dev

We're effectively doing Option A everywhere already, but there's been some confusion between @robbieaverill @ScopeyNZ and myself around this (see silverstripe/silverstripe-installer@cfba4cb and silverstripe/silverstripe-installer@3e7294e).

I'm proposing that we're keeping Option A, but documenting this better.

The CWP release instructions on https://silverstripe.atlassian.net/wiki/spaces/CWP/pages/655458662/Instructions+for+CWP+release already reflect this (see point 3.1)

Docs aren't updated when PRs are merged into 5 branch

Currently when the 5 branch gets new content merged in, we have to manually deploy the changes.
The workflow should be updated to deploy when the 5 branch gets pushes.

Acceptance criteria

• When new content is pushed to the 5 branch, the site is deployed
• The site can be deployed by running the workflow manually

PRs

• #76

Improve docs around setUp and setUpBeforeClass

Description

The docs for setUp and tearDown in SapphireTest are incorrect as these methods are protected now.

Additionally the docs have a section about using setUpBeforeClass in your tests:

https://github.com/silverstripe/silverstripe-framework/blame/4/docs/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md#L140 (blame because there's no line-number view for markdown files 😞 )

This doesn't mention any of the caveats of using this like certain scaffolding not being ready yet - the example from community Slack being you can't Security::setCurrentUser. Personally I would generally discourage use of it in most cases as test state should not persist between individual tests.

Either way that section could be improved to warn developers better.

[DOCS] Fix typos and markdown errors

Affected Version

All.

Description

The markdown docs for many SilverStripe GH projects could be even more useful for anal retentives such as myself who cannot make sense of a block of text, unless they've first removed typ0s, grammer, punctuasion's and markdoon` errors from his or her text! :-)

This issue serves as a placeholder for an example of an "easy" issue to be achieved by students of the SilverStripe group of the 2019 Catalyst Open Source Academy intake, and restricted to the "silverstripe/framework" package in the first-instance.

Suggested tools:

• Github Markdown reference
• Github Markdown editor
• Grammarly (Is there a free edition of this?)

Steps to Reproduce

Review the following random selection of docs for issues of this kind (There will be more, these are just those I found in the space of ~15m):

• Markdown: Old version of API docs linking: https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/00_Model/07_Permissions.md
• Markdown: Most docs under here contain "title:" rather than "##": https://github.com/silverstripe/silverstripe-framework/tree/4/docs/en/02_Developer_Guides
• Markdown: Unrendered backticks: https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md
• Markdown: Badly formatted links: https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/03_Forms/00_Introduction.md
• Markdown: Backticks: https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/03_Forms/03_Form_Templates.md
• Grammar: "Another example, some temporary files are created in a directory" (Missing join word ala: "Another example is...": https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/16_Execution_Pipeline/01_Flushable.md
• Typo: "There's" vs "There are" or "There're": https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md

Add namespaces to code examples in docs

Currently most of the code examples in the docs do not include namespaces. This is a holdover from the SS3 days, and can in some cases result in a lack of clarity over whether namespaces should be included (e.g. most yaml config needs it but graphql for example doesn't always need namespaces).

We should add namespaces to all of the code examples so that it's clear how namespaces fit in with Silverstripe code.

Use X-Status header for status messages

Parent issue for #101

Documentation should be updated to state what a "first class" environment variable is

The problem
It's unclear on what is meant here (had a client literally ask us and pointed to the documentation)

The solution
Add parenthesis with something like "Configure at OS level".
I have a feeling there is more to cover here that I'm not across, but multiple examples of "first class" env vars would help!

Suggested copy change:

Sensitive credentials should not be stored in a VCS or project code and should only be stored on the environment in question. When using live environments the use of .env files is discouraged and instead one should use environment variables set at the OS level.

Source:
https://docs.silverstripe.org/en/4/getting_started/environment_management/#security-considerations

Add linting for docs

We don't currently have any automated checks to validate the quality of our documentation. This means we might potentially have now - or could easily introduce in the future - markdown formatting issues, incorrectly formatted links, etc. This is especially likely to happen with some of the custom markdown syntax such as API links.

Proposed automated checks:

• Markdown linting
  • e.g. all code blocks have a syntax-highlighting hint (use text for plain text blocks)
• Ensure custom functionality is formatted correctly
  • links (e.g. api links use the api:Namespace\Class::someMethod() syntax instead of a hardcoded links, links to other docs sections are relative)
  • [info] and similar are formatted correctly and are never left unclosed
  • Custom anchors (i.e. {#some-anchor} in headings)
  • no malformed title, description, icons
    • e.g. backticks in these causes errors in the netlify build
  • Probably others (part of the work will be looking at what functionality docs.silverstripe.org has and adding to this list)
• Changelog marked as "unreleased" (in title and header) unless it has an actual commit changelog included
• code blocks should be standardised (e.g. allow either yaml or yml but not both)
• Standardised namespace declarations in php code examples
• Any broken links are identified (e.g. at a minimum this would be broken relative links to other doc pages - but could expand to include absolute URLs and api docs)
• Either enforce a character limit for lines of documentation (our guide says "keep documentation lines shorter than 120 characters" at the time of writing) OR enforce that paragraphs must not be split into multiple lines.
• Everything in our contributing documentation page that can be linted should be linted.
• Code inside code blocks for at least PHP and Javascript are linted

This should be run on all PRs automatically via github actions.

NOTE: Linting should respect Silverstripe's writing style guide (only accessible to Silverstripe employees currently)

potentially useful tools

• https://vale.sh/ for linting docs generally
• various suggestions which can work in combination to fulfill various requirements
• eslint-plugin-markdown for linting js examples in markdown
• DavidAnson/markdownlint or markdownlint/markdownlint for linting the markdown itself
• phpcs allows you to add a bootstrapper which might be one way to use that tool for linting php code blocks

Related issues

• #37

Notes

• I am taking custom markdown syntax out-of-scope as it's non-trivial. See #388
• Linting language structure has been pulled out of scope and will be handled in #390

Acceptance criteria

• Where feasible, the proposed automated checks are implemented.
• Developer doc is in Rhino (if it isn't already) and if linting fails, a blroken build is shown in Rhino.
• Validate that module standardiser does not conflict with this new build.
• This applies to developer docs only.

TODO

These will be done after the first lot of PRs are merged.

• Merge up to CMS 5 - this will be a whole process of its own and may need to even be a "undo all of the changes and fix issues from scratch" scenario.
• Create a new PR which only applies the MD013 line-length rule, to limit lines to 120 characters.

PRs

• #387
• silverstripe/markdown-php-codesniffer#1
• silverstripe/rhino#4
• silverstripe/github-issue-search-client#123
• silverstripe/gha-generate-matrix#70
• silverstripe/cow#249
• silverstripe/markdown-php-codesniffer#3
• silverstripe/module-standardiser#25

DO NOT CLOSE UNTIL ALL TODO ITEMS ARE COMPLETE

Tutorial series for PWA with GraphQL

Overview

• As a developer new to SilverStripe, I want to get a quick overview on building solutions on a decoupled CMS in order to evaluate the products suitability for modern applications
• As a developer with existing SilverStripe experience, I want to apply my existing knowledge to building solutions on a decoupled CMS in order to stay relevant in a changing market

Acceptance Criteria

• Uses React (since that's our stack of choice)
• Popularises the JAMStack use case
• Uses aspects of a Progressive Web App (e.g. manifest)
• Minimises documentation around third party tools (e.g. Apollo)
• Final code can be browsed quickly for devs who know parts of the solution already
• Does not render data through SSViewer
• Frontend implementation is maintainable (minimises duplication between simple theme, watea theme, and potential new demo theme)

Notes

• TBC: Staticpublishqueue or Gatsby?
• If Gatsby: Extra tutorial step to explain how to deploy via Deploynaut API?
• Stretch goal: Offline data support?
• Ingo has built a demo app
• Aaron has used https://github.com/unclecheese/dogapp-frontend and https://github.com/unclecheese/dogapp-backend for his StripeCon talk last year

Templates ignore arguments in getter methods

Affected Version

4.3.2 (and probably others)

Description

If a controller method is prefixed with get but called in a template without the prefix, arguments passed in the template are not passed to the method.

I'm not sure if this is strictly a bug as I couldn't find a lot of documentation about getters, but my understanding of the convention in SilverStripe is that getMethod() is expected to work the same as Method().

Perhaps by convention getters shouldn't accept arguments but thought this was worth reporting anyhow. Surfaced by this forum post.

Steps to Reproduce

Not prefixed with get

Page controller:

public function Foo() {
    return 'Foo';
}

public function Bar($bar='Bar') {
    return $bar;
}

Page template: $Foo $Bar(Foo)
Expected result: "Foo Foo"
Actual result: "Foo Foo" ✅

Prefixed with get (method only)

Page controller:

public function getFoo() {
    return 'Foo';
}

public function getBar($bar='Bar') {
    return $bar;
}

Page template: $Foo $Bar(Foo)
Expected result: "Foo Foo"
Actual result: "Foo Bar" ❌

Prefixed with get (method and template)

Page controller:

public function getFoo() {
    return 'Foo';
}

public function getBar($bar='Bar') {
    return $bar;
}

Page template: $getFoo $getBar(Foo)
Expected result: "Foo Foo"
Actual result: "Foo Foo" ✅

Icon not displaying correctly for Managing Security Issues

The icon for the "Managing Security Issues" page does not display correctly

If it's a valid icon, we need to fix it in silverstripe/doc.silverstripe.org - otherwise we need to set a valid icon here in the docs

Acceptance criteria

• A suitable icon is displayed for the managing security issue page.

PR

• #264

Need clearer documentation about "canDelete" being used for archive permissions on versioned objects

If you create a page type with a canDelete(...) return false; in it, it becomes impossible to delete an elemental on this page type. You have to override any elemental's canDelete(...) function in order to get it to work

See BaseElement.php line 251 in canDelete($member = null)

Document Filesystem Operations

Overview

We've changed a lot of stuff in the 4.0 release around filesystem. It's been documented alongside feature pull requests, but it's mostly been focused on the new File model abstraction. There's been lots of lower level changes that aren't documented in a coherent place, mainly around ModuleLoader and ModuleManifest APIs.

Acceptance Criteria

• Developers know how to get filesystem paths for modules, templates and project code
• Developers get consistent guidance in the context they're currently in (setting up a project, working with templates, etc)
• Developers know how to handle the public/ and mysite/ directories, regardless of their context (building themes, building modules, working with files)
• Developers know shortcuts for path operations

Tasks

• Better introduction to the "filesystem" topic (don't start with "uploadfield" in the second section)
• Pointers from "Getting Started > Directory Structure" to deeper info
• Examples on how to create files in Files > File Management
• Add instructions on how to handle module paths (both in "Files" and "Extending > Modules" sections)
• Point to Templates > Themes from "Files" and "Modules" sections regarding how they handle paths
• Document $project, how to configure it, how to use it to get custom paths. Both in Files > File Management and Configuration. Ensure that devs know that they can rename the mysite/ folder, and what effects that has
• Document Director::baseFolder() and alternate_base_folder in an obvious place (e.g. "Filesystem"). Can point to "Execution Pipeline" for details, but shouldn't require devs to find that document in the first place since it's much too advanced for this basic info
• Document SilverStripe\Core\Path

keep_archived_assets docs could be better

There are multiple separate references to configuring file archiving via keep_archived_assets

I'm not sure how many of these you actually need to set to true in order to get keep_archived_assets to function correctly. Possibly some of these are previous implementations and no longer do anything. Seems like we should at have a single source of truth in the docs for how to enable this feature.

Undocumented:

https://github.com/silverstripe/silverstripe-assets/blob/1/src/AssetControlExtension.php#L47

    private static $keep_archived_assets = false;

Documented:

https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/14_Files/01_File_Management.md#configuring-file-archiving

SilverStripe\Assets\File:
  keep_archived_assets: true

https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/14_Files/03_File_Security.md#configuring-archive-behaviour

class MyVersiondObject extends DataObject 
{
    /** Ensure assets are archived along with the DataObject */
    private static $keep_archived_assets = true;

https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/02_Developer_Guides/14_Files/04_File_Storage.md#versioned-and-archived-files-archived

SilverStripe\Assets\Flysystem\FlysystemAssetStore:
  keep_archived_assets: true

Environment set-up guides

In order to ensure effective contribution, I think we need to provide some guides on how to set up IDEs / editors for work on SilverStripe core.

Off the top of my head, we should address the following areas:

• editorconfig
• js, php, and css linters
• custom silverstripe syntax packages

And based on https://groups.google.com/forum/#!topic/silverstripe-dev/bozY5hh9g4c, we should cover the following editors:

• PHPStorm
• Sublime Text
• Netbeans
• Atom

This information should probably be put alongside the other handy tips for contribution:

• checking out npm sources
• running js, php tests
• running final linter checks

Some relevant Atom packages

• https://atom.io/packages/editorconfig
• https://atom.io/packages/atom-silverstripe

DOCUMENTATION: the information about ManyMany Through List should include info about indexes?

Affected Version

4.4.*

Description

see: https://docs.silverstripe.org/en/4/developer_guides/model/relations/

I wonder if we should include some information about ManyMany Through lists about having to create a unique index in the Through Table... e.g.

    private static $indexes = [
        'ManyManyUniqueKey' => [
            'type' => 'unique',
            'columns' => ['ClassID', 'YearID'],
        ],
    ];

Steps to Reproduce

n/a

Preview docs have some incorrect or missing information.

• The preview docs as written will result in css and js from the CMS being injected into the preview if the preview HTML contains <head> or <body> tags.
• There are some broken links in the 4 and 5 branches
• The 4 and 5 branch docs haven't been fully updated to account for the recent changes (i.e. they still say it's dificult to implement CMSEditLink()

Acceptance criteria:

• There are no broken links in preview docs
• CSS and JS Requirements are accounted for
• The 4 and 5 branches don't say it's difficult to implement CMSEditLink() anymore

PRs

• #97
• #98
• #99
• #173

Unclear when methods get called by summary_fields

Affected Version

framework v4.3.0 & v4.3.1 / PHP7.1

Description

Attempting to use custom method output as Gridfield column content, fails when naming the key with "get", but only if the method is not empty. Empty strings for example will work A-OK. Renaming the key to omit "get" in `$summary_fields will also work A-OK.

Scenarios:

    private static $summary_fields = [
        'getFoo' => 'Bar',
        'getBar' => 'Foo',
        'FooBar' => 'Foo'
    ];

    public function getFoo()
    {
        return ''; // <-- Empty string - works
    }

    public function getBar()
    {
        return ' '; // <-- Single space - FAIL
    }

    public function getFooBar()
    {
        return 'TEST TEST 1.2.3'; // <-- Anything here is OK. Method sig contains "get", but we leave it off the respective `$summary_fields` key
    }

Steps to Reproduce

See code examples above.

The github action to deploy docs doesn't seem to work

There is a github action on this repository that should trigger on push to the 4.11 and 3 branch. This should include a push triggered by merging a PR.

There have been several PRs merged to the 4.11 branch, but https://github.com/silverstripe/developer-docs/actions/workflows/build.yml shows the action has never run.

Acceptance Criteria

• Whenever a PR is merged to the 4.11 or 3 branch, or docs are pushed directly to one of these branches, the github action triggers a deployment to docs.silverstripe.org

PRs

• #53

Docs for how to create a module with composer

https://docs.silverstripe.org/en/4/developer_guides/extending/modules/ and https://docs.silverstripe.org/en/4/developer_guides/extending/how_tos/publish_a_module/ don't describe how to actually create a module. With composer, there's a bit of a chicken-and-egg situation: You need to have a module to install it via composer on your site, get autoloading going, and then start developing.

Given that we want people to create modules for SilverStripe, this should be far more obvious.

Recommend a VM as the primary solution to get started with SilverStripe

Setting up your own webserver on a host system is no longer necessary, given the speed and usability improvements in virtualisation layers. Our main gettgin started guide in the docs still recommends installing on the host: https://docs.silverstripe.org/en/4/getting_started/installation/

The tutorials are a bit clearer (VMs as the first option), but could also be a bit clearer in their recommendation: https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1.

We should provide a consistent and advice here, and clearly mark out "advanced use cases" to avoid confusing beginners. And not treat our guides as "related content", but rather have one way to install our product.

Document how to use namespaces in project code

Acceptance Criteria

As a developer:

• I know how to namespace my project classes
• I know how to correctly configure autoloading
• I'm pointed to this information from early-stage introductions (where Page.php is explained in docs and lessons)

Notes

• Should include documentation for the upcoming pull request for controller_name
• There's known workarounds for Page.php namespacing

Documenting the "vendor expose" sorcery

Affected Version

4 and above

Description

Following some discussion it appears the "vendor expose" process is not super clear for most of the SilverStripe community.

I suggest we fix this by providing a central doc article demystifying the vendor-expose logic.

Acceptance criteria

• As a SilverStripe Developer I can understand:
  • The purpose of "vendor-expose",
  • How to expose my project resources,
  • How to reference project resources and module resources in templates and php files,
  • How to debug common issues with vendor expose
• As a SilverStripe Module Developer I can understand:
  • How to expose my module's resources and reference them.

why $this->config instead of static::config ?

Affected Version

4.11

Description

I recently ran Rector on my project and it's complaining about the use of $this->config. Indeed, the method definition is static, so why is it recommended to call $this->config instead of self::config or static::config ?
See docs here: https://docs.silverstripe.org/en/4/developer_guides/configuration/configuration/

Document how deprecation works

We don't have clear guidance on how and when to deprecate method and classes.

Acceptance criteria

• Developers have clear guidance on how to activate/deactivate deprecation warnings and how to configure them.
  • That guidance can be applied to unit test and to browser based execution as well.
• Developers planning a CMS5 upgrade are encouraged to turn on deprecation warnings on their CMS4 project as way to facilitate their upgrade.
• The doc explicitly tells developers working on the core product
  • how and when to use @deprecated phpdoc annotation
  • how and when to use Deprecation::notice()
  • how to retain test for deprecated code
  • how to validate that that deprecated code is no longer in use by the non-deprecated code base.
• Review any previous docs about deprecation and make sure it's inline with the new doc or remove it altogether.

Note

• Once upon a time, some folks wanted to have a PSR standard that would require people to write their deprecation annotations like @deprecated 4.1.0:5.0.0 Some description. In this scenario, 4.1.0 would be the version where the method got deprecated and 5.0.0 would be the version where the method is expected to be remove. The second version parameter got dropped. But we still use that syntax in a few places.
• Draft PSR19 standard proposal for @deprecated

PRs

• #131

DOCUMENTATION for setFieldCasting

Affected Version

SS4+

Description

It would be great to have a bit more detail for about setFieldCasting.

see: https://github.com/silverstripe/silverstripe-framework/blob/909723f8e709a5d1720d84739a80e6a9cfa14b17/src/Forms/GridField/GridFieldDataColumns.php#L102-L106

In particular, it is unclear which one we should use:

    'MyField' => DBDatetime::class.'->Nice', //OR

    'MyField' => 'Datetime->Nice', //OR

    'MyField' => 'DBDatetime->Nice'

Wrong documentation for caching ?

Documentation for caching states on line 133 that :

You can also set your lifetime to 0, which means they won't expire

Actually, this seems to remove cache, TTL will be set to false in normalizeTtlmethod in Symfony\Component\Cache\Simple\AbstractCache

Not setting any ttl looks like the way to achieve wanted behavior for me. Do you agree ?

Docs: Info about how to debug a variable in the template is missing

Affected Version

Current docs

Description

I wasn't able to find information how to debug a variable while trying to help a newbe on slack:

Q: I am new with SilverStripe and I want to know if exists equivalent of print_r or var_dump inside SilverStripe template

A: $Foo.Debug shows the value of $Foo. Indside a loop you can call $Me.Debug to get the current variable in the loop

At which document do you think we should insert information about how to debug variables in templates? Would https://docs.silverstripe.org/en/4/developer_guides/debugging/template_debugging/ be good or should it go to the templates section, e.g. https://docs.silverstripe.org/en/4/developer_guides/templates/common_variables/ ?

Steps to Reproduce

Search docs ;)

function getSearchContext in extension of modeladmin is not called anymore

Affected Version

v4.3.0

Description

When extending ModelAdmin to add new pre-defined queries (e.g. a checkbox that will be used to filter adresses in Belgium - using later on the getlist function), the overwritten getSearchContext functions never called.
This is the code I used but you may simply use examples from your on-line developers doc (https://docs.silverstripe.org/en/4/developer_guides/customising_the_admin_interface/modeladmin/).

class Adress_Admin extends ModelAdmin {
    private static $url_segment = 'Adress';
    private static $menu_title = 'Adressen';
    private static $managed_models = [Adress::class];

    public function getSearchContext() 
    {
        $context = parent::getSearchContext();
        if($this->modelClass == 'bpf\Adress') {
            $context->getFields()->push(new CheckboxField('q[InBelgiumA]', 'Only expensive stuff'));
        }
        return $context;
    }

Steps to Reproduce

It's very easy to check - use e.g. error_log to trace the fact the function has been called.

Help us with step-by-step instructions.

ps: I know this will be depreciated in v5 but at least could you please provide an updated documentation on how to do it using GridfieldFilterHeader.
Thank you!!!

Update references to "Silverstripe" to clarify the distinction between the company and the CMS/framework.

"Silverstripe" on its own should refer to the company (see #9 (comment)).

Acceptance Criteria

• Any references to "Silverstripe" in the docs refer explicitly to the company
  • If you find any that do not refer to the company, update them to say "Silverstripe framework" or "Silverstripe CMS" (whichever is appropriate in the given context)
• There are no references to "Silverstripe ltd"

Improve Model-Level Permissions docs

Affected Version

4.x

Description

Currently the docs cover very basic can permission implementations. One missing aspect of this is the importance to check permissions on your current model, then check against the parent. This is most notable with Pages in the CMS module where the $context param holds the ParentID which is utilized to determine if a given page type can be created under another given parent page type.

Solution

Describe the how $context is used in the CMS module as an example both for the ability to enhance permission logic with context, as well as the importance of that param when checking permissions if you are extending a class and providing custom permissions.

Restructure "customise the CMS" docs

Overview

The current docs at https://github.com/silverstripe/silverstripe-framework/tree/master/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface are a hodge podge of legacy and new documentation. While some docs are marked as "deprecated", there's no clear learning path for new features.

Acceptance Criteria

• As a developer customising the CMS, I can follow a clear learning path for React-based CMS sections without getting confused by legacy usage
• I can get a quick overview of the means to customise the CMS without diving into details
• I have a path for setting up a SilverStripe CMS module with frontend tooling (either through docs or a bare bones code repository)
• Legacy documentation is clearly marked on overview and navigational pages
• Where my customisation my involve multiple approaches (e.g. a reducer and new component), I can easily find relevant sections through cross-linking
• Legacy docs are stripped to their essentials, with minimal outdated advice (e.g. "we test with JUnit")

Documentation error for configuration guide

The configuration documentation for the "Before / After Priorities" guide seems to be incorrect:

It states:

The value section above has two rules:

• It must be merged in before (lower priority than) all other value sections
• It must be merged in after (higher priority than) any value section with a fragment name of "rootroutes"

But the example does not have any "before" rule.

---
Name: adminroutes
# <- No before rule
After: 
  - '#rootroutes'
  - '#coreroutes'
---
SilverStripe\Control\Director:
  rules:
    'admin': 'SilverStripe\Admin\AdminRootController'
---

Nginx configuration docs are empty

Visiting the page https://docs.silverstripe.org/en/3/getting_started/installation/how_to/configure_nginx/ shows an empty section where the example Nginx config should be. It seems to have been removed in a commit that formatted the docs for Gatsby: silverstripe/silverstripe-framework@54e7223#diff-4bd44d58dc18b09f7a067b216a5f0916aa1a73ac93e51f3313ee0c9ae6465014L23

Along with several other code blocks that are examples. They should be probably all be added back in.

CMS 5 developer doc and user help doc are set up

Acceptance criteria

• CMS 5 branches are set up for user doc and developer doc
• CMS 5 content can be seen on developer doc and user doc and API doc.
• CMS 5 content is clearly marked as "pre-release"
• There's a clear demarcation between CMS4 and CMS5 doc.
• Until CMS5 is stable, the docs default to 4
• CMS 3 content no longer shows up on doc site and API Doc.

Notes

• Will probably need some UX/design feedback

PRs

• #47
• silverstripe/silverstripe-userhelp-content#175
• silverstripe/doc.silverstripe.org#244
• silverstripe/api.silverstripe.org#102