Link to demo on each widget page that has one

[jzaefferer]

Picking one idea from #115:

There should be a link to the corresponding demo page on each widget page. It should be styled to stand out. A good spot might be to the right of the page title, somthing like this: (not really this styling, something that looks good).

This would also work for jQuery Mobile. Since the URLs don't have the same scheme, a good option might be to implement an optional attribute or element in the XSLT that gets output as a link, if present. So we'd just add the URL to the demo where it applies.

We should also make the link to the API documentation much easier to spot on our demo pages. The style of both links should probably be the same.

If that sounds good, I can create tickets in the appropriate repos, along with patches.

[scottgonzalez]

I like this idea, but it's confusing that there's a big demo link that doesn't go to the examples on the page. Maybe we should have a single example at the bottom which also links to the full demo section.

[tjvantoll]

I like this idea, but it's confusing that there's a big demo link that doesn't go to the examples on the page. Maybe we should have a single example at the bottom which also links to the full demo section.

I agree that it's confusing to have Examples and Demos links in the same vicinity of the page, but I think having the full demo section link at the bottom of the page hides it too much.

I'll throw out two ideas. With either of these I think @jzaefferer's callout link to the demos makes sense. Let me know what you think.

1. Move the "examples" section to the top of the page, make sure there is only one example that shows the most basic usage of the widget.

The example then serves as an intro to the usage of the widget. The subsequent content shows more customized usage (options, methods, events, etc). If we collapse the source by default it shouldn't take up too much space.

2. Remove the examples from the API docs entirely. The examples are nice when they're integrated into the docs (like some of jQuery mobile's), but in their current location they're kind of hidden anyways.

[jzaefferer]

Both of TJ's suggestions above sound good to me. @scottgonzalez what do you think?

[scottgonzalez]

I like the first suggestion. @jquery/mobile thoughts?

[agcolom]

I'm in favour of the 1st suggestion also. I think it'd be a shame to remove the examples from the API docs entirely.

[arschmitz]

im in favor #1 as well i think it works better for mobile and how our demos work also

[jaspermdegroot]

+1 to @tjvantoll's first suggestion as well.

How are we going to deal with versions? Not only for links from the API docs to the Demos, but also the other way around.

[scottgonzalez]

The entries will have to provide a URL for the demos. That will be managed manually.

[jzaefferer]

Currently the Quicknav links to Examples. Would that go away? Where exactly should the examples get displayed? Before or after Quicknav? Elsewhere? Where would the Demos link go then?

[scottgonzalez]

Currently the Quicknav links to Examples. Would that go away?

I don't think so.

Where exactly should the examples get displayed?

Right after the QuickNav. There would be only one demo.

Where would the Demos link go then?

Right after the example. Likely with some text like "See more demos."

[tjvantoll]

My 2 cents are below.

Currently the Quicknav links to Examples. Would that go away?

Yes. Unless we make "QuickNav" into "Nav" (see below).

Where exactly should the examples get displayed? Before or after Quicknav?

Directly after.

Where would he Demos link go then?

I think what you have here is fine. Or something along the lines of "See more demos" is fine too.

I'll throw out one more idea. I personally would like to see the "QuickNav" just become "Nav" - aka I want the entire outline in there. This solves the "where does the examples link go" problem and gives us a way of linking to anything on the page. For example:

Nav

• Example
• Keyboard Interaction
• Theming
• Dependencies
• Notes
• Options
  • active
  • etc
• Methods
  • destroy
  • etc
• Events
  • active
  • etc
• Extension Points
  • _whatever

[scottgonzalez]

That'll require some design work and updates to all of the entries, but I think that might be a good change.

[scottgonzalez]

@jquery/content @jquery/ui @jquery/mobile Let's revive this and make some progress. Please review the previous discussion and reply with either support for an existing proposal or a new proposal. It's been quite a while since this discussion died down, so I'd like to have people review it before we proceed.

[agcolom]

I think it'd be good to have the basic example(s) that we currently have in the api docs, and they may be more suitable right at the top of the page, probably straight after the description.

We can then remove the examples link in the quick nav and add one for Demos at the top, floated to the right, that links to the widget demo page, possibly in a new tab since this is technically outside of the api docs.