Moodle
  1. Moodle
  2. MDL-26064

Moodle Docs for this page does not point to the correct page for block config

    Details

    • Type: Bug Bug
    • Status: Open
    • Priority: Critical Critical
    • Resolution: Unresolved
    • Affects Version/s: 2.0, 2.3.1
    • Fix Version/s: STABLE backlog
    • Component/s: Blocks
    • Labels:
    • Affected Branches:
      MOODLE_20_STABLE, MOODLE_23_STABLE
    • Rank (Obsolete):
      15662

      Description

      Moodle Docs for this page does not point to the correct page for blocks in moodle 2.0.
      it always points to http://docs.moodle.org/en/course/view

        Issue Links

          Activity

          Hide
          Helen Foster added a comment -

          Joseph, thanks for your report. As you mention, all block configuration pages have a Moodle Docs for this page link as course/view.

          In Moodle 1.9, the random glossary entry block config page had blocks/glossary random as a link and the HTML block config page had blocks/html.

          In 2.0 all blocks now have a config page with settings 'Where this block appears' and 'On this page
          Visible'. I think they can all have the same Moodle Docs for this page link.

          Show
          Helen Foster added a comment - Joseph, thanks for your report. As you mention, all block configuration pages have a Moodle Docs for this page link as course/view. In Moodle 1.9, the random glossary entry block config page had blocks/glossary random as a link and the HTML block config page had blocks/html. In 2.0 all blocks now have a config page with settings 'Where this block appears' and 'On this page Visible'. I think they can all have the same Moodle Docs for this page link.
          Hide
          Joseph Rézeau added a comment -

          Helen,

          I disagree that in 2.0 all blocks should have the same course/view Docs page. Actually that page does not provide very helpful contextual help for blocks configuration, does it?

          What is absolutely needed is for each block's Docs link to point to that block's relevant Docs page (as per moodle 1.9).

          Hope some developer can look into this bug and provide a quick fix.

          Joseph

          Show
          Joseph Rézeau added a comment - Helen, I disagree that in 2.0 all blocks should have the same course/view Docs page. Actually that page does not provide very helpful contextual help for blocks configuration, does it? What is absolutely needed is for each block's Docs link to point to that block's relevant Docs page (as per moodle 1.9). Hope some developer can look into this bug and provide a quick fix. Joseph
          Hide
          Tim Hunt added a comment -

          I think the solution to this is that when process_url_edit in blocklib.php is setting up $editpage, then it needs to call $editpage->set_docs_path() with an appropriate path.

          Show
          Tim Hunt added a comment - I think the solution to this is that when process_url_edit in blocklib.php is setting up $editpage, then it needs to call $editpage->set_docs_path() with an appropriate path.
          Hide
          Michael de Raadt added a comment -

          This is still a problem with current versions.

          Show
          Michael de Raadt added a comment - This is still a problem with current versions.
          Hide
          Helen Foster added a comment -

          Joseph, apologies for my initial comment being unclear. I was NOT saying that all block config pages should link to http://docs.moodle.org/en/course/view They do so currently; this is obviously wrong.

          My recommendation is that all block config pages link to http://docs.moodle.org/en/block (i.e. have 'block' as the path) which you'll notice redirects to http://docs.moodle.org/en/Block_settings

          I don't think that it is necessary to have separate documentation / a different path for every block config page, since most are the same (having sections 'Where this block appears' and 'On this page').

          Show
          Helen Foster added a comment - Joseph, apologies for my initial comment being unclear. I was NOT saying that all block config pages should link to http://docs.moodle.org/en/course/view They do so currently; this is obviously wrong. My recommendation is that all block config pages link to http://docs.moodle.org/en/block (i.e. have 'block' as the path) which you'll notice redirects to http://docs.moodle.org/en/Block_settings I don't think that it is necessary to have separate documentation / a different path for every block config page, since most are the same (having sections 'Where this block appears' and 'On this page').
          Hide
          Jessica Gramp added a comment -

          Helen - yes, I agree that the generic Block_settings page is relevant for blocks that don't have any additional settings, but I agree with Joseph that blocks with additional specific settings should point to their own unique help page. Tim's solution to set the $editpage->set_docs_path() with an appropriate path seems like it would allow block developers to do this.

          Tim - do you know if is this something that needs to be changed in core Moodle code as well, or is it a matter of updating each block with the right docs path?

          Show
          Jessica Gramp added a comment - Helen - yes, I agree that the generic Block_settings page is relevant for blocks that don't have any additional settings, but I agree with Joseph that blocks with additional specific settings should point to their own unique help page. Tim's solution to set the $editpage->set_docs_path() with an appropriate path seems like it would allow block developers to do this. Tim - do you know if is this something that needs to be changed in core Moodle code as well, or is it a matter of updating each block with the right docs path?
          Hide
          Michael de Raadt added a comment -

          Hi, all.

          I don't think this would be wise. We have a lot of blocks, particularly contributed blocks, with complex and distinct configurations. I'm happy for relatively generic blocks to have their documentation redirected to a generic block configuration page at the wiki level, but I think it should be possible for each block to define its own documentation. Unlike activity modules and other plugin types, this is the only docs link that contributed blocks get.

          Show
          Michael de Raadt added a comment - Hi, all. I don't think this would be wise. We have a lot of blocks, particularly contributed blocks, with complex and distinct configurations. I'm happy for relatively generic blocks to have their documentation redirected to a generic block configuration page at the wiki level, but I think it should be possible for each block to define its own documentation. Unlike activity modules and other plugin types, this is the only docs link that contributed blocks get.
          Hide
          Helen Foster added a comment -

          Jessica, thanks for your comment, and good point Michael. If blocks with additional settings can point to their own unique help page, then all other block config pages can be redirected to http://docs.moodle.org/en/Block_settings

          Show
          Helen Foster added a comment - Jessica, thanks for your comment, and good point Michael. If blocks with additional settings can point to their own unique help page, then all other block config pages can be redirected to http://docs.moodle.org/en/Block_settings
          Hide
          Tim Hunt added a comment -

          Both options seem reasonable to me, either:

          1. All blocks point to

          {docsurl}/block (or whatever it is) by default, which redirects to http://docs.moodle.org/en/Block_settings. If a block wants something different, it must manually call $editpage->set_docs_path() at the appropriate place in the code flow. (But, does any part of the block code have access to that object? Is there an appropriate place in the code flow, after the default has been set, and before $OUTPUT->header is called, where this can be done.)

          2. All block are automatically made to point to {docsurl}

          /block/

          {blockname}

          /settings by default. If there is nothing special to say about this block, then we make that redirect to http://docs.moodle.org/en/Block_settings using a redirect in the docs wiki.

          Actually, I have a slight preference for 2. I think it is a neater design. Expecting block developers to screw around with is unnecessarily complicated for them. Michael, can you imagine writing the developer docs to explain to them why and how they might want to do that?

          Show
          Tim Hunt added a comment - Both options seem reasonable to me, either: 1. All blocks point to {docsurl}/block (or whatever it is) by default, which redirects to http://docs.moodle.org/en/Block_settings . If a block wants something different, it must manually call $editpage->set_docs_path() at the appropriate place in the code flow. (But, does any part of the block code have access to that object? Is there an appropriate place in the code flow, after the default has been set, and before $OUTPUT->header is called, where this can be done.) 2. All block are automatically made to point to {docsurl} /block/ {blockname} /settings by default. If there is nothing special to say about this block, then we make that redirect to http://docs.moodle.org/en/Block_settings using a redirect in the docs wiki. Actually, I have a slight preference for 2. I think it is a neater design. Expecting block developers to screw around with is unnecessarily complicated for them. Michael, can you imagine writing the developer docs to explain to them why and how they might want to do that?
          Hide
          Joseph Rézeau added a comment -

          Tim's option 2 for me too.

          Show
          Joseph Rézeau added a comment - Tim's option 2 for me too.

            People

            • Votes:
              3 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated: