Replace 'Build your first' tutorial

guardrex commented 5 years ago

[EDIT] Work this issue with the feedback from Add startup code block on Build your first app page #13607.

From @guardrex on https://github.com/aspnet/Blazor.Docs/issues/56 ...

The plan was to go with Galactic Flight Finder concept. Like Flight Finder but for interstellar travel among planets as opposed to airports on Earth. Considerable progress was made on a version of the app for this, but the 2.1 RTM took priority and the sample was left in an unfinished state at the Blazor 0.5.0 release.

From danroth27 ...

The idea was that this would be our flagship tutorial, similar to the Angular or React tutorials. I don't think FlightFinder is that much more complicated than the Angular Tour of Heroes app. The tutorial should start as simple as possible introducing basic concepts and working up to more advanced ones. This can be done in multiple parts where at the end of each part you feel like you've made progress and by the end you have the fully functioning app.

We should also publish a live version of the tutorial once it's done and published.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

ID: 36e7dc3c-54c4-35de-203e-d230869e8417
Version Independent ID: dc5b52d5-c8c6-1440-6b3a-fda898167d0c
Content: Build your first Blazor app
Content Source: aspnetcore/tutorials/build-your-first-blazor-app.md
Product: aspnet-core
GitHub Login: @guardrex
Microsoft Alias: riande

danroth27 commented 5 years ago

For a more involved intro to Blazor we now have a Blazor workshop: https://aka.ms/blazorworkshop

guardrex commented 5 years ago

@danroth27 Following up on "Todo Items experience is lame!" :smile: I agree, we can do better here.

Galactic Flight Finder remains a smok'in cool concept. I agree that Steve's Flight Finder is too advanced for a build-your-first experience, but I think that I can build a sweet Galactic Flight Finder section experience to replace the Build a Todo list experience in the Build your first topic.

The alternative is a full Galactic Flight Finder advanced experience as a standalone topic. Even if we create a new topic for it, I still recommend getting away from the Todo Item experience in the Build your first topic. We could have a Galactic Flight Finder section for the Build your first topic to replace the Todo Item experience AND have an advanced build-your-second experience.

danroth27 commented 5 years ago

We also now have the Blazing Pizzas app in the Blazor workshop: https://aka.ms/blazorworkshop. For a more advanced scenario, maybe that's sufficient?

I'm still open though to a cooler getting started app to replace the todo app. But I agree that it can't be too complicated.

guardrex commented 5 years ago

Yes, I like pizza 🍕 ... and the app, too.

Should the Todo Item component of the current Build your first topic be a basic, low-level pizza app-themed experience to match the advanced topic? ... similar to what's done in the Todo Item experience but using pizza app theming and concepts?

danroth27 commented 5 years ago

I don't think there's any requirement that the scenario for the app is the same. For the build-your-first-app I think we just need something simple and compelling. Todo list is simple, but not particularly compelling. I think Blazing Pizzas is compelling, but I'm not sure we can come up with a version of it that is simple enough for your first web app. I'm open to suggestions though!

guardrex commented 5 years ago

I'll brainstorm on it ... something no deeper in concepts or longer than the current Todo Item experience. I'll think along the lines of pizza-related and Galactic Flight Finder-related concepts first. I'll post whatever I come up with here for discussion before doing anything with the topic.

guardrex commented 5 years ago

Here's a concept list for the current Build your first tutorial:

Concepts

Template Counter component
- Pages are implemented by components.
- Component anatomy
- Components use HTML and Razor with dynamic rendering logic.
- @functions holds component class members.
- Events (registration, render tree, DOM updates) – Click me button onclick and IncrementCount.
- Component nesting – Survey Prompt component and add Counter component to Index component.
- Component parameters – Add a property, use the property, set the property from a parent component.
- Component anatomy, routing, DI, and Razor
- @page directive
- @inject directive
- Use DI in a component
  - Server-side: WeatherForecastService
  - Client-side: HttpClient
- Razor enumeration of service-returned object
New ToDo Items component
- New component
- Navbar navigation to a component
- Use a model in a component – TodoItem/List<TodoItem>
- Component works with items in a collection via UI elements
- Events
  - Read – List todo items
  - Create – button onclick with AddTodo method
- Databinding to UI element – todo.IsDone/todo.Title/newTodo
- Razor+Linq feedback – @todos.Count(todo => !todo.IsDone)

I'm just about completely positive that I can make a nice little Galactic Flight Finder that covers these concepts at a similar length without much additional depth.

Notes + I-dears

Make the finder part just a single <input> filter function on the name of the planet.
I think the images are critical for the galactic flight finder concept to 🎸 JAM! 🎷, and we don't talk about static assets currently. Instead of dropping NASA public domain planet images into the app for the component to consume, I'd investigate using stable links to their content. It's almost the same thing as using static assets. [EDIT] Yes! ... We're good here for commercial purposes. As long as it isn't a NASA emblem/logo, there are no people in the image, it doesn't indicate any endorsement, and the image doesn't have a listed copyright ... yes ... we can hotlink right to their content. NASA guidelines They just want image credit ... np. NASA exoplanet example
I think we can have the dev create a small service akin to the WeatherForecastService that shoots back a small collection of planet data to cover the DI angle. In addition to the images, the actual Sci-Fi movie planet names are critical for the coolness factor here imo. We can cover the CELA aspects appropriately with copyrights and links.
The user can add a planets (name and image URL) to the collection.

I'd like to give this a shot this weekend. Shall I proceed with a draft?

mcabram commented 5 years ago

Pretty good tutorial. Finish it. Looking for more tutorials.

guardrex commented 5 years ago

@Michaelwan777 You saw the workshop, right? ... https://github.com/dotnet-presentations/blazor-workshop/

mcabram commented 5 years ago

@guardrex no yet. Just found this pizza tutorial. Gonna to do it. Thanks for mentioning it

guardrex commented 5 years ago

~I'll be turning that into a topic here soon on Create advanced Blazor tutorial #12516 ... within a week or two.~ Issue Dropped

guardrex commented 5 years ago

I've placed this prototype here :point_right: https://github.com/guardrex/BuildYourFirstBlazor

In order to keep it simple and focused on the learning objectives, what the test project evolved into is a Doctor Who Planet Database app.

There's a service ...

public class PlanetService : IPlanetService
{
    // Planet names are ©1974-1981 BBC. https://www.bbc.co.uk/
    // Planet images are courtesy of the National Aeronautics and Space Administration (NASA). 
    // https://www.nasa.gov/
    private List<Planet> _planets = new List<Planet>
    {
        new Planet { ImageUrl = "<NASA HOTLINK URL HERE>", Name = "Skaro" },
        new Planet { ImageUrl = "<NASA HOTLINK URL HERE>", Name = "Skonnos" },
        new Planet { ImageUrl = "<NASA HOTLINK URL HERE>", Name = "Argolis" },
        ... more planets ...
    };

    public IEnumerable<Planet> GetPlanets(string filter)
    {
        if (string.IsNullOrEmpty(filter))
        {
            return _planets;
        }
        else
        {
            return _planets.Where(f => 
                f.Name.StartsWith(filter, StringComparison.OrdinalIgnoreCase));
        }
    }

    public void AddPlanet(Planet Planet)
    {
        _planets.Add(Planet);
    }
}

Those NASA images are high res and slow to receive, but they cache and are quick-loading thereafter.

There's a component with scenarios analogous to those found in the Todo Items component that should take a similar amount of time to explain+build ...

@page "/"
@using BuildYourFirstBlazor.Interfaces
@using BuildYourFirstBlazor.Models
@inject IPlanetService PlanetService

<h1>Planets</h1>

<div>
    <input oninput="@FilterPlanets" placeholder="Filter planets" />
</div>

<div class="planets">
    @foreach (var planet in _planets)
    {
        <figure>
            <img alt="Image of @planet.Name" src="@planet.ImageUrl" />
            <figcaption><em>@planet.Name</em></figcaption>
        </figure>
    }
</div>

<div>
    <h2>Add Planet</h2>

    <input bind="@_newPlanet.Name" placeholder="Name" />
    <input bind="@_newPlanet.ImageUrl" placeholder="Image Url" 
        style="width:350px" />

    <button class="btn btn-primary" onclick="@AddPlanet">Add Planet</button>
</div>

<div style="position:absolute;bottom:0">
    <p>
        Planet names are &copy;1974-1981 
        <a href="https://www.bbc.co.uk/programmes/b006q2x0">BBC</a>.
        Planet images are courtesy of the <a href="https://www.nasa.gov/">
        National Aeronautics and Space Administration (NASA)</a>.
    </p>
</div>

@functions {
    private IEnumerable<Planet> _planets;
    private Planet _newPlanet = new Planet();

    protected override void OnInit()
    {
        _planets = PlanetService.GetPlanets(null);
    }

    private void FilterPlanets(UIChangeEventArgs e)
    {
        _planets = PlanetService.GetPlanets(e.Value.ToString());
    }

    private void AddPlanet()
    {
        PlanetService.AddPlanet(_newPlanet);
        _newPlanet = new Planet();
    }
}

A smidgen of CSS for the repeating <figure> ...

.planets figure {
    display: inline-block;
    margin: 10px 5px;
}

    .planets figure img {
        height: 100px;
        border-top-left-radius: 10px;
        border-top-right-radius: 10px;
    }

    .planets figure figcaption {
        border: 1px dotted blue;
        text-align: center;
    }

The result without applying filter characters ...

The <input> element immediately filters character-by-character. For example, type "z" in the filter and instantly receive ...

Seems more interesting and fun than Todo Items, but is it fun enough? Is there enough 🐄🔔 for the experience?

I did consider just making it a NASA Exoplanet Database app, but that seemed a hair less interesting to me than Doctor Who planets ... a personal bias, of course! lol

guardrex commented 5 years ago

@danroth27 I'm ready to proceed :point_up:, react to feedback on that concept, or try again with similar learning objectives using a different theme/concept.

Schedule+issue progress is look'in great. I anticipate knocking this out and then getting on to the Blazing Pizza advanced tutorial in the next couple of days.

Can u triage the next group? I'm just about ready for more. 🏃 https://github.com/aspnet/AspNetCore.Docs/projects/35

danroth27 commented 5 years ago

I like the concept and the planet pictures look great :smile:. As much as I love Doctor Who I don't think we can refer to it directly in the app though. I think a more generic "Galactic Planetary Atlas" or something similar is preferred. But I think we might be able to use the NASA images and the pop culture planet names. I'll look into it.

guardrex commented 5 years ago

I agree that a license would be safest. Here's the form if you want to forward it to CELA ... https://www.bbc.co.uk/branding/logo_use/input ... I can supply the descriptive information for the fields if it comes to that.

I'll go with "Galactic Planetary Atlas." If that doesn't fit the sidebar, I'll make it "Planetary Atlas."

I'm going to go ahead and work this up into a PR. I'll probably have it in by the EOD (Thursday).

[EDIT] Working it a bit more today ... want to make sure learning objectives are good. Should have this done by this afternoon (Friday).

So far, so good.

screenshot

guardrex commented 5 years ago

We're going to track next steps here on the issue. I'm going to close the current PR, which was out-of-sync with my local branch anyway and doesn't have content to cover all of the updates we made to the app.

The app will remain at ...

https://github.com/guardrex/PlanetAtlas

... for further review and feedback.

mkArtakMSFT commented 2 years ago

@danroth27 should we close this at this point given that it's been sitting idle for so long (priorities... priorities...)

danroth27 commented 2 years ago

Yup, we've decided to stick with ✅ todo lists and pizza :pizza:.

dotnet / AspNetCore.Docs