Forget todos and align all examples to building a store

[cloudwheels]

Description / Steps to reproduce / Feature proposal

Current starter examples are based around the concept of todos and their relationships in todoLists. No doubt chosen for the relative simplicity of the concept.

From my understanding of the roadmap and current activity, the aim is to primarily demonstrate the product's production-ready capabilities through a reference implementation of an e-commerce store api backend shopping sample?

IMHO it would make more sense to start the examples with say Products and Product Variations (Orders, OrderProducts etc) to align to this and progress through one project until I've build my store, Angular Heroes style.

Then when I move on to the next step I'm authorising adding Products to an Order etc., not adding "buying milk" to my OAuth2 authenticated cloud-distributed todo list of my chosen colour. The.Real.World. LargeRedTShirt-SmallBlueTShirt. :) . This can be achieved quickly just by renaming Todo Product Variation and TodoList Product or whatever: I also think is actually is a genuine one-to-many relationship for exploring related models, whereas I would probably implement todos and lists as many-to-many from the start to cover use cases of sharing items between lists.

Thanks for listening.

[bajtos]

@cloudwheels thank you for the proposal. IIRC, we created todo-list because it was the simplest way how to get a working example for a has-many relation.

I like your proposal to use a somewhat more realistic scenario.

The tricky part is how to keep the example simple, so that people reading the code can quickly discover the relevant parts & understand what's just a boilerplate, and to keep the maintenance costs low.

So perhaps we should rename examples/todo-list to examples/has-many, to make it clear that this particular example is demonstrating has-many relation, and rework the domain model to show "Order has many OrderItem instances" relation.

@strongloop/loopback-maintainers thoughts?

@cloudwheels once we reach an agreement on the direction, would you like to contribute these changes yourself please?

[cloudwheels]

@bajtos all your hard work very much appreciated and I will do my best to find some hours!

Looking at the current structure of docs:

• Hello world only appears on the homepage / separate getting started section. I then get taken onto todos where I start a new project, not build on my hello world, I'm not sure sure this add anything vs the first tutorial part having "Do have know what a terminal is and have node installed (if not you're probably very lost/follow these links and come back when you're done): Now install our CLI" type of 'pre-requisite documentation'.
• Todos and todoList are really one example based as you say around the concept of one-to-many relations. It's nice and simple but I can't see where you go to extend it to other relations, in addition to being less 'real world' that a store.
• Some thought needed about the separate "how-tos" section (isn't "how to" synonymous with "example"?) they are downloadable with lb4 example and make use of Todos in most cases where a snippet is needed. I have trouble putting my finger on the distinction, other than these are perhaps more atomic operations which are given a bit of context when included as steps in a tutorial.
• The only other 'example' in 'examples' section is for the concept of a non rest server, not a "SOAP Todo server", which seems more aligned with the 'how tos section'
• The "concepts" section, which are essentially package scoped docs demonstrating their features exports, makes sense ( aligned to a more design first approach than sample building). However it would be more consistent if the snippets in this and the how-tos section were at least related to the same store 'mono sample' by virtue of using the same entities.

It could be nice to move on rapidly from the getting started page or even replace hello world / ping by jumping straight in with a simple user/ customer model, controller, repository and memory connector (the current todo) so I start POSTing my name & getting get a back a slightly more exciting "hello cloudwheels!"

With the generators that could be a working example running locally in a few minutes (or ideally in the cloud after another 30 seconds setting up some free tier Bluemix credentials with any of my favourite email addesses :)

[One problem here is that this 'proper' auth is probably something that gets implemented OOTB before too long and becomes 'part' of lb4 and I don't really need to do it, because you have :) (although that could be a nice demo of extensions in itself to see how that's done in the reference implementation). ]

With a change of domains to order/customerOrder list, product/product variant etc. you can just have one "The Store Example" section, demo-ing in steps of one or a few related 'concepts' and or 'howtos' at time how to rapidly achieve functionality: a more code first approach,

e.g (very very very loosely)

• initial concepts ( ?simple models, controllers, static routes, deploy) - Add a homepage about our upcoming store and let customers sign up to find out more, quick deploy to real world on IBM Cloud free tier - wow, look what we just did in a few minutes!
• further concepts (?related models one-to-many, repository, more complex controllers) - Add a product list to our store...
• (? basic authentication) - customer login, shopping cart (/customerOrders)
• ( authorisation/realms) Add an /admin route
• (External apis, multiple connectors) Hook up dummy Stripe payments & using Redis, order confirmation email
• (extensions) build one for some reason
• (deploy to K8) Going live!
• ( oauth/jwt, Many to many/one2one) - Allow access via service account to a stock checking app, Er....
• etc ...

Actually the logic in implementing one to many first is obvious when you try to think of simple many-to-many & one-to-one examples in the store domain without over-complicating the model: I'm sure there are plenty, but off the top of my head easier examples would be thing like books/records - authors/artists, author - Booker prize winners, so it may help to think in advance about what our store is selling to give a richer tapestry of more examples to work with using product details, for example, and also make it a bit more memorable and interesting than {"title": "product1"} (think ng heroes).

I don't have any Pets and I probably wouldn't want to buy one from an online store (maybe their accessories) but I guess as themes go it is out there

The tricky part is how to keep the example simple, so that people reading the code can quickly discover the relevant parts & understand what's just a boilerplate, and to keep the maintenance costs low

Agreed. Limiting the domains would help think : Customers (really User/Roles), Products (?with variants) , Orders (via ShoppingCart for other reasons), maybe Payments (again for other demo purposes). Should be enough. We DON'T want to be building Addresses, Suppliers, shippingRates blah...

Even with those limitations it would (I think) still be possible to deliver an 'End to End' experience within the built sample by 'selling' a digital 'product' served from an authorised static route. We could bundle a couple of tiny mp3&4s, gifs etc with the sample repo: music & video loops... A LoopStore! :)

I think a lot of this work (initially at least) is ctrl+H stuff if todos become users/Orders etc, which can be decoupled from developing the example logic completely, so sure I can start there once you know the exact direction! Better practice is probably recreating the app from scratch in accordance with the updated docs anyway, to ensure that it all works in practice when the instructions are followed?

[cloudwheels]

Previous comment edited to try to get to grips with how docs & samples fit together and can be reworked now, and what the bigger picture might be longer term.

[virkt25]

Hmm, my 2 cents on this ...

Todo, Todo-List example should be left as is and a tutorial should be implemented for loopback4-example-shopping with steps like the angular hero tour as we your suggestion @cloudwheels. And then that example can be better promoted in this repository and on the site.

Here’s the link to the repo: https://github.com/strongloop/loopback4-example-shopping

[cloudwheels]

Is the plan to lerna import the shopping example repo into loopback-next/examples?

Also, semantics I know, but "Shopping" or "Store"?, "Example" or "Tutorial"?

Actually this whole issue is really semantics: as with avoiding too much boilerplate cluttering an explanation of the concepts, does effectively telling the user, even though they almost certainly understand, "So far in other examples, we've been calling these 'Todos', but now we're calling them 'Orders'- don't worry were talking about the same concept of child relations", not just add an unnecessary thinking step vs just consistently calling them Orders across all examples?

It's also pretty low hanging fruit to make that change now vs 2 years of example building & tutorials later!

I also understand talk is cheap: I personally am more than happy to work through regenerating the sample apps with different entity names (which but nature should be a smooth & rapid process!) and work on updating docs and links for my own education / contribution :)

The possible need to revise folder structure for tutorials / examples / how tos / concepts is closely linked to #1908.

[cloudwheels]

@virkt25 Yes, "Stepped tutorial" is the phrase I was looking for. Each tutorial step being essentially as set of how-tos (which only exist as part of the tutorial referenced as linked headings/anchors), and a summary of the Key Concepts involved, under their own section as currently but using the language of a store in their supporting code snippets. (links not implemented and of course just rough idea of sample steps but should show the idea).

---

Step 1

Let's get started building our store by installing loopback and creating a controller

We'll learn how to:

• install the loopback cli an scaffold an app
• create a model for store customers add a simple controller to view and manage their data using our store api
• serve a static home page for our store from the loopback app The example should help you to understand about using these key concepts in your own application:
• Application
• [etc]

Installing Loopback CLI

Do this and that

Creating a loopback Application

Creating a Model

A loopback Model describes the entities in your application. Create Customer model Let's create a model to describe the users of our application, in this case our store customers {"user":""}

Creating a controller

Serving static pages

---

Step 2

Let's move on with or store to do this that and the other.... In the previous step of our tutorial we: learnt how to:

• install the loopback cli an scaffold an app
• [etc] and learned about these key concepts in loopback: Application, [etc]

In this step we'll create models for the products in our store and a shopping cart, then set up basic authentication so customers can sign in and manage their own orders. We're going to learn how to... Add a one to many relationship .etc., so we understand the concepts of... [Repository] etc

Adding One-to-many relations: Create a product list and user order list

Create Product model Create ProductList model Add Products to the ProductList

Adding Basic Authentication to the store with [@loopback/authentication]

---

I.E.

Step []

in [previous steps] we've done this in our store, learnt how to and explained the concept of

A. We'll do this example stuff in our store today in summary.

B. So we learn how to: how-tos-within-the-tutorial....

Query our data by exposing GraphQL APIs

deploy our app to IBM cloud

Serve static files

Migrate a Database

C. Until we understand all the concepts in https://loopback.io/doc/en/lb4/Concepts.html

[next] we'll be doing this in our store, learning how to do [this] and [this] and explaining the concept of [...]

And at the end everything will work together as one package... lb4 example

[stale[bot]]

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

[stale[bot]]

This issue has been closed due to continued inactivity. Thank you for your understanding. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository.