Epic - cheat sheet content we should/could draft

[jenweber]

As much as possible, I would like to reuse code examples from the Octane cheatsheet, and then add more for template syntax. The 🆕 indicates things that do not have an example in the old cheatsheet. Please comment on anything you think is missing, what should be removed, and which of the 🆕 things are highest priority.

Ember Data also needs a cheat sheet, but I think it should be separate.

Using components in templates

• Invoking a component
• Block components
• Nested components
• Using named args
• Using own properties

Fetching data

• 🆕 Via ember-data - very very brief example and links to docs. Someday, make it its own cheat sheet.
• 🆕 In a model hook
• 🆕 In a service (i.e. websockets, 3rd party API widgets)
• 🆕 In a component

Passing and mutating data

• Passing arguments
• Data down, actions up
• Using component args
• Tracked
• 🆕 Tracked for objects & arrays
• Default values

Interaction

• Actions
• 🆕 Click event
• 🆕 Keyboard event
• 🆕 custom event listener?
• willDestroy event teardown
• did-insert
• 🆕 Input w/associated label
• 🆕 Maybe something showing focus management?

General Template syntax & helpers

• 🆕 dynamic property access
• 🆕 iterating over an object
• 🆕 iterating over an array
• 🆕 inline ifs
• 🆕 conditional modifiers
• 🆕 usage of the (maybe now?) built-in math/equality helpers
• 🆕 use of plain-functions as helpers/modifiers
• 🆕 maybe a general "how to think about this syntax" sort of thing

Routes

• 🆕 changing routes
• 🆕 changing params
• 🆕 Reading params in a model hook
• 🆕 Accessing the model

Component class

• Creating a component and declaring a property on it
• Using the constructor

Notes from Twitter

Possible way to describe the template syntax:

Expression =
  | SubExpression
  | Value

SubExpression =
  | (Helper, ...Value[])

Value = 
  | number
  | string
  | boolean
  | undefined
  | null
  | SubExpression 

[jenweber]

@NullVoxPopuli let me know your thoughts! Also if you can add me to this repo as a member, that would be helpful. I can make a feature branch that drafts this content as plain markdown and tag you for review whenever I have something new.

[yratanov]

@jenweber Good plan!

Example of passing an attr to the component with one-way change. like @tracked internalState = this.args.externalState, which will update if @externalState is being changed, but not vice versa. The only way I see doing it is {{did-update @externalState this.changeInternalState}}.

[NullVoxPopuli]

I'm generally in favor,

Some additional thoughts:

• the octave vs classic cheatsheet has significant layout-shift on load -- I don't think it used to?
• for describing the syntax, I think I may want to make a "syntax explorer" component (as a library), so folks can interactively browser the AST (in a non-overwhelming way coughASTExplorercough)
  • We could probably also supplement a lot of conceptual things with interactive demonstrations... if folks want to work on that content, I can animate / demo interactive concepts)
    • I agree that the current representation is a bit terse, but I consider that to be the minimum information to present
• Using the constructor should come with the caveat that constructors in @glimmer/component are non-reactive (which is different from some resource implementations.. and even though resources are new, the expectation of reactivity in a constructor is not -- had that come up in discord this morning w/r/t @glimmer/component's constructor)
  • creating a component - :+1: CLI + how to do this manually + the different ways a component can be created / used would be good, too. (setComponentTemplate, etc)
  • fetching data - love this section - lots of ways to do this. Just used glimmer-apollo for the first time a couple weekends ago, resources make this super straight forward (not that we need to mention those, exactly, but that brings up a broader topic of how to deal with async things in components, which resources are good at)
  • passing and mutating data
    • tracked for objects and arrays -- I'd like to get tracked-built-ins merged into ember within this timeline, so hopefully we don't need to recommend "yet another non-default library"
    • "data down / actions up", I think we should call this "one way data flow" and mention data-down-actions-up as an aside. I had this fight with drones for the longest time when mainstream media started having conniptions over hobbyists' fun. I insisted folks call them quadcopters, but .. eventually gave up and started calling my own stuff drones as well (I'm still kinda upset about it lol). Language is living, and if we don't use words/phrases people will get confused at our "new concepts", even though they are not new.
  • interactions
  • I strongly feel we should not be promoting did-insert or any of the render modifiers -- we have better patterns for the things typically used by these, and we should be teaching folks how to think more in derived data terms. https://nullvoxpopuli.com/avoiding-lifecycle
  • focus management? -- I think this'd be good - maybe also a nod to the ember-headlessui project which is aiming to handle all the a11y stuff for common UI patterns but in a style-agnostic way, so that we can all benefit from improved accessibility
  • General Template syntax & helpers most of this exists in this cheatsheet, but I want to figure out where all the built-in stuff is atm. We shouldn't have to tell people to install truth-helpers still :-\ cc @snewcomer -- you did the VM side of this implementation yeah? eq, gt, etc?

[NullVoxPopuli]

like @tracked internalState = this.args.externalState, which will update if @externalState is being changed,

if you happen to need this now, you'd do it like:

yarn add tracked-toolbax

@localCopy('args.text') myText; // can be set, re-sets to args.text when args.text changes

see: https://github.com/pzuraq/tracked-toolbox

if you wanted to do this vanilla, you can use the same approach as you would with class instance values:

import { cached } from '@glimmer/tracking';
import { getOwner, setOwner } from '@ember/application';

// ...

@cached
get myValue() {
  let instance = new MyClass(this.args.externalState);
  setOwner(instance, getOwner(this));
  return instance;
}

then myValue only creates a new MyClass when externalState changes. Note that set/get owner not needed, but most folks like using services and stuff from their custom classes, and set/get owner enables that.

[NullVoxPopuli]

additional topics -- everything from here?: https://discuss.emberjs.com/t/collection-of-strict-mode-template-demos-of-various-concepts/19637 (as well as the provided demos on limber.glimdown.com (focus management, forms, etc etc)

• effects
• resources in general
  • loading data
  • encapsulated state (clock, loading data)
• automatic form binding without event listeners on each input
• checkboxes without event listeners

and maybe also a collection of anti-patterns so that it's clear where the ecosystem stands?

by use-case alternatives, because effects are rare to reach for (or should be (even in React))

• did-insert, did-update, will-destroy