Block type: add support link #11330

simison · 2018-10-31T20:42:28Z

Description

I've added a way to declare where block's support documentation lives, via a block type options.

The link would appear under block description either as an external or internal link.

During our block development, we've started adding links to support documentation directly in "description" option. It works for desktop visually but isn't obviously great declaratively since it's no more just "description" and also goes against Gutenberg design rules:

description: (
  <Fragment>
    <p>
      { __(
        'Simple Payments lets you create and embed credit and ' +
          'debit card payment buttons on your WordPress.com and ' +
          'Jetpack-enabled sites with minimal setup.'
      ) }
    </p>
    <ExternalLink href="https://support.wordpress.com/simple-payments/">
      { __( 'Support reference' ) }
    </ExternalLink>
  </Fragment>
)

Would be great to have a declarative way to add support documentation and make it easier to show in an optimal way in other places such as mobile devices. Something like:

support: {
  url: 'https://support.wordpress.com/simple-payments/',
  label: __( 'Support reference' ),
  external: true,
},

This is a quick prototype; if you think it's a good idea, I'm happy to look into what other work might be needed to adding such support.

Further ideas:

This could also support passing URL as a string:

support: 'https://wordpress.org/gutenberg/handbook/'

Could support adding multiple links as an array
The label could be made optional, defaulting to something like "Support reference".
Instead of support, the option could also be called documentation.
URL could be passed through prependHTTP

How has this been tested?

WIP

Screenshots

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.

gziolo · 2019-02-04T13:00:43Z

For me personally, it feels like plugins territory. I would love to hear feedback from others.

jasmussen · 2019-02-04T13:03:10Z

I'm tempted to hear more use cases and examples of where this might make sense.

Honestly it feels like links like these should be less "cookie cutter", and rather be worked into the prose of the paragraph, like a simple hyperlink. But could be I'm missing something?

gziolo · 2019-02-04T14:29:56Z

Honestly it feels like links like these should be less "cookie cutter", and rather be worked into the prose of the paragraph, like a simple hyperlink. But could be I'm missing something?

The description is text only at the moment, so it would be a raw link included...

simison · 2019-02-04T16:43:48Z

The description is text only at the moment, so it would be a raw link included...

You mean it's supposed to be... 😅

https://github.com/Automattic/wp-calypso/blob/83f7629381613eb5de5403c29180a0e846ad1f53/client/gutenberg/extensions/markdown/index.js#L22-L29

it feels like plugins territory.

@gziolo I don't follow you — wanna elaborate what you mean?

gziolo · 2019-02-04T17:03:17Z

it feels like plugins territory.

@gziolo I don't follow you — wanna elaborate what you mean?

I mean that they can use blocks.registerBlockType filter to override the description.

The description is text only at the moment, so it would be a raw link included...

You mean it's supposed to be... 😅

I assumed it's text only, but it looks like we never validate it :) It makes only this whole process easier.

/cc @youknowriad and @aduth - this is an interesting finding, it might mean that most of the fields we consider as string only might, in fact, accept components.

aduth · 2019-02-04T17:38:46Z

I've encountered this too in the past. It's quite easy to overlook, unfortunately.

gutenberg/packages/notices/src/store/actions.js

Lines 44 to 47 in a1b1eec

    
           // The supported value shape of content is currently limited to plain text 
        
           // strings. To avoid setting expectation that e.g. a WPElement could be 
        
           // supported, cast to a string. 
        
           content = String( content );

It makes me conflicted because I think we're better to set the expectations earlier than to have it break at a point in the future, but the contract we establish makes it clear that this is to be a string, regardless of what other values incidentally happen to work.

https://wordpress.org/gutenberg/handbook/designers-developers/developers/block-api/block-registration/#description-optional

simison · 2019-02-04T18:12:10Z

I'm tempted to hear more use cases and examples of where this might make sense.

Perhaps also a good place for:

upsell links for a premium version of the block
if block integrates with external service, there would be "Manage account" / "Register account" -link.

I mean that they can use blocks.registerBlockType filter to override the description.

Why would block builder do that vs what we've done? Shouldn't description still be considered a string even when modified via filter?

jasmussen · 2019-02-05T07:40:17Z

Those use cases are totally fair, thanks for elaborating, and it especially makes sense in light of the textfield not allowing links (or it shouldn't). I'm not entirely sure a separate link below the box is the right solution though... maybe it is? It feels, to repeat myself, cookie-cutter: this is where you put text, this is where you put a link. It's great to provide APIs that are limited so as to ensure accessibility and usability even for plugins, but I'd love a sanity check on these thoughts.

sarahmonster · 2019-02-05T09:43:36Z

❤️ Anything that makes documentation more findable for users when they need it is a 👍 from me. Having an explicit mechanism for plugin developers to link to their documentation will ideally encourage developers to use it more.

Ideally, this would be something we could expand in the future to provide inline help directly, rather than taking the user to a new site, making for a more seamless and uninterrupted flow.

I'd be in favour of keeping the link separate from the description. This has a few benefits:

a consistent place for users to look for help
easier to manage translations
more immediately visible when scanning the page
the description doesn't need to be reworded to support a help link (potentially making it longer)

Regarding wording, I'd opt for "Help" or "How-to" or even just "Documentation" rather than "Support reference" here. (Added tag for copy review.)

It would be great to get an accessibility perspective on this proposed change as well. (Added tag for accessibility feedback.)

danjjohnson · 2019-02-05T10:22:28Z

I second everything @sarahmonster said. I think "Help" or "Documentation" would be better than "Support Reference", and I think keeping it separate from the description would be best.

jasmussen · 2019-02-05T10:34:00Z

It sounds like a consensus is emerging!

michelleweber · 2019-02-05T11:11:16Z

"Support reference" and "documentation" both sound a little... serious? They're not normal-speech words for most people. "Help" feels like it doesn't give me quite enough context re: what happens when I click -- does that open a chat window, an email, a webpage?

I'd love something that felt a little more relaxed but with a little more info, like "Setup details"/"Block details" if it needs to be short, or "How to use this block" or "Learn more about this block" if that can be accommodated.

mapk · 2019-02-06T00:23:06Z

I like "Learn more about this block" as pointed out by @michelleweber, or even "Learn more" would work for me.

I also like how it's displayed in the initial post... a link at the bottom of the description. My reasons are that it's right inline with what I'm reading, and that feels like the place I'd expect to see any help links if there were any.

gziolo · 2019-02-06T12:29:46Z

@simison - we are working on defining the server-side friendly definition of blocks, there is RFC opened which would be a great place to include your proposal given that it seems like there is agreement that it would be a nice addition. We will need to have this new property documented so it should be win-win if it's taken into account there from the start.

simison · 2019-02-06T13:55:35Z

packages/editor/src/components/block-inspector/index.js

+							{
+								blockType.support.external ? (
+									<ExternalLink href={ blockType.support.url }>
+										{ blockType.support.label }


We prolly need to cast this as a string to be on the safe side.

We prolly need to cast this as a string to be on the safe side.

Did you still intend to make this change?

simison · 2019-02-06T13:56:02Z

@gziolo nice, so since folks are in favour of this feature, I can add docs in this PR (to here) — or did you mean I should chime in at RTC proposal?

I'll also rename the default label to "Learn more" (remember it's just default and possible to override).

gziolo · 2019-02-07T08:12:21Z

There is also:
https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-registration.md

There might be more documents which mention Block API :)

At some point, we will have to include it in RFC, too. Ideally, the proposed structure can be defined inside a JSON file.

aduth

How can we move this forward? From the conversation here, it seems there still needs to be implemented support for the default label?

Is it considered blocked by the Block Registration RFC (#13693) ?

aduth · 2019-04-24T14:26:31Z

packages/editor/src/components/block-inspector/index.js

+					{ hasSupportLink && (
+						<div className="editor-block-inspector__card-support">
+							{
+								blockType.support.external ? (


Can you explain what makes a support link "external"? Is it based on the origin/hostname of the URL, and if so, is that not something we should programmatically determine on behalf of the block developer, than to impose on them?

aduth · 2019-04-24T14:26:39Z

packages/editor/src/components/block-inspector/index.js

+							{
+								blockType.support.external ? (
+									<ExternalLink href={ blockType.support.url }>
+										{ blockType.support.label }


We prolly need to cast this as a string to be on the safe side.

Did you still intend to make this change?

draganescu · 2019-11-22T14:01:40Z

@simison @gziolo apparently this was a good idea which went stale. Can it still move forward?

youknowriad · 2020-03-18T10:56:05Z

Trying to triage PRs today. It seems that this PR is stale. I'm going to close it for now. Thanks all for your efforts.

@mtias I was also wondering what you think about this config? and whether it's worth considering refreshing this PR?

mrfoxtalbot · 2022-02-03T13:07:24Z

I find that providing an inline support link right next to the block description could have a positive impact on the learning curve of new users. This would be particularly true in the case of blocks added by plugins, which can be considerably more complex than the ones in core.

Could we open this PR just to revisit this? Thank you!

Block type: add support link

6ce733d

simison mentioned this pull request Nov 13, 2018

Markdown block: move support link away from description Automattic/wp-calypso#28416

Closed

gziolo added the Needs Design Feedback Needs general design feedback. label Feb 4, 2019

gziolo requested review from jasmussen, mapk, kjellr, melchoyce, sarahmonster and karmatosed February 4, 2019 12:58

gziolo added the [Feature] Blocks Overall functionality of blocks label Feb 4, 2019

gziolo requested a review from youknowriad February 4, 2019 12:59

sarahmonster added Needs Accessibility Feedback Need input from accessibility Needs Copy Review Needs review of user-facing copy (language, phrasing) labels Feb 5, 2019

jasmussen removed the Needs Design Feedback Needs general design feedback. label Feb 5, 2019

gziolo added the [Type] Technical Prototype Offers a technical exploration into an idea as an example of what's possible label Feb 6, 2019

simison commented Feb 6, 2019

View reviewed changes

gziolo removed the Needs Accessibility Feedback Need input from accessibility label Feb 7, 2019

gziolo added this to the 5.2 (Gutenberg) milestone Feb 7, 2019

gziolo modified the milestones: 5.2 (Gutenberg), 5.3 (Gutenberg) Mar 4, 2019

youknowriad removed this from the 5.3 (Gutenberg) milestone Mar 18, 2019

aduth reviewed Apr 24, 2019

View reviewed changes

kjellr mentioned this pull request Aug 9, 2019

Add a help panel to the inserter available in all blocks #16813

Merged

simison mentioned this pull request Oct 2, 2019

Gutenberg extensions: visual regressions in Gutenberg 6.5 (=WP 5.3) Automattic/jetpack#13618

Closed

5 tasks

draganescu added the [Status] Stale Gives the original author opportunity to update before closing. Can be reopened as needed. label Nov 22, 2019

youknowriad closed this Mar 18, 2020

simison deleted the add/block-type-support branch March 18, 2020 11:11

simison mentioned this pull request Aug 11, 2021

Link to external documentation in Pattern creation snackbar #33481

Open

donalirl mentioned this pull request Sep 24, 2021

Add Support Link to Block Card Description Automattic/wp-calypso#56091

Closed

simison mentioned this pull request Aug 20, 2024

Block Registration: add SlotFill to extend a block's description #49887

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Block type: add support link #11330

Block type: add support link #11330

simison commented Oct 31, 2018 •

edited

Loading

gziolo commented Feb 4, 2019

jasmussen commented Feb 4, 2019

gziolo commented Feb 4, 2019

simison commented Feb 4, 2019

gziolo commented Feb 4, 2019

aduth commented Feb 4, 2019

simison commented Feb 4, 2019 •

edited

Loading

jasmussen commented Feb 5, 2019

sarahmonster commented Feb 5, 2019

danjjohnson commented Feb 5, 2019

jasmussen commented Feb 5, 2019

michelleweber commented Feb 5, 2019 •

edited

Loading

mapk commented Feb 6, 2019

gziolo commented Feb 6, 2019

simison Feb 6, 2019

aduth Apr 24, 2019

simison commented Feb 6, 2019

gziolo commented Feb 7, 2019

aduth left a comment

aduth Apr 24, 2019

aduth Apr 24, 2019

draganescu commented Nov 22, 2019

youknowriad commented Mar 18, 2020

mrfoxtalbot commented Feb 3, 2022 •

edited

Loading

Block type: add support link #11330

Block type: add support link #11330

Conversation

simison commented Oct 31, 2018 • edited Loading

Description

Further ideas:

How has this been tested?

Screenshots

Types of changes

Checklist:

gziolo commented Feb 4, 2019

jasmussen commented Feb 4, 2019

gziolo commented Feb 4, 2019

simison commented Feb 4, 2019

gziolo commented Feb 4, 2019

aduth commented Feb 4, 2019

simison commented Feb 4, 2019 • edited Loading

jasmussen commented Feb 5, 2019

sarahmonster commented Feb 5, 2019

danjjohnson commented Feb 5, 2019

jasmussen commented Feb 5, 2019

michelleweber commented Feb 5, 2019 • edited Loading

mapk commented Feb 6, 2019

gziolo commented Feb 6, 2019

simison Feb 6, 2019

Choose a reason for hiding this comment

aduth Apr 24, 2019

Choose a reason for hiding this comment

simison commented Feb 6, 2019

gziolo commented Feb 7, 2019

aduth left a comment

Choose a reason for hiding this comment

aduth Apr 24, 2019

Choose a reason for hiding this comment

aduth Apr 24, 2019

Choose a reason for hiding this comment

draganescu commented Nov 22, 2019

youknowriad commented Mar 18, 2020

mrfoxtalbot commented Feb 3, 2022 • edited Loading

simison commented Oct 31, 2018 •

edited

Loading

simison commented Feb 4, 2019 •

edited

Loading

michelleweber commented Feb 5, 2019 •

edited

Loading

mrfoxtalbot commented Feb 3, 2022 •

edited

Loading