Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Quest - Improvements to teaching Ember Data #20

Open
jenweber opened this issue Apr 22, 2018 · 13 comments

Comments

Projects
None yet
7 participants
@jenweber
Copy link
Contributor

commented Apr 22, 2018

Let's teach Ember Data better! Developers face three main hurdles when learning Ember Data, and by completing the issues linked below, we can improve the learning story. The challenges at a high level are:

  1. Not knowing where the line is between Ember and Ember Data
  2. Hard to know which API methods to use when
  3. Fundamental misunderstanding of the point of serializers, as a way to turn any response into JSON:API

Here's how we'll overcome these. PRs should branch from master and target master for a merge.

  • Find the places in the Guides where Ember Data functions are referenced, outside of the "Ember Data" section of the guides. Add an explicit note that the example uses Ember Data, and maybe a link to that part of the Guides or API docs.
  • Show sample req and res objects/spec for different adapters/serializers
  • Replace "customizing" language for serializers. I think we could simplify the mental model for everyone by teaching more about what a serializer is and how to write one instead of focusing on “customizing”
  • Focus serializer explanations around most useful API methods. There are only 3 necessary methods, only 2 of which are “happy path”. Those methods are normalizeResponse serialize and pushPayload, and each can be described in an ideal world as “a pure function that converts from non-json-api to json-api or vice-versa”. The 2 happy path methods are normalizeResponse and serialize
  • make sure distinction between model and record is clear. record for instances and ModelClass for the class
  • better intro explaining what adapters are
  • overall, gradually align on json-api terminology within ember-data, e.g. instead of saying record say resource and resource-identifier
  • provide a proper intro to Ember Data in the Guides
  • Split out Ember Data into its own Guide (way down the road, after we do the same for Tutorials)

Helpful terminology definitions:

  • store: a cache for records
  • Model: a schema class used when instantiating a record
  • Adapter: a request-manager: it takes instructions on what to find and manages the process of making an API request and returning the response. Essentially an abstraction over fetch.
  • Serializer: a formatter used to convert your API responses into json-api format if they are not already (caveat, needs to be a subset of json-api (camelCase member names and dasherized, singularized types)
  • finders: a utility method for chaining together request => format data => update cache
  • records (e.g. instances of Models) - think of them as “remote state”. A record is some data that lives outside of the lifecycle of the application, e.g. on your server
@jenweber

This comment has been minimized.

Copy link
Contributor Author

commented Apr 22, 2018

cc @runspired - please edit however you want ^^^

@lifeart

This comment has been minimized.

Copy link

commented Apr 23, 2018

In serializers: _normalizeDocumentHelper, extractAttributes, extractRelationships - most used methods for me, it will be nice to cover it for newbies

@ppcano

This comment has been minimized.

Copy link
Contributor

commented Oct 28, 2018

Related discuss thread

@zachgarwood

This comment has been minimized.

Copy link
Contributor

commented Oct 29, 2018

I think one incremental change that could be made is to introduce using fetch (or some third-party library) to retrieve data in the Super Rentals tutorial. Currently, in part 5 of the tutorial, Installing Addons, we have the reader install Mirage, add the dummy data to the mirage config, then tell reader that they won't actually use this data until part 8, Using Ember Data. In the meantime, we have the reader using hard-coded data that we had them add when we were explaining the model() hook in part 4, The Model Hook.

I propose that immediately after we have the reader install Mirage (in part 5), we have them replace the hard-coded dummy data with a fetch call to retrieve data from Mirage in part 6, Building a Simple Component. I believe this would help demonstrate the path to eventually incorporating Ember Data as an app grows.

@jenweber, if you think this would be an appropriate change, I'd be happy to submit a PR.

@sukima

This comment has been minimized.

Copy link

commented Nov 2, 2018

If I (or others) were to work on this would it be best to use ember-ajax of fetch()?

I'm inclined to say ember-ajax as it is included in ember apps by default, has better support for errors, and has good patterns for customization (which is a common need in apps). On the flip side fetch is a known JS standard and many people coming to a framework to evaluate its worthy-ness tend to dislike more abstractions over a standard-lib even if said lib lacks features.

Hmm. maybe a progression from fetch then ember-ajax ending with ember-data?

Thoughts?

@zachgarwood

This comment has been minimized.

Copy link
Contributor

commented Nov 2, 2018

@sukima I like the suggestion of using ember-ajax, but I think going from fetch -> ember-ajax -> ember-data may be too gradual of a progression. I think it might be best to use ember-ajax while stating something like "You may choose to use fetch(), but ember-ajax is included in a standard project and gives us additional functionality, so we're going to stick with that." We might even be able to point out a place or two where we use a feature of ember-ajax that does not appear in fetch, to help sell it.

@jenweber

This comment has been minimized.

Copy link
Contributor Author

commented Nov 3, 2018

I love the idea of using fetch until Ember Data is introduced! This will help users understand the model hook and Ember Data’s role better.

I think Ember-ajax adds mental overhead, whereas fetch should be familiar to devs in other frameworks. I believe it’s a better learning experience to show fetch.

We need to do some work to present fetch as a normal JavaScript method, for people who are new to web development. It should also have a note that many devs use Ember Data to make api requests, which is covered later in the tutorial.

cc @todd.jordan and @pzuraq, any thoughts?

@jenweber

This comment has been minimized.

Copy link
Contributor Author

commented Nov 3, 2018

Sorry for the delay, but I think this should be a topic at this week’s learning team meeting to confirm, before you do any work. @zachgarwood

@toddjordan

This comment has been minimized.

Copy link
Contributor

commented Nov 3, 2018

Hi! Love seeing energy around the tutorial! There's an issue around use of mirage here where we replace mirage with a publicly hosted tutorial api #229 . (mirage would still be utilized for testing)

IF we were to introduce using standard http apis before ember data in the tutorial, it would probably need to go as follows:

  1. we should use ember-ajax instead of fetch. Fetch doesn't have ie 11 support natively (among other browser related quirks), and we don't want to introduce another addon to the mix. (ember-ajax comes out of the box)
  2. network calls are not introduced until the ember data section, so we would need to replace that section with the ajax version of it and possibly add a new section to the tutorial possibly near the end right before deploying.
  3. mirage is only mentioned in the addons section because it is an addon we will use later. It doesn't necessarily have to be there and can be pushed back to the the first use of a network connection. (its install/setup could be pushed into the test part of the section near the end, allowing users to skip if they please, once we move towards using the public api)

I'd also like to mention we are planning a coordinated effort in December to enhance several parts of the Learning infrastructure and for sure tutorial will be a part. If folks want to get started earlier we have a few guides-source issues here marked with the tutorial label. Get in touch with me or comment in a relevant issue if you are interested.

https://github.com/ember-learn/guides-source/issues?q=is%3Aissue+is%3Aopen+label%3Atutorial

Like Jen said we'll also be discussing Thursday, so folks are welcome to join then too.

@zachgarwood

This comment has been minimized.

Copy link
Contributor

commented Nov 12, 2018

@jenweber & @toddjordan any updates?

@runspired

This comment has been minimized.

Copy link

commented Nov 15, 2018

you may want to watch this RFC emberjs/rfcs#395

@runspired

This comment has been minimized.

Copy link

commented Nov 15, 2018

And you may want to consider the effects of defaultStore on the learning story, and the need for us to deprecate it to clean things up: emberjs/rfcs#377

@jenweber jenweber changed the title Epic - improving Ember Data sections Quest - Teaching Ember Data better Mar 29, 2019

@jenweber jenweber changed the title Quest - Teaching Ember Data better Quest - Improvements to teaching Ember Data Mar 29, 2019

jenweber added a commit that referenced this issue Mar 29, 2019

@jenweber

This comment has been minimized.

Copy link
Contributor Author

commented Mar 29, 2019

I opened a PR for #708 that introduces the use of ember-ajax. Once that goes through, we should examine all the other places in the Guides that Ember Data is used, and see if they could benefit from some ember-ajax examples.

We also plan to do another tutorial, in addition to Super Rentals, that does not use Ember Data. In a way, then, Super Rentals can kinda serve as a better "Ember Data" tutorial, since people will not be learning Ember basics and Ember Data basics at the same time, if they follow the tutorials in order.

This new tutorial project was started a long time ago but never finished. I'm going to bring it up at some learning team meetings soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.