Comments

TR’s picture

TR’s picture

Help text standards: http://drupal.org/node/632280

If you want to help out and learn how to contribute patches, this would be a good simple task to get started!

TR’s picture

Component: Code » Documentation
Issue tags: +Novice
longwave’s picture

As well as hook_help, is it worth bringing the documentation from ubercart.org and drupal.org into the download via http://drupal.org/project/advanced_help in a similar way to Views?

TR’s picture

I'm not a big fan of putting everything into advanced help. In order to use that documentation, you not only have to set up a website but you have to install the module you want help on and install advanced help, all just to read the documentation. Then maybe you find out you don't want to use that module because it doesn't do what you thought it did. Big waste of time and effort. I understand the limitations of the current hook_help() mechanism, but Drupal is not moving to advanced help as the solution. There has been a lot of progress in the community documentation on drupal.org recently, and I favor improving the Ubercart documentation at http://drupal.org/documentation/modules/ubercart, which is where the community is pushing to have this sort of thing. That way the documentation gets indexed by search engines and the information is not only more accessible but also more findable than it would be in advanced help. Likewise, having the documentation on drupal.org gives us permanent URLs to point people to when they have questions, and allows the community to participate in improving the documentation, and allows us to keep the documentation up-to-date without pushing out a new release. We could even link to the drupal.org documentation from within our hook_help() methods, rather than inlining and distributing all the documentation along with the module.

TR’s picture

Version: 7.x-3.x-dev » 8.x-4.x-dev
Issue summary: View changes
Shashwat Purav’s picture

Assigned: Unassigned » Shashwat Purav
Shashwat Purav’s picture

TR’s picture

@Shashwat Purav - You assigned this issue to yourself more than a month ago - are you still planning on working on this and submitting a patch?

TR’s picture

Assigned: Shashwat Purav » Unassigned
gfcamilo’s picture

Assigned: Unassigned » gfcamilo
gfcamilo’s picture

Assigned: gfcamilo » Unassigned
JayKandari’s picture

I think Issue description should be updated corresponding to version : 8.x-4.x-dev. Kindly Confirm. Thanks

JayKandari’s picture

This might help anyone who picks up this issue.
Following sub modules have already implemented hook_help(). Some of them needs fix.

payment/uc_2checkout/uc_2checkout.module:11: * Implements hook_help().
payment/uc_credit/uc_credit.module:45: * Implements hook_help().
payment/uc_paypal/uc_paypal.module:15: * Implements hook_help().
shipping/uc_fulfillment/uc_fulfillment.module:19: * Implements hook_help().
uc_ajax_admin/uc_ajax_admin.module:14: * Implements hook_help().
uc_attribute/uc_attribute.module:32: * Implements hook_help().
uc_cart_links/src/Tests/CartLinksTest.php:32:    // System help block is needed to see output from hook_help().
uc_cart_links/uc_cart_links.module:14: * Implements hook_help().
uc_catalog/uc_catalog.module:23: * Implements hook_help().
uc_file/uc_file.module:27: * Implements hook_help().
uc_order/uc_order.module:30: * Implements hook_help().
uc_report/uc_report.module:19: * Implements hook_help().
uc_role/uc_role.module:22: * Implements hook_help().
uc_stock/uc_stock.module:19: * Implements hook_help().
uc_store/uc_store.module:135: * Implements hook_help().

Ubercart Submodules.

./payment/uc_2checkout/uc_2checkout.module
./payment/uc_authorizenet/uc_authorizenet.module
./payment/uc_credit/uc_credit.module
./payment/uc_payment/uc_payment.module
./payment/uc_paypal/uc_paypal.module
./shipping/uc_fulfillment/uc_fulfillment.module
./shipping/uc_quote/uc_quote.module
./shipping/uc_ups/uc_ups.module
./shipping/uc_usps/uc_usps.module
./uc_ajax_admin/uc_ajax_admin.module
./uc_attribute/uc_attribute.module
./uc_cart/tests/uc_cart_entity_test.module
./uc_cart/uc_cart.module
./uc_cart_links/uc_cart_links.module
./uc_catalog/uc_catalog.module
./uc_file/uc_file.module
./uc_googleanalytics/uc_googleanalytics.module
./uc_order/uc_order.module
./uc_product/uc_product.module
./uc_product_kit/uc_product_kit.module
./uc_report/uc_report.module
./uc_role/uc_role.module
./uc_stock/uc_stock.module
./uc_store/uc_store.module
./uc_tax/uc_tax.module

It'd be great if maintainer can give help by providing exact texts to use as help description for each of the above modules those do not have hook_help() implemented.

Thanks!

TR’s picture

You're not helping me if you need me to provide all the text.

I think this task is self-explanatory - all the modules in Ubercart need review to update/enhance/create the information in hook_help() in order to make the help mechanism more useful to Ubercart users and to take advantage of changes that Drupal core has made to the help system (e.g. https://www.drupal.org/node/2669966 and https://www.drupal.org/node/2669988). I would also like to see some links pointing to the more detailed help documents under http://drupal.org/documentation/modules/ubercart, and improvement of that documentation as needed.

If you don't know enough about the modules, then this is a great way to learn more about Ubercart - do the research and come up with a help implementation that is useful to you as a new Ubercart user. That's why this is marked as a Novice issue. A review of Drupal core to see what sort of information is typical would be a good start, but be aware that a lot of Drupal core also needs some work on hook_help().

JayKandari’s picture

Assigned: Unassigned » JayKandari

Picking this.

JayKandari’s picture

Assigned: JayKandari » Unassigned
Status: Active » Needs review
FileSize
59.25 KB

Hi,

Please find changes done in attached patch.

All modules reviewed and updated/added their hook_help() implementations.
Help texts standards as per Drupal Template (https://www.drupal.org/node/632280).
Help pages contain links to specific pages of Ubercart documentation.

Kindly Review. Thanks :)

Status: Needs review » Needs work

The last submitted patch, 17: implement_hook_help-751976-17.patch, failed testing.

JayKandari’s picture

Test failed because of :
uc_cart_links/src/Tests/CartLinksTest.php:97:

    // Test presence of and contents of Help page
    $this->clickLink(t('View the help page'));
    $this->assertText(
      'http://www.example.com/cart/add/<cart_link_content>',
      'Help text found.'
    );

Help here !! What todo next?

TR’s picture

This looks like a good start.

uc_cart_links has a better help implementation than any other module in Ubercart, so it should be used as an example. Specifically, any help text other than trivial one-liners should probably be put into a Controller class like uc_cart_links does - this way the help text is only loaded when needed, not on every single page view, and the help text can be maintained separately from the code in .module.

uc_cart_links also has a test case which tests to make sure the help text shows up where expected. The reason that test fails is because you redefined help.page.uc_cart_links, so that page no longer contains the text that the test is looking for. If you want to modify the help text at help.page.uc_cart_links then you need to modify CartLinksHelpController.

JayKandari’s picture

Assigned: Unassigned » JayKandari
JayKandari’s picture

Assigned: JayKandari » Unassigned
Status: Needs work » Needs review
FileSize
59.74 KB

Reverted defining help.page.uc_cart_links case in uc_cart_links.module file.
Added, section headers to uc_cart_links/src/Controller/CartLinksHelp.php file.

Local tests passed successfully. Changing status.

Kindly Review :) Thanks !

JayKandari’s picture

sumitmadan’s picture

Status: Needs review » Reviewed & tested by the community
JayKandari’s picture

Issue tags: +SprintWeekend2017
TR’s picture

Status: Reviewed & tested by the community » Needs work

@sumitmadan: It would help if you would detail what you looked for when you reviewed the patch, that way we would know that your review added value and was not simply a favor for a co-worker... As it stands, your RTBC isn't saving me any effort because I don't know what has been examined already ...

I noticed several unneeded "use" statements added in, as well as at least one line that was apparently accidentally modified - "affiliate' sales". I would also like to examine the provided links before this goes in - most appear to point to the top-level ubercart documentation page, but I think there are probably more specific places to link to. Or if not, then those more-specific pages should be created because this points out gaps in our documentation. Also a style note: we prefer [] instead of array() in most places, especially for the second parameter passed to t(). And trailing "," for array elements are only appropriate if the array elements are each on separate lines, like you might do in a form definition, not when the elements are inline.

JayKandari’s picture

Assigned: Unassigned » JayKandari
JayKandari’s picture

Assigned: JayKandari » Unassigned
Status: Needs work » Needs review
FileSize
58.03 KB
68.16 KB

Updated previous patch

* Unnecessary use statements removed.
* changed array() to [].
* corrected existing texts.
* trailing commas in inline arrays removed.
* help linked with Main ubercart online document, specific settings documentation pages and to internal links.

Kindly Review, Thanks !!

gmaltoni’s picture

Status: Needs review » Reviewed & tested by the community

Hi @yago-elias,

It's good for me.

Congrats.