Todo Tutorial Feedback -- Issues, Comments, Challenges

[virkt25]

Description / Steps to reproduce / Feature proposal

As part of #729 I sat down with a user with no prior LoopBack experience (but a developer) and had him go through what is currently known as example-getting-started (pending rename to example-todo) Tutorial. I made notes during this process and gathered the following feedback from the user.

---

• Node 9 CLI issues after global install -- Test lb4 CLI on Node 10 #1296

  Had Node installed via brew and lb4 install location wasn't part of the PATH.

• Why do I need to create a class? -- [CLI] Do not prompt for Application Class name #1297

  Refers to the CLI prompting for Application Class Name. No description of what that Application class refers to.

• What is loopbackBuild? -- Description of Options -- loopbackBuild / mocha #1298

  No description in the CLI tool.

• Enable mocha -- Description of Options -- loopbackBuild / mocha #1298

  Asked if this means that it will generate the tests for the project for him.

• Looking for views … coming from react background … -- Default folder for serving static files #1468

  Essentially referring to a folder for static files

• Missed the Next Step … Make Next Step a heading instead of Navigation -- This will be addressed via new LB4 Site Tutorial Page

  The navigation found at the bottom of the Tutorial steps.

• Renamed index.ts to model.ts since all folders have index.ts in them [CLI] Generating index.ts in each models/repositories/controllers automatically #1127

• Skipped legacy juggler bridge step since he doesn’t know what that is and said “I could care less” Enhance developer experience in persistence story #1237

• Added export to index.ts first but that led to a warning in VSCode that module doesn’t exist. [CLI] Generating index.ts in each models/repositories/controllers automatically #1127

  Annoyed. Instruction should've told him to create the module first and then add it to index.ts

• Under Model section … what is Repository? Entity? Etc? To-do tutorial: Include one-liner LB4 concept definition #1444

• For Datasource section, expected config directory to exist already. Update Todo tutorial to load datasources via loopback boot #1440

  • Saw instructions for creating the config folder.
  • Questioned Why?
  • Doesn’t know what juggler is …
  • Why wasn’t the config folder created?
  • Thought the config file was good enough — not sure of the purpose of the ts file.

• Repositories folder [CLI] Generating index.ts in each models/repositories/controllers automatically #1127

  • What do I put in index.ts … also created it as repositories.ts
  • Export * from ‘pwd’ ?? …

    Can something like this work?

• Doesn’t mention to go to /swagger-ui

  For the last step, after npm start we should add visiting /swagger-ui

  • update from @dhmlau: http://loopback.io/doc/en/lb4/todo-tutorial-putting-it-together.html Try it out section shows API Explorer with the link. From my understanding, this is fixed.

• Redirect to loopback.io isn’t intuitive (link to API Explorer in Docs)

  Was confused about why the redirect took place or how clicking "API Explorer" link in the doc loaded API Explorer with his App running.

  • update from @dhmlau: it's fixed. The API Explorer link goes to localhost:3000/swagger-ui

• Missing id field in GET/todo/id (so id=undefined) resulted in a 500 but should’ve been 4XX (Bad request). Same result with any invalid id field. This should be a Bad Request. -- Incorrect response codes for invalid HTTP calls #1469

• Id shows up in all “try it out” options as 0 but it is ignored in various calls including Create -- [API Explorer] Fields shown but ignored #1470

• Can you patch the ID?

• Response for PATCH / PUT is true instead of JSON as one would expect -- [REST] Consistent response format for PATCH/PUT #1471

• Was able to delete id=2 when it doesn’t exist. Returned a success message. -- [REST] DELETE with invalid ID is successful #1472

• Feels like an architecture that scales well but a lot of new concepts -- To-do tutorial: Include one-liner LB4 concept definition #1444

• Be nice to add the tutorial to todomvc -- This is for front-end frameworks, not backend frameworks such as LoopBack

---

cc: @strongloop/lb-next-dev I think we should work on addressing some of these areas of concerns with the next release (after DP2).

[shimks]

This is some good feedback 👌

[shimks]

@virkt25 Could you update this task with an appropriate acceptance criteria? At first glance, this issue seems like it'll pan out to be a spike to see how the feedback could be addressed, but what do you think?

[dhmlau]

I agree that we need to work things out to have a set of acceptance criteria. However, I don't think there's a need for a spike, rather than fixing things up.

[virkt25]

No Spikes. I'll take an attempt at creating a Todo List (get it) for the tasks with some criteria.

[fjanon]

Adding some issues in the LB4 todo tutorial

https://loopback.io/doc/en/lb4/todo-tutorial-repository.html

1. I think the code immediately following:
   NOTE: The index.ts file is an export helper file
   should be part of the note. It's confusing here, we are looking for the todo code for index.ts that's missing.
2. the code for the index.ts is missing

In the controller page and code:
https://loopback.io/doc/en/lb4/todo-tutorial-controller.html

The return type for the method is Promise boolean:

@put('/todos/{id}')
  async replaceTodo(
    @param.path.number('id') id: number,
    @requestBody() todo: Todo,
    // Must change to Promise<void>
  ): Promise<boolean> {
    return await this.todoRepo.replaceById(id, todo);
  }

gives an error at compile and runtime times.

The correct return type for the method is Promise void :

  // from the finished example
  async replaceTodo(
    @param.path.number('id') id: number,
    @requestBody() todo: Todo,
  ): Promise<void> {
    await this.todoRepo.replaceById(id, todo);
  }

[bajtos]

@fjanon thank you for the feedback! Would you mind contributing the proposed changes yourself? See DEVELOPING.md and contrib guide to get started.

[dhmlau]

@fjanon, I believe I've fixed them via PR #1846.
For creating controller in the tutorial, we now ask our users to select the REST Controller with CRUD functions option so that most of the code are generated. Thanks.

[dhmlau]

Closing as resolved.