The link module only has an about section but no "Uses". After improving the link documentation page https://drupal.org/documentation/modules/link more help content should be added.

Files: 
CommentFileSizeAuthor
#39 link_help_tested.png52.96 KB-enzo-
#37 link-help-text-2028799-37.patch3.25 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,908 pass(es).
[ View ]
#37 interdiff-2028799-link-35-37.txt3 KBifrik
#35 link-help-text-2028799-35.patch3.23 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,532 pass(es).
[ View ]
#35 interdiff-2028799-33-35.txt2.33 KBifrik
#33 link-help-text-2028799-33.patch3.11 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,530 pass(es).
[ View ]
#33 interdiff-2028799-22-33.txt4.38 KBifrik
#30 link-help-text-2028799-30.patch3.11 KBbatigolix
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch link-help-text-2028799-30.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]
#22 link-help-text-2028799-22.patch3.31 KBifrik
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch link-help-text-2028799-22.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]
#22 interdiff-2028799-20-22.txt4.83 KBifrik
#20 link-help-text-2028799-20.patch2.8 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,429 pass(es).
[ View ]
#20 interdiff-2028799-17-20.txt5.53 KBifrik
#17 link-help-text-2028799-17.patch3.8 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,122 pass(es).
[ View ]
#13 link-help-text-2028799-13.patch4.17 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,486 pass(es).
[ View ]
#9 link-help-text-2028799-9.patch3.59 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,132 pass(es).
[ View ]
#6 link-help-text-2028799-6.patch3.3 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,218 pass(es).
[ View ]
#4 link-help-text-2028799-4.patch3.13 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 57,952 pass(es).
[ View ]
#1 link-help-text-2028799-1.patch3.19 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 57,903 pass(es).
[ View ]

Comments

ifrik’s picture

StatusFileSize
new3.19 KB
PASSED: [[SimpleTest]]: [MySQL] 57,903 pass(es).
[ View ]

I've added Uses for allowing and displaying link texts, adding "nofollow" and displaying placeholders.
In case more more functionality is added, more uses should still be added in future.

ifrik’s picture

Status:Active» Needs review
jhodgdon’s picture

Status:Needs review» Needs work

Thanks... I'm not sure that the items here are really "uses" of the Link module. The Link module is a field used to display links. The "uses" listed here are just the specifics of how to configure that field, and I don't think they really need to be described as separate "uses". Maybe... I could be convinced. :) But maybe the uses should just say "Configuring the field" and "Configuring field display", and list what can be done in each of these categories of "uses"?

I'm also not certain that the Drupal 8 core Link module supports all of the options you have stated in this help, or that they are on the same URL paths as they were in Drupal 7. Did you actually test this in Drupal 8?

Finally.... If we do want to add this text, there are some formatting issues in the patch (indentation in the code) and grammatical issues in the text (the main one I saw is that the word "text" as used in "link text" is not a countable noun, so it should not be made plural into "link texts").

Thoughts?

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3.13 KB
PASSED: [[SimpleTest]]: [MySQL] 57,952 pass(es).
[ View ]

I admit that this is not the most important issue at the moment - but I'm at the code sprint of the DevDays and wanted a simpler bit to start with.
All is done and tested on the latest D8 dev version.
I followed https://drupal.org/node/632280, and the indentation as I found it in the module file.
I've changed some of the wording.

jhodgdon’s picture

Status:Needs review» Needs work

This issue is just as important as any other documentation issue! Patches improving documentation are always welcome. I appreciate your efforts now, and others will appreciate it down the road. :)

So... This is looking better! I still think it can use some improvement:

a) I noticed the link to the on-line help is using http://drupal.org but I think it should probably be https now?

b) In the same way that "link text" cannot be made plural because it is not a countable noun, it also cannot be counted as the number one, for instance: "a link text". Just say "link text" without the "a". For example: "To enable the addition of a link text" should be "To enable the addition of link text". Also, I'm still seeing "texts" in the Placeholders section. It should just be "text". (The countable word "texts" means something like "books or documents", not "little pieces of text".)

c) I still think this would be clearer if it separated the "manage" operations from the "display" operations. How about this structure:
Uses

Configuring link field settings
To configure the settings for a link field, go to [your description of how to get to Manage Fields/edit]. On this page, you can:
  • Toggle whether link text is entered: ...
  • Use placeholders: ...
Configuring link field display
To configure the display settings for a link field, go to [your description of how to get to Display Fields, including the cog]. In this dialog, you can:
  • Display URL, link text, or both: ...
  • Add "rel" and other attributes
ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3.3 KB
PASSED: [[SimpleTest]]: [MySQL] 58,218 pass(es).
[ View ]

Thanks for your comments.
I re-arranged and reworded them accordingly. Grouping them is a good way to get rid of the repetitions.

jhodgdon’s picture

Status:Needs review» Needs work

This looks good! I like the text, and I think the organization is much better. A few To Dos:

a) There is a spelling error: approbriate [b>p]

b) I think we normally say to "click" links rather than "choose" links.

c) Link fields can be added to many other things besides node content types (taxonomy terms, users, etc.), now that I think about it. I'm not sure what to do about it... Maybe in the instructions for how to get to the configuration screen we should say something like "find the Manage Fields page for the content type, taxonomy vocabulary, or other [entity bundle] that your Link field is attached to. For instance, if it is attached to a content type, [the instructions you wrote]". Thoughts? Maybe you can word it better. And as a note, I'm not sure what word we are using for "entity bundle", which is the programmer term but I'm sure we are not using that in the Drupal UI.

d) Same as C for the Manage Display instructions.

e) In the Drupal project, we use serial commas. So: "option a, option b, or option c" (need a comma before "or" in "Display URL, link text or both").

f) A reviewer (other than the person who made the patch) needs to install this patch on a Drupal 8 site and verify that:
- It formats well on the help page
- The descriptions of how to do things are accurate
- The text matches the UI text
- The links work
So we should tag this issue "needs manual testing" once the known issues in the patch are taken care of.

batigolix’s picture

c) I prefer to refer to entities as follows:

entity (content type, user, taxonomy term or comment)

For example:

You can add a link field to an entity (content type, user, taxonomy term or comment) by adding a geofield.

So in this case we might use:

To configure the settings for a link field, edit the entity (content type, user, taxonomy term or comment) and choose the Manage fields link for the content type.

You can leave the link on the word "content type" (maybe add links on the other entities. dunno if that is possible)

f) im trying to review the patch but my version of d8 is broken :(

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3.59 KB
PASSED: [[SimpleTest]]: [MySQL] 58,132 pass(es).
[ View ]

I've added the term ' "fieldable" entity' with a few examples, since that is also used on the field help page. Under uses I left the link to the content pages just as an example, even though it's double now.

I thought about just linking 'fieldable entity' to the field page and leave out the examples, but site builders and site administrator who are most likely to look at this help might not be completely aware of the concept and they shouldn't need to go from help page to help page if at that moment they just want to change a configuration.

jhodgdon’s picture

Status:Needs review» Postponed
Issue tags:+Needs usability review

I think your method of referring to entities is good, batigolix... but your preference and my preference are not exactly what matters. In the Drupal Core UI, we try to be consistent. So we need to figure out what the Usability Team has decided to standardize on.

Also, we do have a standard for serial commas, so it would be "... taxonomy term, or comment...". :)

And in your last example:
"To configure the settings... Manage fields link for the *entity*" (not *content type*) right?

Since we have a UX text question,... actually I think we should file a separate issue to figure out how to refer to entities in the UI for Drupal 8. It needs to be added to this page:
https://drupal.org/node/604342

Here's an issue:
#2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI

We should postpone this issue until this has been decided.

ifrik’s picture

Status:Postponed» Needs review
Issue tags:-Needs usability review

I'm now wondering whether it should be added that only web protocols (http and https) validate - and that other scheme names (ftp, git, etc) are not supported.

jhodgdon’s picture

Status:Needs review» Postponed

Yes, I think that is worth mentioning. In the first sentence, you could say "...external URLs starting with http: or https:..." for instance?

Anyway, we still need to postpone this issue due to comment #10.

ifrik’s picture

StatusFileSize
new4.17 KB
PASSED: [[SimpleTest]]: [MySQL] 58,486 pass(es).
[ View ]

I've added supported formats, and that entity reference can be used for internal links.
This is still postponed due to comment #10 and #2029751: Create hook_help for entity reference

jhodgdon’s picture

I don't really like how this last change is set up very much... Can't it just be added to the About section as a short note like I suggested in #12? Having a whole section on what the Link module doesn't support in the Uses section seems like overkill, and it's also more of a "this is what it isn't used for" than a "this is what it's used for", so I don't think it belongs in "uses" at all.

ifrik’s picture

How about this?

About
The Link module defines a simple link field type for the Field module. It allows the addition of link fields to any "fieldable" entity (content types, blocks, taxonomy terms, users, etc.). Links are external URLs, can have optional link text, and can be formatted when displayed. They must include the web protocol (http or https) in order to validate during input; other scheme names (ftp, git, etc.) are not supported. Use Entity reference for internal links.
For more information see the Field module help page, and the online handbook entry for Link module.

batigolix’s picture

We can rewrite this by explaining in the About section what kind of links and protocols are supported by the Link module, like e.g.

The Link module provides a field for external URLs (http:// or https://). The links can be displayed as URL or as a clickable link.

ifrik’s picture

StatusFileSize
new3.8 KB
PASSED: [[SimpleTest]]: [MySQL] 58,122 pass(es).
[ View ]

I think it's important to mention that other external links are not supported, because it's somewhat unexpected. Not only was it possible in D7 to submit for example ftp links, also the default editor allows the use of ftp and news.
I've submitted a feature request for the validation of more scheme names - if that gets done then of course this becomes obsolete.

jhodgdon’s picture

This looks better! A few thoughts:

a)

They must include the web protocol (http or https) in order to validate during input; other scheme names (ftp, git, etc.) are not supported.

The same concept is referred to as "web protocol" and "scheme name" in the same sentence. Choose one and stay consistent.

b) Don't put <br> in there. Either make a new paragraph or just remove it to stay in the same paragraph; in any case the correct tag would be <br />

c) The first two sentences in About seem kind of short and choppy. Maybe combine into one sentence?

d) "Links are external URLs"... I don't think a link *is* a URL, rather than it *links to* a URL. This maybe needs to be reworded?

e) The correct punctuation of "e.g." is that it nearly always needs a ; before it and a , after it. Better yet, use "for example" instead of "e.g." because nearly everyone confuses e.g. and i.e. and I can't tell you how many patches I've made and/or committed in the documentation of Drupal to fix this confusion.

And once we figure out how we're referring to "entities", some more rewriting will be needed of course.

ifrik’s picture

Thanks,
I reworded it, and now I'll wait for an "entity" decision.

ifrik’s picture

Status:Postponed» Needs review
StatusFileSize
new5.53 KB
new2.8 KB
PASSED: [[SimpleTest]]: [MySQL] 58,429 pass(es).
[ View ]

Taking up the previous comments in this thread and the proposal from #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI.

With the proposed references to the Field and Field UI help pages, the separation and some explanations about field settings and display are not necessary here anymore, so I got rid of the two Uses sections again.

jhodgdon’s picture

Status:Needs review» Needs work

Thanks! A few updates I think are needed:

a) Can we make the link to the online docs follow our standard format? http://drupal.org/node/632280

b) The code indentation is not correct in this patch.

c) The word "text" as in "link texts" should not be plural.

d) In the "Using link texts" [sic] section, some of the instructions seem to be referring to the field settings forms and some to the display forms. I think it's pretty confusing. This applies to most of the other Uses sections too... Just saying "click on the cog icon" is not good enough, because they aren't on the Manage Display page to begin with, they're reading this help page.

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new4.83 KB
new3.31 KB
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch link-help-text-2028799-22.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

Thanks for the comments.
a) fixed the reference to the online documentation (and fixed it in my notes for future reference as well...)
b) fixed code indentation
c) fixed "texts"
d) I separatet the "link text" again into two different uses, and tried to make clearer where changes should be done.
The wording sounds a bit clumsy to me me, but that has to do with the way all the pages with settings are sometimes called settings and sometimes not. For example under "Manage Fields" for a fieldable entity, you can choose "Edit" or "Field settings". And by choosing "Edit" you get a different set of settings...
I'm refering to the different tabs like "Manage fields" as "Field management tab", but I'd be happy to hear better suggestions.

Status:Needs review» Needs work

The last submitted patch, link-help-text-2028799-22.patch, failed testing.

jhodgdon’s picture

Good question about how to refer to things... The Field UI help should ideally tell us in general how to edit field settings and display settings, and hopefully make that distinction. So maybe in individual field modules, after the heading you already have there about field and display settings (the first item in Uses), we can do something like this:

Adding link text

Link text can be set to optional or required in any link field.

Displaying links

There are display settings options for displaying the URL as plain text, the URL as a link, the URL with the supplied link text, and other options.

...

Thoughts? It seems like that would be much simpler.

jhodgdon’s picture

Actually, I think just saying "this is a field setting" or "this is a display setting" is both simpler and clearer, and that's the main objective for documentation. :)

So maybe if we adopt this format, we should also change the standard heading for the first uses bullet point to:

Field and display settings

?

jhodgdon’s picture

And then the Link Text thing should maybe read:

There is a field setting that lets you set link text to be optional or required in any link field.

batigolix’s picture

We should refer to the "Field management tab" as follows:

the Manage fields tab

or maybe even simpeler:

the Manage fields page

The part in italics should be something the user can find literally on the page.

I think that is how we have always done, although I have not much evidence to back this up. But in the hook_help for the image module it says:

To add an image field to a content type, go to the content type's manage fields page, and add a new field of type Image.

jhodgdon’s picture

I completely agree with #27.

ifrik’s picture

#27 sounds good. I'll apply that wording in other help texts as well

batigolix’s picture

StatusFileSize
new3.11 KB
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch link-help-text-2028799-30.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

Patch:

- fixes comments from #27, #26
- fixes links according to new standard https://drupal.org/node/632280#url-note

batigolix’s picture

Status:Needs work» Needs review

Change status

Status:Needs review» Needs work

The last submitted patch, link-help-text-2028799-30.patch, failed testing.

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new4.38 KB
new3.11 KB
PASSED: [[SimpleTest]]: [MySQL] 58,530 pass(es).
[ View ]

Patch 30 was corrupted for me, so here it is the new text as changed by Batigolix again, together with an interdiff.
I'm happy with the text, and it would be great if we can get this one finished before the DrupalCon sprint on Friday, so we can use it as an example for modules for fieldable entities.

jhodgdon’s picture

Status:Needs review» Needs work

I think this is looking very good!

I only have a few small suggestions:

a) In the "Displaying link text" item in Uses, I think it should say ... choose Link as **the** format... ("the" is missing there).

b) I also think the beginning of that item could use a bit of work: "By default, link text is displayed instead of the URL."... By default, a link field is displayed as a link to the URL with the entered text as the link text, right? So both the URL and the entered link text are used to format the link. The text as it is made me scratch my head to figure out what it meant.

c) In the last Uses item, I think you should use the term "scheme" in the first part where you say only http and https are supported, and not suddenly introduce it in the last part. Not everyone will know what it means, and the extra context will make it clear.

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new2.33 KB
new3.23 KB
PASSED: [[SimpleTest]]: [MySQL] 58,532 pass(es).
[ View ]

Fixed according to #34 comment 1 and 3.
Changed the text in "Displaying link text" around to make the three different options more obvious.

jhodgdon’s picture

Status:Needs review» Needs work

Looking really good! I think this is all very clear and it reads very well.

There are just a couple of typographical/grammatical things to fix now:

a) "In the field settings you can define a link text to be optional..." -- I don't think "link text" is a countable noun. I would suggest "the link text" instead of "a link text".

b) "t(' If link text has been submitted for a URL..." -- there is an extra space at the beginning between ' and If

c) "Links need to start with either with the scheme name " -- two "with"s there.

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3 KB
new3.25 KB
PASSED: [[SimpleTest]]: [MySQL] 58,908 pass(es).
[ View ]

a) I used "additional link text" instead "the" to make it a bit clearer.
b) fixed
c) changed. I also figured out that I to keep the info about scheme names together, I could just as well move the sentence about anchors forward.

jhodgdon’s picture

Issue tags:+Needs manual testing

Looks good to me!

Someone needs to give this some manual testing:
- Make sure the text in the help matches the text in the Drupal user interface
- Make sure all the links work correctly

-enzo-’s picture

Status:Needs review» Reviewed & tested by the community
StatusFileSize
new52.96 KB

The patch was tested successfully, all text match and the links are working.

Check the attached image.

link_help_tested.png

Boaah’s picture

#37: link-help-text-2028799-37.patch queued for re-testing.

Boaah’s picture

Retested it as a second test during the drupal mentoring sprint. I can confirm -enzo-'s statement. The text matches and and the urls lead to the right pages.

Boaah’s picture

Assigned:ifrik» Unassigned

Retested it as a second test during the drupal mentoring sprint. I can confirm -enzo-'s statement. The text matches and and the urls lead to the right pages.

duplicate

alexpott’s picture

Status:Reviewed & tested by the community» Fixed

Committed ba6cdc2 and pushed to 8.x. Thanks!

Automatically closed -- issue fixed for 2 weeks with no activity.