x/pkgsite: Reset button for doc examples

[gertcuykens]

example: https://golang.org/pkg/html/template/#example_Template_block

The only way to reset a code example when you mest up trying something is to refresh the page. This is annoying if you are on a large page. Note that ussualy you are just on this url https://golang.org/pkg/html/template without a hash tag to the example directly so your page wil jump up when you refresh.

Possible solutions update the hash tag when you expand the example

Or introduce a reset icon somewhere. (where and how i am not sure yet, feel free to discuss)

[agnivade]

I think this can be solved by exposing a pilcrow (¶) symbol besides the examples too. Because once you have the link, you can just click on it and hit refresh and your page will come back to the original position.

This takes care of resetting the example contents and has the added benefit of making the examples more readily shareable. I find it cumbersome to go all the way up the page, find the example anchor link and share it.

@gertcuykens - Does that work for you ?

/cc @andybons , @bradfitz, @ysmolsky for opinions.

[gertcuykens]

Yep, that would solve it but don't know if it would be intuitive for others too?

[jimmyfrasche]

@agnivade The semantics of all the various expanding/collapsing sections are all over the place. It would be nice if they were unified, possibly including all having ¶s for quick linking as you suggest. They need a lot of work for #22171, probably a full rewrite. There are a lot of edge cases to work out.

I could see a reset button being useful, regardless. It might be more user friendly.

[agnivade]

but don't know if it would be intuitive for others too?

The original issue was that refreshing the page goes to the top because there is nothing to anchor to the example. And putting an anchor solves it. I don't understand where counter-intuitiveness comes into this ?

I could see a reset button being useful, regardless.

I am a soft negative on that. I think doing a quick refresh is cleaner than maintaining state and adding a button to revert to that state. Also, adding the button would probably need the change to be propagated to playground also to be consistent. I prefer godoc to be clean and minimalistic as it is. No strong opinions though.

[gertcuykens]

Agree on minimalistic. By intuitive I mean that everybody has a tendency to just refresh the page in general when something is wrong on the page, by page I mean any website. So if the url get hash tagged automatically when user scrolls down or in my case when I expand the example, then I don't need to know what (¶) stands for. I just refresh the page. Same philosophie as users hitting the back button on a single page app. It's just more intuitive then to click a back link.

[agnivade]

So if the url get hash tagged automatically when user scrolls down or in my case when I expand the example, then I don't need to know what (¶) stands for. I just refresh the page.

I don't think the url should be hash tagged automatically on expanding the example. That will cause confusion because it will jump to the top of page. The pilcrow symbol will be exposed on mouse-hover, same as the other structs and functions today. Hence, it becomes clear that if you click on the symbol, the example will get anchored and you are then free to refresh the page. I think this is pretty intuitive and explicit behavior.

[gertcuykens]

Technically you can prevent jumps using https://developer.mozilla.org/en-US/docs/Web/API/History_API But in reality it's to much js effort needed compared to your solution. And I prefer simplicity and consistency over everything so your solution is better :)

[jimmyfrasche]

The collapsible section headers (Overview, Index) use the same code as the examples. Would those get ¶ too? Regardless, do they go outside the clickable area of the toggle element?

[agnivade]

The collapsible section headers (Overview, Index) use the same code as the examples. Would those get ¶ too?

Hmm ... yea to be consistent, I would guess they need it too.

Regardless, do they go outside the clickable area of the toggle element?

I was thinking, we can show the ¶ beside the text (like Example (Block) ¶) itself on hover so that it is consistent with other structs and functions. And use an event propagation logic through js so that if you click on the ¶, the event does not percolate down to the toggle element, letting it act as an anchor link. Clicking on the toggle element anywhere outside ¶ preserves the hide/show behavior.

[jimmyfrasche]

You can't nest a tags. The browser'll force close the outer tag when it hits the inner a tag. I'm not sure that would work unless you were doing some wacky positioning to move the ¶ back over into the link area without overlapping the text.

Even if nested a tags worked or there was a reasonable workaround, you could diagram the clickable areas of that set up as [ toggle label ] [ ¶ ] [ invisible continuation of toggle area ]. That doesn't seem like ideal usability. The part that's not the toggle is invisible until you're over it which means accidentally hitting the ¶ when moving too fast. For the examples, I'm not entirely sure the "invisible continuation of toggle area" was intentional or just a result of the cascade. Even if it's okay to get rid of that, the same argument applies to the Index, etc., section headers which are 100% width.

It would be fine if it went ¶ ▹ Example but that looks a bit weird and then either those are flipped from the others which is a bit annoyingly irregular (and would seem random to a casual user until the pattern was worked out) or all of the ¶ need to be moved to the front which would be a change for people accustomed to them coming after the item.

[agnivade]

Gotcha. I will look into it.