search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.59k stars 25.3k forks source link

Manual RenderTree snippets are incomplete #16330

Closed ShawnDigital closed 4 years ago

ShawnDigital commented 4 years ago

Unless I'm missing something the manual render example snippets are wrong/incomplete. @CustomRender is set by CreateComponent() in the method RenderComponent(), but nothing calls RenderComponent(). While prototyping Blazor I assumed this was a derived a method or convention like ChildContent but after a good bit of debugging blank screens realized nothing calls it.

Also, some explanation of the mechanism and lifecycle there would be nice for understanding it. A lambda/method is used to populate a RenderFragment Property which is then referenced in the razor/template sections. Altering things even slightly (e.g. referencing the lambda method directly, moving the population of the property, etc...) usually resulted in blank screen and only through (a lot of) trial and error could I get a successful render.

Document Details

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

ShawnDigital commented 4 years ago

After cutting and pasting as is to visual studio while looking at the ComponentBase source I found the caller but it would be nice if it showed a more realistic example that isn't triggered by a user click as its been tricky to get it setup correctly with the page lifecycle.

ShawnDigital commented 4 years ago

Hi thanks for the interest and response. As I mentioned I did find where it was calling the method, I originally copied most of the code into an existing project with its own UI so totally missed the click event and somehow didn't notice it when troubleshooting. Things are a bit clearer after looking through the source and spending more time with it, the RenderFragment delegate versus RenderFragment or simply returning a RenderFragment caused some confusion when comparing various examples (not all of them were in this doco). I'm still trying to figure out the lifecycle or at least how it fits into our use case. I've gotten examples to work then tried to enhance it and broken things accidentally several times so learning through trial and error, which considering that things are still in flux, may be of questionable value at the moment.

Our system is an edge case I'm sure similar to use cases of UI control providers. We dynamically render views provided from a service. These views/forms are created and managed by departments or managers for their workflows and at times may even be customized for a single user. This component model is shared across many platforms and if modified should automatically update when the view is navigated to again or refreshed depending on platform. I have a prototype to demo about 90% of the way there but keep breaking the rendering and spend half a day or so getting it working again (which isn't abnormal while experimenting), but wish the doco had a little more info in this area. I am hoping when schedules normalize next week after the new year I can find time to really dig through the source more.

ShawnDigital commented 4 years ago

I think the most confusing things for me are:

  1. sequence (of course) which is incorrectly explained all over including places like visual studio magazine online articles. As I understand the requirements, the value isn't important so much as they are a sequence of integrals that progress, are unique, and persist so can be used for differencing performance. Hard coding line numbers is often mentioned as a good solution but raises questions like unique within what scope since you have looping, splatting, templates etc... so how do they affect or are affected by this? Unique within what scope and timeframe e.g. do they need to persist across posts or complete page reloads or only to facilitate local routes short circuited by the router?
  2. component lifecycle and rendering cycle. It wasn't clear until reading the source that most examples are referencing a property with a RenderFragment named delegate not a property of type RenderFragment. A full example versus snippets and text would help too, but attempts with "similar looking" architectures that got contents from methods or base/helper classes or used razor templates etc... often produced unexpected results causing more confusion as errors can be vague or more commonly simply nothing is rendered and since tooling isn't fleshed out in VS it can be hard to tell whats going with no errors for the browser tools and the elements simply don't exist which makes the docs extra valuable for understanding versus trial and error.
  3. templating i.e. trying to use RenderFragment and razor templates combined with manual rendering has been difficult. Understanding the behavior based on testing alone has mixed results and rendering content that may be one thing (panel) which may recursively render its own contents or a collection of items (list) where using a razor template makes sense has been mostly trial and error resulting in solutions that feel clunky or like hacks and rely on internal functionality which is more likely to change and possibly invalidating any prototyping I do which makes documentation and best practices even more beneficial.

Its early days and a WIP so completely understandable, but blazor opens up web to existing .net code reuse so many ui control vendors and framework providers with advanced use cases will be very interested in and early adopters of this tech. I'd be happy to help/contribute, but I definitely don't feel like I understand anything well enough help document it yet lol.

Edit: Also Open/CloseRegion recommended then made internal then said it is or would be made not internal? Kind of relates to #2 but this topic specifically seems all over the map over time as things evolve.

guardrex commented 4 years ago

@ShawnDigital ... I'm back! ... it was a nice, restful break. Hope you had the same.

Ok ... so your feedback should be addressed by management, so I'm going to mark this for triage on the Blazor.Docs project. They'll come in at some point ... a few weeks probably ... and provide a response. Give them a few weeks because we're all just getting back from the extended holiday break. ⛄️ Everyone is digging out from a piles of email and issues! ⛏

A few notes to your points by numbered comment ...

  1. I defer to engineering on content pertaining to sequence (e.g., Sequence numbers relate to code line numbers and not execution order). Standby for their response to your remarks.

  2. RenderFragment

    referencing a property with a RenderFragment named delegate not a property of type RenderFragment

    I've been holding off on cross-linking to API docs in the Blazor docs. This made your research more difficult. When I get to https://github.com/aspnet/AspNetCore.Docs/issues/10931, I'll cross-link RenderFragment to RenderFragment ... and a few hundred other API mentions that need to be cross-linked. I apologize for this situation, and I plan to make a 👹 monster pass 👹 on the Blazor docs to get those cross-links in there. The problem was mostly 🕐 TIME ... high priority issues to address and the cost 💰 of the very-manual process of cross-linking. Also, Blazor WebAssembly hasn't released yet, and I favor one giant cross-linking pass after Blazor WebAssembly reaches GA. It's a 💲 cost savings 💲 to Microsoft to embrace this approach.

  3. Absolutely, I hear you. I defer to Dan to react and let us know what we can do, if anything. In general, we focus on the most common scenarios. IMO, one of the most frequent feedback comments is, 'you don't cover enough advanced scenarios.'

Its early days and a WIP so completely understandable

Thank you for that! We're aware and working hard to cover Blazor scenarios most beneficial to developers.

I'd be happy to help/contribute, but I definitely don't feel like I understand anything well enough help document it yet

I'll work with you on that. Please feel free to open doc issues for any new topic idea, new sections to existing topics, or just feedback. If you're concerned about the framework itself (the source code), open with engineering. For an existing doc, use the This page feedback button+form at the bottom of the topic, which will automatically ping me. For a new doc opened directly on the repo, ping me in your opening comment ... I'll add the appropriate labels and set it up for triage on the Blazor.Docs project.

Open/CloseRegion recommended then made internal then said it is or would be made not internal

Just due to framework churn ... it's public now, and it will stay that way.

guardrex commented 4 years ago

OH! ... and btw --- totally off topic, but we were just there for a visit. No crazy crowds in the French Quarter. We had a great time. Some of our family who were on the trip were born and raised there, so it was a family history trip, too. It was great. I encourage others to visit New Orleans and enjoy the culture, food, and music! Landry's was highlight of the trip ... ❤️ it 🍤.

ShawnDigital commented 4 years ago

Generally we try to stay away from the quarter around holidays/mardi gras, but my wife and I decided to get away (from family and obligations) and had a little staycation in the quarter the week of new years to celebrate our 10 yr anniversary so were probably in the area. Glad you had a good time. There's a certain character here that makes it hard to live in places after you stay here a while although the hot months like Aug/Sept may make you seriously consider it. :)

ShawnDigital commented 4 years ago

We really do appreciate the work! We've been excited for Blazor (and WebAssembly) since we first heard about it. We've been laying the ground work for consolidating a bunch of platform specific code in preparation for a "single-pane" UX looming on our roadmap for years and when we got wind of it we hoped Blazor would be viable in time and the timing has been perfect. Took a little fumbling around at first, but currently very happy with the proof of concept we have so far for a hosted app and eventually hope to transition to wasm. Its saved us months if not years of recreating a ton of functionality for the web by reusing our existing cross platform libraries.

guardrex commented 4 years ago

@mkArtakMSFT @danroth27 I've done what I can on my own for this issue ...

I'll need guidance to continue on this issue or for engineering to provide the exact updates, if any. If the remainder of @ShawnDigital's asks are "advanced scenarios" that we won't cover, then we can close this issue.

@ShawnDigital, if we close on the grounds of further coverage falling into the advanced scenarios bucket, it's because the docs generally seek to cover the base cases for the vast majority of general Blazor scenarios. We leave a number of advanced scenarios to devs to work out from basic concepts, the framework reference source, engineering repo issue discussions, the API docs, blogs, chat, books, etc. We're a small team with limited time, so we have to prioritize coverage for what 95% of devs will be doing with Blazor.

ShawnDigital commented 4 years ago

I've kind of moved beyond the blazor docs and mostly just dealing with integration issues and fighting css and third party controls so haven't been looking at it much lately. Look back in hindsight based on my bad recollection the two main hurdles were the render delegate and lifecycle methods. In snippets from the docs it wasn't obvious what it was calling i.e. if it was a abstract/base method or builtin convention like ChildContent and I think I had to find the source to find the delegate which at the time wasn't easy. It looked like renderfragment properties you saw in templates so took some trial and error to get the snippet working. I think that is found with the manual rendering which is advanced but kind of ties into razor templates and templated components and renderfragments are handled (some of which is just VS being flaky with razor files & render fragments. I think api cross references helps alot. The other was (is) a general lack of clarity on the lifecycle methods. When are they called/not called what should / should not be done there etc...quite a few bugs I've encountered were due to setting something in the wrong place so it doesn't get updated or it gets replaced or causes unexpected duplication etc... so if thats already planned, sounds good to me.

guardrex commented 4 years ago

We've worked on and are continuing to work on the lifecycle methods.

There have been PRs since you opened this issue, and all Blazor topics will be receiving a big UE (user experience) pass soon-ish ... within a month or two if my plans work out.

I even have an open one now for review that helps (I hope) ...

Blazor lifecycle ordering clarifications — https://github.com/dotnet/AspNetCore.Docs/pull/18610

As for the rest :point_up: of your feedback ... things that I couldn't directly address, I'll leave this open a bit longer for engineering to look. If they don't say anything tho :ear:, then I'll close, and we'll keep working on these topics in the coming weeks and months before new 5.0 preview content starts to land.

guardrex commented 4 years ago

I'm going to close now. Engineering management hasn't remarked further. These topics have received a number of improvements since this issue was opened, including improvements to the Lifecycle topic. We also have all of the API doc cross-links in place, which would've probably helped at the time.

Thanks for the feedback and discussion @ShawnDigital.