Ember Tutorial

[toddjordan]

This is a continuation of what started in issue https://github.com/emberjs/guides/issues/445

Goal: to create guided tutorial, geared towards people new to Ember. This will be some people's first experience with the techology, so we want to make it show off the basics of creating an application from scratch. At the end of the tutorial the developer should have an understanding of the basic concepts of ember and ember-cli and be able to create and deploy a basic ember application from scratch.

The tutorial will lead the user through the process of creating a vacation rental app called "Super Rentals". MVP of the app will be to allow perspective renters to browse available properties.

• [x] Creating a new app
• [x] Routes and Templates
• [x] Using Addons (CSS addon and mirage)
• [x] Writing an Acceptance Test
• [x] The Model Hook
• [x] A Simple Component
• [x] Handlebars Helper
• [x] A Complex Component
• [x] Service
• [x] Nested Routes
• [x] Integrate testing into existing tutorials
• [ ] Creating Forms
• [x] Links to the super-rentals repo
• [ ] Make super-rentals accessible, add a section?

  Standards for Each Tutorial Page

• Clear language adhering to guides contributing standards: https://github.com/emberjs/guides/blob/master/CONTRIBUTING.md
• Each Tutorial Page should be written in a step-by-step format, guiding the user through how they would build it themselves
• Examples tailored to someone new to ember, showing off basic concepts while not diving into complex approaches
• Testing should be incorporated into each functionality described.
• The super-rentals repo should be updated with working code (and tests): https://github.com/emberjs/super-rentals

  Using addons

Our addon examples will use Mirage and a custom CSS addon we've written to decorate our website. This section should occur early in the tutorial so as pages are create they are instantly styled. Also we want to employ Mirage as our datasource.

An alternative is creating an addon for adding styles into the addon (suggested by tom dale) This would show how to install the addon, plus give the app a nice look and feel without having to include css in the tutorials.

Writing an acceptance test

As a good basic intro to acceptance testing, we want to show how we can write a test to exercise the basic initial load of the page and test one of the routes. We'll do this early, after we've installed mirage, but before creating most of the page content.

Complex Component

the autocomplete section already exists, but it needs to be improved. Right now it does an autocomplete dropdown of the properties that are already right below it. Also the dropdown is unstyled and looks pretty bad. I'd like to tweak the component to just be a filter of the list below, so no "search" button and no dropdown.

Service

There's a current PR out there https://github.com/emberjs/guides/pull/1289 , but in hindsight I think its a bit complicated for a first time ember app. I'm going to simplify this into a basic map display of the location

Nested Routes

Right now we just do index route and and the about route. I'd like to add a sub-route for rental details

Integrate testing into existing tutorials

As test is a first class citizen in Ember, we need to incorporate testing into each tutorial page. That means test is a must for any new section we add, and we also need to go back to sections we've already done and add it as well. We should make use of Unit, Integration, and Acceptance tests to give developers a good idea of what each does and when to use them.

Links to super-rentals

The completed tutorial lives in its own repo, and we should link back to that repo so developers can download and try for themselves, or use as a reference.

[toddjordan]

Slack discussion on the addon piece. Current thinking is we will do the css addon as the installing an addon example, and put it early on in the tutorial. That way, as a developer builds the app things will be styled as you go.

[toddjordan]

4/21 Update: @kidgodzilla is working on developing a css addon for the tutorial, and the addons section. @toddjordan is working on the services section and has a simplified example he's PR'ing to the super rentals repo for feedback: https://github.com/emberjs/super-rentals/pull/15/files . Targeting Monday for the services example to be merged.

[toddjordan]

5/5 Update:

• @toddjordan taking over finishing addon section
• open PRS for complex component revamp and services section
• started on nested routes. Will focus on getting addons done first
• added a task for acceptance testing

[toddjordan]

5/13 update

• service and complex component sections merged!
• addon PRs out for review. Need to make some minor updates to the code of existing pages to update markup. Plan on doing that by end of weekend
  • super rentals pr: https://github.com/emberjs/super-rentals/pull/21
  • guides pr: #1424
• starting on acceptance test section next week.

[sbatson5]

As someone who spent the last year learning Ember, I'd love to help contribute. I'd be willing to take a couple stabs at the nested-routes tutorial. I actually did a screencast of a similar scenario: https://www.youtube.com/watch?v=ljLxZw-XStw

Was thinking of a details route that takes the id as a param to pull up a specific listing. Then a search route to find listings of a certain type.

An editing route may be more complicated since my assumption would be to handle saving the records, which may be out of the scope of a beginning tutorial.

For my own clarification: are contributors supposed to open a PR against super-rentals repo with all the changes?

[acorncom]

Re: a PR against super-rentals, we’ve been trying to keep things in sync, but having the PR to guides is probably more important. Happy to have you work on the tutorial if you’d like. Fair warning: we’re quite hard on those tutorials (text, code, etc) because they’re so central. Todd Jordan has been getting a ton of feedback on his PRs ;-) So we’d love to get the help, but look out if you send in a PR :-D

On May 13, 2016, at 3:17 PM, Scott Batson notifications@github.com wrote:

As someone who spent the last year learning Ember, I'd love to help contribute. I'd be willing to take a couple stabs at the nested-routes tutorial. I actually did a screencast of a similar scenario: https://www.youtube.com/watch?v=ljLxZw-XStw

Was thinking of a details route that takes the id as a param to pull up a specific listing. Then a search route to find listings of a certain type.

An editing route may be more complicated since my assumption would be to handle saving the records, which may be out of the scope of a beginning tutorial.

For my own clarification: are contributors supposed to open a PR against super-rentals repo with all the changes?

— You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub

[sbatson5]

Thanks for the quick response @acorncom. I thought I would start with the PR against super-rentals just to make sure I'm on the right path. Here is a quick stab at subroutes: https://github.com/emberjs/super-rentals/pull/24

I changed my mind on an edit sub-route. I thought we would add an admin route where the user could see all the listings, click one and edit it. Rather than adding a save action (since handling post/patch requests seems out of the scope of this tutorial), we would just have a "go back to admin page" link-to which will allow them to see their changes populate since we are transitioning.

Thoughts?

[toddjordan]

Hi @sbatson5 , Thanks for your willingness to help. We would love it! Here are some of my thoughts from the subroute tutorial:

• Since its purpose is a beginner's tutorial, I don't think we need to add a ton of functionality. Just enough to introduce developers to the concept
• I think we should add a rentals route that will show the homescreen, so that when the user goes to index, or when they go to /rentals we get the rental list filter.
• Then our subroute could be rentals/:name or rentals/:id. I think name is interesting, because you could use dasherize or camelize from Ember.String
• We are incorporating tests now into each of the tutorial sections, so you'll want to incorporate unit testing into your section.

[sbatson5]

@toddjordan Was going to try a first draft this weekend. If you have time, would you mind looking over the PR here to see if I am on the right track as to what you envisioned: https://github.com/emberjs/super-rentals/pull/24/files.

Not sure I follow what you mean by using Ember.String.dasherize in the params for a subroute. I assume I would have to add dasherize to the ember-cli-mirage config as well, which seems off to me (as an API typically isn't that flexible). I feel like I may be missing something, however.

I added a rentals route with an index and show subroute. The rentals.hbs includes an additional h2 and a footer. I thought this would be a good example of how elements on the parent route are always present and the sub-routes are rendered in the outlet

The index child route mostly matches the home page. I was thinking of opting out of the filter (it seems out of the scope of this tutorial) and instead adding a link to each one that will redirect to the show subroute:

  {{#each model as |rentalUnit|}}
    {{rental-listing rental=rentalUnit}}
    {{link-to "Select Rental" "rentals.show" rentalUnit.title}}
  {{/each}}

In the router, we update the show subroute so that we can hit just /rentals/:title which I feel is a pretty important concept for subroutes (i.e. you can pass params and modify the path).

  this.route('rentals', function() {
    this.route('show', { path: '/:title' });
  });

Then, in the show subroute we still use the rental-listing component. Do you think something additional should be added? Like the ability to edit the listings? I also have a setupController hook in the show route so that we can access it as rental and not model.

In terms of testing, I wrote a unit test for the show route since I have the setupController call. What additional testing would you need? I typically rely on acceptance tests and pretender for routes/subroutes. Not sure about writing a unit test for a simple model hook.

Thanks in advance!

[toddjordan]

Hi @sbatson5 thanks! I commented in the PR. Lets discuss over there.

[toddjordan]

5/23 Update

• Merged installing addons section 💥
• Work in progress with the acceptance testing section
• Started work on an accessibility section for Global Accessibility Awareness Day (GAAD)
• @sbatson5 is working on the beginnings of a subroutes section, while @kidgodzilla is providing markup/style for a listing details page to complement the subroute functionality.

[acorncom]

Looks like we need to get the nested routes section into the tutorial and super rentals whipped into better shape and then we'll be done here. Nice! 🎉

[toddjordan]

6/14 Update

• Merged Acceptance testing section ✨
• Accepance testing, installing addons, and services deployed along with Ember 2.6 🎉
• @sbatson5 currently working on a subroutes section for the tutorial

[sbatson5]

Just need to address this styling nitpick I have and we should be good on sub-routes: https://github.com/emberjs/super-rentals/pull/24#discussion_r67165383

The tutorial should be mostly finished if people want to take a first pass-through: https://github.com/emberjs/guides/pull/1443

[toddjordan]

9/12 Update

• Nested routes section merged 💥
• Added a new todo for forms

[acorncom]

@toddjordan Looks like we could close this issue and migrate the few todos above out into separate issues. Thoughts?

[toddjordan]

tutorial work is not represented in seperate issues. Closing...