101 Contact Book Tutorial Quest

[pzuraq]

This issue is for tracking the progress of and items for completing the 101 Contact Book tutorial. The tutorial is meant to be a thorough guide for SPA framework beginners that ramps them up slowly, as opposed to the existing Super Rentals tutorial which is targeted at more experienced developers.

Overview

The concept for this tutorial is a barebones contact manager app, such as the Contacts app on MacOS. Aurelia has a similar application for there tutorial, which has been a source of inspiration for this tutorial.

The motivation for this tutorial is to fill a gap that our existing tutorials skip over, which is a thorough guide to building a basic SPA for someone with little-to-no experience with frontend frameworks. Some of the major issues with the existing tutorials are:

• Lack of focus on Components. Most frontend frameworks these days start with Components, and build abstractions slowly on top of those. Concepts that are there by default in Ember, such as Routes, Models, Controllers, etc. can be confusing to newcomers, and make Ember seem overly complicated by comparison.
• Data management. Frontend devs often understand the basics of $.ajax or fetch and know how to communicate with backends and APIs. Ember Data is a powerful solution that throws a whole bunch of abstractions on top of these primitives, and can be very confusing to new users. It also makes Ember Data appear to be a required part of Ember, which may deter users who are more familiar with alternative data layers such as Apollo.
• Testing. Tests are one of Ember's strengths, and we should include a full demonstration of tests in every tutorial, but the TDD style of tests in Super Rentals is very heavy handed. For beginners learning the basics, it can feel like too much at once.

Given these factors, the idea here is to make a tutorial that focusses on the basics first, and builds up to more complicated features more gradually. It is also meant to mimic the tutorials for other frameworks, so that we can leverage our similarities to these other frameworks to accelerate learning within ours.

Outline

Rather than introduce all of the Ember concepts at once, the tutorial currently starts with just one - Components. Everything in the app is built using components so learners can really focus on all the ways that they can be used, including component patterns such as container/presentational components and other concepts that are becoming common in the larger SPA framework world. The components are built to be fully functional, but with mock data (e.g. POJOs on the Component instance) instead of loading any data or communicating with the backend.

Once the basic app has been built with components, we focus on adding a basic data layer. We start by using simple fetch requests against a service (currently located here) directly in components, and then extract those requests out into a Service (this is also where we introduce Services, and explain them as the general solution to long term state in Ember).

After that's all done, we refactor the application using Routes and the Router. This demonstrates the value of the Router at the same time as introducing it when it makes sense - when an app has reached enough complexity.

Finally, we add tests. This should be a thorough demonstration of how to write tests in Ember, both overall acceptance tests and component integration tests.

Supplemental Resources

The tutorial should have a reference implementation in the form of a git repo, much like Super Rentals. The git repo should have commits for every step in the tutorial, so users can jump to a commit and see the code they should be targetting. Ideally tags should be added as well. See the Super Rentals reference app.

Quest items

• [ ] Pages

  • [x] Setup
  • [x] Setting Up
  • [x] The Application Template
  • [x] Introduction to Components
  • [x] Creating the Details Component
  • [x] Using a Container Component
  • [x] Creating the Contact List
  • [ ] Data Management
  • [ ] Loading Contacts from the Server
  • [ ] Creating and Editing Contacts
  • [ ] Adding a Service
  • [ ] Routing
  • [ ] Refactoring with Routes
  • [ ] Testing
  • [ ] Testing the App
  • [ ] Finishing Up

• [ ] Contact Book Repo [link]

  • [ ] Setup of commits on master

• [ ] Contact Book Server [link]

  • [ ] Ensure it's working
  • [ ] Transfer to ember-learn org

• [ ] Misc

  • [ ] Styles and design of the Contact Book app

[jaredgalanis]

We will revisit this topic if we start to write new tutorials. Thanks everyone for the discussion!