Initial content of the EyeDropper API

[captainbrosset]

Summary

This adds some initial documentation content for the EyeDropper API.

The suggestion to add docs for this API was made in issue #9955.

Motivation

The API is implemented in Chromium-based browsers, and can therefore already be used (Chrome 95+ or Edge 95+ for example).

Metadata

• Adds a new document

Note

This is my first time creating an entirely new API documentation on MDN, so let me know if I forgot some pages or messed up some cross-linking.

Also, I'm not sure I understand how to add the spec section on all of the new pages.

Finally, there isn't any BCD data yet to go with this. I suppose this needs to be done separately in the BCD repository.

[github-actions]

Preview URLs

• https://pr9985.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/EyeDropper/EyeDropper
• https://pr9985.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/EyeDropper/open
• https://pr9985.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/EyeDropper
• https://pr9985.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/EyeDropper_API

Flaws

None! 🎉

External URLs

URL: /en-US/docs/Web/API/EyeDropper_API
Title: EyeDropper API
on GitHub

• https://web.dev/eyedropper/ (1 time) (Note! This may be a new URL 👀)
• https://www.w3.org/2021/03/media-production-workshop/talks/patrick-brosset-eyedropper-api.html (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/EyeDropper
Title: EyeDropper
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/EyeDropper/open
Title: EyeDropper.prototype.open()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/EyeDropper/EyeDropper
Title: EyeDropper()
on GitHub

No new external URLs

(this comment was updated 2021-10-29 06:34:59.657966)

[wbamberg]

Thanks @captainbrosset ! I'll take a look.

Also, I'm not sure I understand how to add the spec section on all of the new pages.

The BCD should include a spec_url property that points to, well a URL for the bit of the spec for that feature: https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#the-__compat-object.

Then the page needs to include:

• the "browser-compat" front matter property, whose value is the BCD query
• a line like {{Specifications}} where you want the spec table to appear
• a line like {{Compat}} where you want the BCD table to appear

For example:

• BCD for Request.url: https://github.com/mdn/browser-compat-data/blob/main/api/Request.json#L1296
• front matter property:

  content/files/en-us/web/api/request/url/index.md

  Line 12 in f00aff5

  browser-compat: api.Request.url

• {{Specifications}} and {{Compat}}:

  content/files/en-us/web/api/request/url/index.md

  Lines 40 to 46 in f00aff5

  	## Specifications
  	{{Specifications}}
  	## Browser compatibility
  	{{Compat}}

Finally, there isn't any BCD data yet to go with this. I suppose this needs to be done separately in the BCD repository.

Yes.

[captainbrosset]

Thanks Will. Because the BCD data points to MDN (with the mdn_url fields), does that mean that the MDN content change should land first, without compat sections, and the BCD change should land after, followed by a new MDN content change to add the missing compat sections?

[captainbrosset]

For information, the BCD pull request I opened the other day got merged, which is great. But if I'm not mistaken it takes a while for this data to be available to MDN.

[wbamberg]

Thanks for this @captainbrosset !

[wbamberg]

For information, the BCD pull request I opened the other day got merged, which is great. But if I'm not mistaken it takes a while for this data to be available to MDN.

Yes, it might take up to a week or even a little more (BCD is released weekly, and then a new MDN deployment has to be made).

[captainbrosset]

Thank you Will for the thorough review.
I think I addressed all of your points.

2 things are remaining:

• I'm unsure whether I need to add the compat tables (and spec links) to the constructor and open method pages too.
• I've added them on the main EyeDropper interface page, but I think we still need to wait a bit more as the site is giving me an error that the BCD entry couldn't be found.

[wbamberg]

Thank you Will for the thorough review. I think I addressed all of your points.

2 things are remaining:

• I'm unsure whether I need to add the compat tables (and spec links) to the constructor and open method pages too.

Yes, these should be added. In BCD you should have something like:

api.EyeDropper             <- interface                
api.EyeDropper.EyeDropper  <- constructor
api.EyeDropper.open        <- open method

• I've added them on the main EyeDropper interface page, but I think we still need to wait a bit more as the site is giving me an error that the BCD entry couldn't be found.

I'm not quite familiar with the exact details of how BCD changes make it into mdn/content, but this addition to BCD was in BCD release 4.0.8, which was made a few days ago: mdn/browser-compat-data#13122

...and I just tried referring to the EyeDropper data from inside an MDN from the head revision of mdn/content, and it worked:

...so I reckon it will be OK.

[captainbrosset]

Ah, thanks for checking! Silly me, I had forgotten to run yarn install locally to update my local deps. It works now.

[wbamberg]

👍 looks great, that you @captainbrosset !