Cover a QuickGrid main-detail page approach

[guardrex]

Fixes #37019
Addresses #37020

Daria, let's work on this from this new PR. I was using a patch PR before, but I'd like to have it on a branch for edits.

You'll see that I've commented-out the 11.0 or later parts. We can't surface it until Preview 5 lands. It can sit like this until the time comes.

I also placed a link in that commented-out coverage to "URL-based navigation," which is just a placeholder for all of the QuickGrid static SSR Preview 5 coverage that will be coming about a week before Preview 5 lands. I usually wait to cover preview bits until close to the preview release because I like to avoid merge conflicts if possible. This way, we can get this coverage merged now. At P5, I'll activate the commented-out parts here and fix it up.

For the upcoming coverage on QG bits for static SSR, I had already placed a tracking item for it in my main .NET 11 tracking issue at #36448. I'm sure that you're aware of Dan's pitch that PU engineers should write up new feature coverage. If that's what will happen for the QG static SSR coverage, you can add it as an issue comment on #37102. I'll take care of everything from there. Please let me know on that issue if you plan to write it up. If not in this case ... if I should write it up, I'll do so from the PU issue/PR and ping you for review near the P5 release.

One more thing ... I think I understand why the new URL-based navigation uses one-based page indexing in the page parameter. I think it's because that's what will match what the Paginator visually shows ... 1, 2, 3, etc. What I currently have on the PR about the index is ...

Opens the preceding `Details` component with the current page index incremented by one (`+1`) to make the value a one-based index (<xref:Microsoft.AspNetCore.Components.QuickGrid.PaginationState.CurrentPageIndex%2A>) in the query string.

That doesn't explicitly say why. Do you think we should add a remark there to tell devs that it works that way to match the Pagniator's rendered index? ... 🤔 ... I'm leaning in the direction of adding a remark or two there. Of course, when the URL-based nav is explained fully elsewhere, we'll very likely include a remark like that. But here, I think it would be a good idea to state it as well.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/blazor/components/quickgrid.md	aspnetcore/blazor/components/quickgrid

[dariatiurina]

@guardrex I did index starting from 1 so that UI and URL will have the same state. And adding remark here would be great, because we do some tricks with +1, so it would be helpful to say why we do it.

[guardrex]

@dariatiurina ... Added the remark 👍 ... and I thought it was a good idea to do that for the <11.0 demonstration. Both now use a one-based page qs parameter value.

Note that I now need at least one formal GH approval to get anything merged on this repo. Can you approve if you agree with the updates? If so, I'll merge this now. We'll pick back up at P5 with the next round of QG article updates.

[Copilot]

Pull request overview

Adds documentation to the Blazor QuickGrid article describing a main/detail navigation pattern where a user can open a details page from a paged grid and return to the correct page, using PaginationState APIs.

Changes:

• Expanded QuickGrid.Pagination parameter description to mention PaginationState page-index related APIs.
• Added a new section with Details.razor / Characters.razor examples showing how to preserve/restore the grid page when navigating to/from a details page.
• Staged (commented-out) .NET 11+ URL-based navigation content for later activation.

Comments suppressed due to low confidence (2)

aspnetcore/blazor/components/quickgrid.md:333

• This code sample won't compile as written: Page is declared as int, but the code uses Page.HasValue and Page.Value. Make Page nullable (int?) or change the conditional/usage accordingly (and ensure the value is validated before subtracting 1 to convert from one-based page numbers to the zero-based PaginationState index).

    protected override async Task OnInitializedAsync()
    {
        if (Page.HasValue)
        {
            await pagination.SetCurrentPageIndexAsync(Page.Value - 1);

aspnetcore/blazor/components/quickgrid.md:285

• The bullet says the page index is set with the value of Page, but PaginationState.SetCurrentPageIndexAsync expects a zero-based index. Since the query string value is one-based in this example, the description should note the conversion (for example, set the current page index to Page - 1).

* Pages the `QuickGrid` component by calling <xref:Microsoft.AspNetCore.Components.QuickGrid.PaginationState.SetCurrentPageIndexAsync%2A?displayProperty=nameWithType> on component initialization, setting the page index with the value of `Page`.
* Opens the preceding `Details` component with the current page index incremented by one (`+1`) to make the value a one-based index (<xref:Microsoft.AspNetCore.Components.QuickGrid.PaginationState.CurrentPageIndex%2A>) in the query string. A one-based index for the `page` query string parameter matches the rendered `Paginator` component's rendered one-based page number in the UI.

[guardrex]

@dariatiurina ... Stand-by ... I'll address Copilot's concerns. It raised a few good points.

[guardrex]

@dariatiurina ... Ok, I think that's better. It might need a hair more work.

For the >=11.0 remark ...

Automatically pages the `QuickGrid` component on component initialization using [URL-based navigation](#url-based-navigation), which sets the page index from the value of `Page` minus one (`-1`).

Is that true? Is the Page property what's actually used by the framework with the new URL-based nav? ... because it seems like it might work by automatically just looking at the query string for the "page" query string parameter (or {PREFIX}_page) and drawing the value from that directly. If that's the case, then I guess the characters component doesn't need the Page property at all when the new URL-based nav is active.

[dariatiurina]

@guardrex Yes, everything is automatic and Page can be deleted from Characters page, because I don't see it used anywhere except for it being assigned, hah.

[guardrex]

I'll take care of that right now.

[dariatiurina]

My biggest problem with the .NET 10 example is that after you return to the Characters page from Details and then you do some navigation back-forth in QuickGrid URL is stale and you still see ?page={initial load}.

[guardrex]

Is there a way around that tho? I figured that that's kinda what we'd be stuck with.

The bright side tho is that .NET 11 or later, we'll have the nicer bits that you're making available.

If you have a different approach tho for <11.0, then let's do that. I only did it this way because it seemed like the obvious, simple way to manage it.

[guardrex]

Can we zap the entire query string cleanly (across render modes for example) on initialization after the current index page is set?

[guardrex]

Maybe so! ...... from our coverage, I see ...

Use GetUriWithQueryParameter to add, change, or remove one or more query parameters on the current URL:

I'll play with it and see what happens!

[dariatiurina]

In OnInitializedAsync you can set page and set do NavigateTo without anything for the Page parameter? If that's what you mean by "zapping"

[guardrex]

I'm going to have to see what's possible. It's been a couple of years since I've worked with that bit of the navigation API. Hopefully, we can read the page for setting the index and remove it immediately in initialization. It's covered over here ...

https://learn.microsoft.com/aspnet/core/blazor/fundamentals/navigation?view=aspnetcore-10.0#query-strings

[guardrex]

Looks like this will work ...

Navigation.NavigateTo(Navigation.GetUriWithQueryParameter("page", (int?)null));

I put it on the PR with an updated remark.

Do you have any concerns about it for CSR or static SSR?

Well ... static SSR is a no-go because the whole QG doesn't work unless interactive ... until your bits go out for .NET 11! 😄 At that point, the <11.0 approach won't be shown.

I think it's fine for CSR. I don't expect any problems for client-side rendering. Let me know if you have a concern about that.

[dariatiurina]

Looks good!

[guardrex]

Thanks for your help with this! It's a great add to the article.

I'll keep an 👁️ out for your P5 QG coverage on that issue ... if you're writing it. If not tho, no worries ... I'll write it up later if you and Dan prefer I take care of it.