Polymer 2.0 API Upgrade CheatSheet

[kevinpschaaf]

From @pkaske on May 20, 2017 18:58

I started a cheat sheet for reference with before and after examples when upgrading elements to the Polymer 2.0 api. I found this easier than searching the official docs all the time.

Maybe this is useful for somebody else, so I though I open an issue here.
(feel free to close if this isn't the right place)

The doc is by no means complete. In fact I just copy and pasted the last 5 minutes from the official doc to get this started. PRs with "cheats" you would like to have for easy access very welcome.

The cheat sheet is only meant for upgrading to class based elements, right now. Not hybrid.

https://github.com/pkaske/polymer2.0-upgrade-cheatsheet

Copied from original issue: Polymer/polymer#4615

[kevinpschaaf]

@arthurevans Going to move this over to the docs tracker... maybe you can do a once-over of the content in his cheat-sheet and ensure the upgrade guide covers it?

[ghost]

@arthurevans @kevinpschaaf @notwaldorf

There are a few items in here that aren't covered. Hoping you can help, or point to someone who can?

Before: this.getComputedStyleValue() After: ???

Before: this.getContentChildren After: ???

Before: this.getEffectiveChildren After: ???

[notwaldorf]

Just dropping this here since it may have been missed: i wrote a cheatsheet: https://meowni.ca/posts/polymer-2-cheatsheet/

[ghost]

Thanks @notwaldorf, I had seen that but couldn't locate those three items that @pkaske marked with question marks.

[kevinpschaaf]

@katejeffreys

Before:

this.getComputedStyleValue()

After: For now, need to use custom ShadyCSS API when the polyfill is loaded:

if (window.ShadyCSS) {
  style = ShadyCSS.getComputedStyleValue(el, '--something');
} else {
  style = getComputedStyle(el).getPropertyValue('--something');
}

An issue exists at https://github.com/webcomponents/shadycss/issues/83 to improve the fidelity of the polyfill by patching the native window.getComputedStyle to do the good thing without a conditional.

---

Before:

this.getContentChildren

After: Just write the platform code that will do this: find the slot, get the assignedNodes, and filter down to just the elements (ignore comments & text nodes):

this.shadowRoot
  .querySelector('slot')
  .assignedNodes({flatten:true})
  .filter(n.nodeType === Node.ELEMENT_NODE)

---

Before:

this.getEffectiveChildren

After: Use Polymer.FlattenedNodesObserver's getFlattenedNodes helper method, and filter them down to just the elements (ignore comments & text nodes):

<link rel="import" href="polymer/lib/utils/flattened-nodes-observer.html">
...
let effectiveChildren = Polymer.FlattenedNodesObserver.getFlattenedNodes(this)
  .filter(n.nodeType === Node.ELEMENT_NODE)

[ghost]

\o/ Thanks!

[ghost]

@pkaske I created this placeholder file in a new branch:

https://github.com/Polymer/docs/blob/upgrade-cheat/app/2.0/docs/upgrade-cheat.md

If you wanted to add your content to it, GitHub will ask you to sign a CLA and we can include it in the docs. Then I can edit to add the info from Kevin above. If not, no worries :)

[trading-peter]

Yeah of course. I'll create a pr soon.

[jsilvermist]

@kevinpschaaf What's the benefit of the longer:

getComputedStyle(el).getPropertyValue('--something');

Versus the shorter:

getComputedStyle(el)['--something'];

[trading-peter]

@katejeffreys see #2233

[kevinpschaaf]

@jsilvermist The CSSStyleDeclaration returned from getCopmutedStyle does not include custom properties that can be dereferenced by name: https://drafts.csswg.org/css-variables/#apis. Custom properties must be retrieved via getPropertyValue.

http://jsbin.com/cukeva/edit?html,console

[ghost]

@kevinpschaaf @arthurevans WDYT about adding this cheat sheet to the docs site?

See also: #2231

The PR for it is here: #2239

[ghost]

Upgrade cheat sheet needs cross-referencing and editing. From @arthurevans:

"...make it cover all of the items in the regular upgrade guide, and add cross-references to the official sections"

Branch is here; https://github.com/Polymer/docs/tree/upgrade-cheat

When I get time, I will look at working this up so it can be included. No open PR for now since it is not ready for review.