Skip to content
This repository has been archived by the owner. It is now read-only.

Ember Tutorial #1374

Closed
toddjordan opened this issue Apr 15, 2016 · 17 comments

Comments

Projects
None yet
3 participants
@toddjordan
Copy link
Contributor

commented Apr 15, 2016

This is a continuation of what started in issue #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.

  • Creating a new app
  • Routes and Templates
  • Using Addons (CSS addon and mirage)
  • Writing an Acceptance Test
  • The Model Hook
  • A Simple Component
  • Handlebars Helper
  • A Complex Component
  • Service
  • Nested Routes
  • Integrate testing into existing tutorials
  • Creating Forms
  • 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 #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

This comment has been minimized.

Copy link
Contributor Author

commented Apr 18, 2016

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.

image

@toddjordan

This comment has been minimized.

Copy link
Contributor Author

commented Apr 21, 2016

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

This comment has been minimized.

Copy link
Contributor Author

commented May 5, 2016

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

homu added a commit that referenced this issue May 11, 2016

Auto merge of #1408 - toddjordan:revamp-autocomplete, r=locks
revamp autocomplete tutorial to be a filter

Part of #1374
@toddjordan

This comment has been minimized.

Copy link
Contributor Author

commented May 13, 2016

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
  • starting on acceptance test section next week.
@sbatson5

This comment has been minimized.

Copy link
Contributor

commented May 13, 2016

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

This comment has been minimized.

Copy link
Member

commented May 13, 2016

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

This comment has been minimized.

Copy link
Contributor

commented May 15, 2016

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:
ember-learn/super-rentals#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?

@sbatson5 sbatson5 referenced this issue May 15, 2016

Closed

Add subroutes #24

@toddjordan

This comment has been minimized.

Copy link
Contributor Author

commented May 16, 2016

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.

homu added a commit that referenced this issue May 20, 2016

Auto merge of #1424 - toddjordan:addons-section, r=acorncom
add addons section to tutorial

Part of issue #1374

Here's the start to the addons section.  Moved in mirage, and added a new section on our custom style addon.
@sbatson5

This comment has been minimized.

Copy link
Contributor

commented May 21, 2016

@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

This comment has been minimized.

Copy link
Contributor Author

commented May 23, 2016

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

@toddjordan

This comment has been minimized.

Copy link
Contributor Author

commented May 23, 2016

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

This comment has been minimized.

Copy link
Member

commented Jun 11, 2016

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

This comment has been minimized.

Copy link
Contributor Author

commented Jun 14, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Jun 15, 2016

Just need to address this styling nitpick I have and we should be good on sub-routes:
ember-learn/super-rentals#24 (comment)

The tutorial should be mostly finished if people want to take a first pass-through:
#1443

@toddjordan

This comment has been minimized.

Copy link
Contributor Author

commented Sep 12, 2016

9/12 Update

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

This comment has been minimized.

Copy link
Member

commented Mar 25, 2017

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

@toddjordan

This comment has been minimized.

Copy link
Contributor Author

commented May 18, 2017

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

@toddjordan toddjordan closed this May 18, 2017

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