4885 Posts in 7139 Topics by 1472 members
|Go to End|
8 April 2013 at 2:33pm
I posted this on SSBits as well but I think the thread was a bit old.
Its about time we had a /_config/config.yml plus _config.php combo cheatsheet.
What you put in either when upgrading from a pure SS3 _config.php is quite confusing and the docs are awful!! I for one have a lot in my _config.php which set up the editor rather better. Plus I have a lot of potential shop config coming up.
Some general conversion and syntax advice would be helpful
11 April 2013 at 8:03pm
What would make the documentation for the config system easier to follow?
We avoided created a list of every. config. option as that is a huge infinite list of statics (same reason we can't produce a "list of all the template variables), it would be better to explain the features behind those statics (like Director::addRules) in context.
11 April 2013 at 8:59pm Last edited: 11 April 2013 9:00pm
tazzydemon: The most up-to-date docs are here, in case you were looking at an older version: http://doc.silverstripe.org/framework/en/trunk/topics/configuration#setting-configuration-via-yaml-files
Willr: The docs are incredibly confusing. Read through the section imagining you are someone that has never used YAML - even if you do manage to understand all of what's said, there's no mention of YAML syntax and no way of telling which properties can be set with YAML. There isn't even an example of how to add an extension with YAML!
Another example is that I've been trying to register dataobjects to the Google Sitemaps module, I have no idea how an array like that is supposed to be structured, or if you can even register dataobjects with YAML.
tldr; the documentation needs more examples (doesn't need to be every config option, just a wide variety of possible use-cases), needs some form of advice about syntax and advice on which properties can be set in YAML (again not listing them all, just some rough guidance).
17 April 2013 at 12:53pm Last edited: 17 April 2013 12:57pm
Here's an example. The thing that threw me is that I didn't realize that "extensions" must be in lower case, or it will not load the extension! The forum does not preserve indentation correctly, so the file is also attached.
29 April 2013 at 2:34pm
Question 1. Whats the hyphen for in this example? Its this type of syntax detail which is missing
Question 2. In the following example I am trying to enable ImageMagick. Not that the _config.php version is without the function test statement
When to use the different type of config and what the arguments might be is as clear as mud.
5 August 2013 at 1:10pm Last edited: 5 August 2013 1:11pm
Willr - you asked about making the docs better. Some thoughts:
The docs would be a lot better if the most common config settings were listed, to get people going. Also a list of common config settings that can't be set in the yaml files & why would be handy & would reduce the learning curve.
eg, http://doc.silverstripe.org/framework/en/3.1/tutorials/4-site-search still shows to use the static method. why?
I wouldn't think a description of how yaml works in the job of the SS docs, but a handy link would be friendly.
read the source code is good general advice but its pretty hostile to new users.
Silverstripe has a lot of documentation, but a common gripe is the documentation isn't very good. Thats a concern for sure. for an example of great docs, check out either the laravel or cakephp sites. They generally have a good general intro to a section & the concepts behind it, backed up with in depth specific sections with code examples for common uses with the context shown.
finally, the silverstripe.org pages rarely load first time. It might be better if they were built with a static generator for some uptime & performance.
in terms of handy links for this specific issue, i found this:
5 August 2013 at 6:17pm
Interesting point, we're marking the config variables easier to spot in the code by using @config (like https://github.com/silverstripe/silverstripe-framework/blob/3.1/view/SSViewer.php#L596). I thought this pulled through to the API docs but obviously expecting too much
Putting the relevant configuration values on the documentation pages is a good start (like SSViewer.theme on the templates page).
|Go to Top|