Playing with web components and custom elements

[Mike "Pomax" Kamermans]

Hey all,

I posted this to the public-webapp mailing list too, but I don't think that's synced to this group, so if this is a double posting: apologies!

I've been playing with web components and custom elements for a bit, blogging about my understanding of it at http://pomax.nihongoresources.com/index.php?entry=1364168314 and writing a demo for the Mozilla "webmaker" dev group to see what we can do with them, which is hosted at http://pomax.github.com/WebComponentDemo/

This demo has a stack of custom elements that all "tack onto" a media element on the page, if there is one, with two pages, one with a media element, the other with an image instead, but identical code outside of that difference, using the components defined in http://pomax.github.com/WebComponentDemo/webmaker-components.html

One thing we're wondering about how to play with is self-documenting components. Was there already work done on this, or has anyone else already played with that idea? Right now we've hardcoded the documentation as plain HTML, trying to come up with a nice way of autogenerating it by having some JS that checks whether the components were loaded as "the document itself" and if so, generate the documentation from the <element> definitions, but finding a clean way to include a general description as well as attribute documentation is tricky. If anyone has good ides for doing this, I'd be delighted to hear from you!

Also, if there's anything on those pages that we did "wrong", or that can be done better, I'd also love to hear from you. These things feel like game-changers, and making things that use components and custom elements is proving extremely fun =)

- Mike "Pomax" Kamermans

[Eric Bidelman]

Hey Mike,

I saw your post on public-webapps and am glad you cross posted here. This feels like a better group for the topic.

A self documenting web component excites me. The idea never dawned on me, but

it makes a ton of sense. If we can define a suggested structure, it's going to be easy for people to learn how to use a component just by visiting a hosted URL. It also (somewhat) solves my concern with versioning as the component's API documentation comes along with it.

On the flip side, you're pulling down a bunch of extra text/markup.

At any rate, I think this is worth experimenting with and have started writing up some thoughts.

I'll share them in the next couple of days.

--
You received this message because you are subscribed to the Google Groups "Toolkitchen" group.
To unsubscribe from this group and stop receiving emails from it, send an email to toolkitchen...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Steve Orvell]

I also agree, that's really nifty and not something we had considered. As long as the doc part is stripped for production loading, this seems ideal.

[Dominic Cooney]

We think self-documenting components are a great idea. I think that Dimitri explicitly had documentation in mind when he suggested component resources be HTML documents. 

It would be great if the early documentation of custom elements set a high standard of consistency and quality. I think documentation of a given element should encompass markup (not just attributes), script API and styling.

If you can get a hold of an <element> e you can probably tell whether it is loaded as an external resource by doing something like

document === e.ownerDocument ? 'document itself' : 'external resource'

per the Spec Soon To Be Formerly Known As The Web Components Spec, when components are loaded as external resources, they get their own document <https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/components/index.html#loading-components>.

HTH, look forward to more discussions about how to document components!

Dominic

Email SLA • Google+

[Mike Kamermans]

Getting documentation right is going to be tricky. On the one hand you
don't want to be too verbose, but on the other there really doesn't
appear a good way to do self-documentation in a way that doesn't
involve either hand-coding it, or using some clever JavaScript that
scans the file if window.location ends in the components filename, and
autogenerating the documentation based on (necessarily at the moment)
non-standard annotation. That said, and taking Dominic's observations
into account, the documentation needs we've run into, so far, are the
following:

globally:
- versioning information
- general documentation to describe the collection as a whole
- notes on which additional imports we make (i.e. script
dependencies and subcomponent dependencies)

for each element:
- name
- description of what it's for
- JS API, if any
- information on the local CSS (because people will want to override
it at some point)
for each attribute:
- name
- description of what it's for
- the effect of assigning or clearing it, if any (think setting
"src" on an image/audio/video element. Things happen)

The subcomponents are an interesting thing too; the spec doesn't state
how relative subcomponent and script URIs are resolved, and right now
the polyfills seem to resolve them relative to the master-owner, so if
I have an index.html with a component uri
http://cdn.ourstuff.com/API/components.html, and that has a
subcomponent with URI additionals.html, one would have to hardcode the
location for the subcomponent, since it doesn't resolve relative to
the "owner" but to the "super owner". (The same goes for scripts. If
one wants to move global script for a components.html into its own
file to make things clean and possible easier to compile, relative
links are problematic to say the least)

- Mike

[Domenic Denicola]

I'm pretty new to this scene and don't know much about the requirements or desires, and honestly not sure I've followed everything said in the thread so far. So take this idea with a grain of salt. But...

Isn't this exactly the type of thing content negotiation is meant to solve?

E.g., if requested as text/html, the server could respond with a verbose self-documenting definition that sucks up lots of bandwidth. But if requested as text/html+webcomponent (or whatever; text/html+componentonly?) it could respond with the minimum amount of data necessary, and no docs.

Then, of course, browsers would request web components with the Accept header preferring text/html+webcomponent, and get the benefits of less overhead. But when the user views source and clicks the link to the component, they end up on a nice self-documenting page.

________________________________________
From: toolk...@googlegroups.com [toolk...@googlegroups.com] on behalf of Mike Kamermans [nih...@gmail.com]
Sent: Thursday, March 28, 2013 11:26
To: toolkitchen
Subject: Re: Playing with web components and custom elements

- Mike

--

[Eric Bidelman]

I like the idea and it simplifies the component include. But what if users don't have control over their server or your app is a server-less thick client?

[Angelina Fabbro]

It looks like x-tags are auto-generating documentation for their tag/component registry:

https://github.com/x-tag/registry

Compare xtag.json with the content for each component in the registry:

http://registry.x-tags.org/

I think this simple method of a json config is pretty decent. I'm not sure how elegant it ends up being if you have complicated documentation for your component, but I'm hoping and assuming that most components will be small-ish.

Thoughts?

- Angelina

[Mike Kamermans]

This isn't actually self-documentation, but a package description that isn't guaranteed to be in any way in synch with the element's real definition. Any self-documenting of custom elements is going to have to be somehow inherent to the element's definition, not any package information "added" manually.

- Mikax

--
You received this message because you are subscribed to a topic in the Google Groups "Toolkitchen" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/toolkitchen/T8p9rnvFZCk/unsubscribe?hl=en.
To unsubscribe from this group and all its topics, send an email to toolkitchen...@googlegroups.com.

[Angelina Fabbro]

That distinction is true (i.e. package description vs. auto-generated docs) and that I misunderstood what was going on there, Still, this caught my attention because I like the idea of having auto-generated documentation in an easily parseable format for templating. I don't necessarily always want the auto-generated documentation to be thrown into it's own page with arbitrary tags, which is how a lot of auto-templating tends to be done. Lack of control over that sort of this is what I've found infuriating with auto-generated docs in the past.

I like what TJ's doing with Dox:

https://github.com/visionmedia/dox#readme

I was thinking at this from the angle of running a script and producing a set of static docs. However, I just read Dominic's suggestion of:

text/html+webcomponent

... and the idea of viewing the source, clicking the link, and being taken to a nicely documented component is a great idea and probably a much better direction.

- Angelina

[Domenic Denicola]

At first I thought this killed the idea. But upon mulling it over about it, I’d say that’s not a real concern:

·         If users don’t have control over the server, they’re screwed when it comes to optimizing anyway. They’re not going to be able to gzip, or set cache headers, for example. An extra KB or so of docs won’t hurt them.

·         In practice, most users who are hosting on shared web site services are able to at least edit .htaccess files, which from my understanding do let you specify certain files as certain MIME types, and probably do full content negotiation through rewrite rules (?).

·         In the thick-client scenario, file size doesn’t matter. That is, when building Windows 8 apps, I’m not going to minify my JavaScript; similarly, I’m not going to remove documentation from my web components.

[Dominic Cooney]

For me, I like that I can develop on a local filesystem, or at worst fire up a dumb local webserver (python -m SimpleHTTPServer 8000). I think having to tweak the MIME type of files used as components will require something more elaborate. Making me do something more elaborate will give me the blues. 

Dominic

Email SLA • Google+

[Domenic Denicola]

Sure, but that should still work---the browser will just download the entire self-documenting web component file.

 

In case it wasn’t clear, I wasn’t proposing

 

Accept: text/html+webcomponent

 

but instead

 

Accept: text/html+webcomponent, text/html; q=0.9, */*; q=0.8

[Dominic Cooney]

I understand. I somehow missed that you were suggesting Accept: and not Content-Type:.

Not sure how I feel about this proposal. My fear is that the further you get from the garden-variety web, the more likely some busted old HTTP proxy or virus scanner will ruin your day. But I have no data to back that up.

I suppose servers could do this in an ad-hoc way with the querystring (e.g. ?doc).

Dominic

--

Email SLA • Google+