Help strings: Difference between revisions

Revision as of 09:50, 13 July 2012

2.0 help strings
Project state	Fixed
Tracker issue	MDL-21695
Discussion	Help file integration in php lang files
Assignee	Helen Foster

Moodle 2.0

In Moodle 2.0, help files will be converted to strings. All essential help will remain available in Moodle via help popups, with supplementary help available in Moodle Docs. Many help popups remain the same in 2.0 as in 1.9, with only extra long help popups (often from the time before Moodle Docs) greatly reduced.

String names

Help strings names will start with the string name of the setting to which they apply, so that they are kept together in the language file.

stringname
stringname_help
stringname_link - an optional string naming a path in Moodle Docs, only if required, calculated just like the link in the footer to go to the right language etc, and shown after the help text in the popup as a link with an icon to "More help..."
stringname_desc - an admin setting description replacing the legacy configstringname

For example:

$string['submissionsize'] = 'Submission size';
$string['submissionsize_help'] = 'Blah blah blah some useful text, optionally using Markdown syntax';
$string['submissionsize_link'] = 'mod/workshop/submission';
$string['submissionsize_desc'] = 'Default value for submission size. This value will be pre-filled and can be blah blah ...';

Help string formatting

Help string text should be short and simple - two small paragraphs maximum (150 words?) with no headings, no links, no bold, no tables etc.

Markdown can be used for some formatting. It is recommended to stick on paragraphs and lists only.

paragraph: new line
bullet point: *

The help popup will have the same title as the setting it applies to.

For example:

$string['newsitemsnumber'] = 'News items to show';
$string['newsitemsnumber_help'] = 'This setting determines how many recent items appear in the latest news block on the course page. If set to "0 news items" then the latest news block will not be displayed.';

will result in a help popup as follows:

More help links

The string with the _link suffix is used to provide an optional More help... link at the bottom of the associated help popup. These strings should consist of a short relative path like 'component/thing' (eg. 'mod/folder/view' or 'group/import'). This gets turned into a link to MoodleDocs in the user's language, and for the appropriate Moodle version.

For example the string

$string['groupimport_link'] = 'group/import';

will make a link to something like 'https://docs.moodle.org/23/en/group/import' (if you are an English user of Moodle 2.3). This page in turn should be a redirect page to the actual page providing the info. Note the 'https://docs.moodle.org' part comes from $CFG->docroot.

This is the only option that should be used in standard Moodle code. The other two options exist since Moodle 2.3.1 and have been implemented because they are useful for third-party plugins. The are described below.

Also note that the strings with the _link suffix do not appear in AMOS translation tool. They are supposed to be defined in the English pack only.

Absolute links

The second option is that you can give an absolute link, if you want, and that will be used unmodified. For example

$string['patronising_link'] = 'http://lmgtfy.com/?q=Moodle+for+dummies';

This case is detected by seeing if the string starts with http:// or https://. This option is useful if the documentation for your plugin is hosted at Github wiki, for example.

Links relative to wwwroot

The third option is to start the link with %%WWWROOT%%. That is replaced by $CFG->wwwroot. This is useful for contrib plugins that want to keep the help within the plugin. For an example see https://github.com/maths/moodle-qtype_stack/blob/master/lang/en/qtype_stack.php.

Words for roles

The following words should be used in the en help strings whenever it is necessary to refer to people with particular roles in a generic sense.

Participants - all people with a role
Teachers - people with some sort of a facilitation/editing role
Students - people primarily there to learn
Users - people across the site

(Martin Dougiamas 16:13, 20 April 2010 (UTC): I'm not entirely comfortable with this choice even though I just re-confirmed it, as I'd prefer to be using words like facilitator/moderator to subtly and continually promote a less transmissionist pedgagogy and I know many Moodle users would agree. However, I think these terms are far more commonly used in the community and in discussion, and from the point of view that we need to build a consistent system for usability they are less distracting and better for documentation.)

@@ Line 44: / Line 44: @@
 [[Image:Help popup.png]]
-==Links to additional documentation==
+==More help links==
-The string with the _link suffix is used to provide an optional 'More help...' link at the bottom of the associated help popup. In most cases, these strings should consist of a short relative path like 'component/thing' (eg. 'mod/folder/view' or 'group/import'). This gets turned into an link to MoodleDocs  in the user's language, and for the appropriate Moodle version. For example 'group/import' may become <nowiki>'https://docs.moodle.org/23/en/group/import'</nowiki> which in turn should be a redirect page to the actual page providing the info. The <nowiki>'https://docs.moodle.org'</nowiki> part comes from $CFG->docroot.
+The string with the _link suffix is used to provide an optional ''More help...'' link at the bottom of the associated help popup. These strings should consist of a short relative path like 'component/thing' (eg. 'mod/folder/view' or 'group/import'). This gets turned into a link to MoodleDocs  in the user's language, and for the appropriate Moodle version.
-This is the only option that should be used in standard Moodle code. The other two options exist since Moodle 2.3.1 and have been implemented because they are useful for third-party plugins:
+For example the string
-* The string may be an absolute URL, starting with <nowiki>http:// or https://</nowiki>. In this case, the link is used as is.
+ $string['groupimport_link'] = 'group/import';
-* The string may start with %%WWWROOT%%, in which case that is replaced by $CFG->wwwroot to make the link.
-The strings with the _link suffix do not appear in [[AMOS]]. They are supposed to be in the English pack only.
+will make a link to something like <nowiki>'https://docs.moodle.org/23/en/group/import'</nowiki> (if you are an English user of Moodle 2.3). This page in turn should be a redirect page to the actual page providing the info. Note the <nowiki>'https://docs.moodle.org'</nowiki> part comes from $CFG->docroot.
-==Words for roles==
+This is the only option that should be used in standard Moodle code. The other two options exist since Moodle 2.3.1 and have been implemented because they are useful for third-party plugins. The are described below.
-The following words should be used in the en help strings whenever it is necessary to refer to people with particular roles in a generic sense.
+Also note that the strings with the _link suffix do not appear in [[AMOS]] translation tool. They are supposed to be defined in the English pack only.
-* Participants - all people with a role
+===Absolute links===
-* Teachers - people with some sort of a facilitation/editing role
-* Students - people primarily there to learn
-* Users - people across the site
-([[User:Martin Dougiamas|Martin Dougiamas]] 16:13, 20 April 2010 (UTC): I'm not entirely comfortable with this choice even though I just re-confirmed it, as I'd prefer to be using words like facilitator/moderator to subtly and continually promote a less transmissionist pedgagogy and I know many Moodle users would agree.  However, I think these terms are far more commonly used in the community and in discussion, and from the point of view that we need to build a consistent system for usability they are less distracting and better for documentation.)
+The second option is that you can give an absolute link, if you want, and that will be used unmodified. For example
-==More on help links==
+ $string['patronising_link'] = <nowiki>'http://lmgtfy.com/?q=Moodle+for+dummies';</nowiki>
-There are actaually three options for the
+This case is detected by seeing if the string starts with <nowiki>http:// or https://</nowiki>. This option is useful if the documentation for your plugin is hosted at Github wiki, for example.
- $string['quiz_link'] = 'mod/quiz';
+===Links relative to wwwroot===
-string.
+The third option is to start the link with %%WWWROOT%%. That is replaced by $CFG->wwwroot. This is useful for contrib plugins that want to keep the help within the plugin. For an example see https://github.com/maths/moodle-qtype_stack/blob/master/lang/en/qtype_stack.php.
-===Normal help links===
+==Words for roles==
-The first is as shown above. A relative like that gets turned into a link to MoodleDocs, using the current language and Moodle version. For example this link becomes https://docs.moodle.org/23/en/mod/quiz (if you are an English user of Moodle 2.3). Such pages are almost always redirect pages. For example, this link redirects to https://docs.moodle.org/23/en/Quiz_module.
+The following words should be used in the en help strings whenever it is necessary to refer to people with particular roles in a generic sense.
-This option is the only one that should be used in core Moodle code.
+* Participants - all people with a role
+* Teachers - people with some sort of a facilitation/editing role
+* Students - people primarily there to learn
+* Users - people across the site
-===Absolute links===
+([[User:Martin Dougiamas|Martin Dougiamas]] 16:13, 20 April 2010 (UTC): I'm not entirely comfortable with this choice even though I just re-confirmed it, as I'd prefer to be using words like facilitator/moderator to subtly and continually promote a less transmissionist pedgagogy and I know many Moodle users would agree.  However, I think these terms are far more commonly used in the community and in discussion, and from the point of view that we need to build a consistent system for usability they are less distracting and better for documentation.)
-The second option is that you can give an absolute link, if you want, and that will be used unmodified. For example
- $string['patronising_link'] = 'http://lmgtfy.com/?q=Moodle+for+dummies';
-This case is detected by seeing if the string starts with http:// or https://
-===Links relative to wwwroot===
-The third option is to start the link with %%WWWROOT%%. That is replaced by $CFG->wwwroot. This is useful for contrib plugins that want to keep the help within the plugin. For an example see https://github.com/maths/moodle-qtype_stack/blob/master/lang/en/qtype_stack.php.
 [[Category:Language]]

Documentation