|
| 1 | +# <Lazy /> |
| 2 | + |
| 3 | +Renders a Component (`IComponent`) from a Lazy Module based on it's **LazyName** or **TypeFullName** (*string*). |
| 4 | + |
| 5 | +This Component needs to exist in a *known* Lazy Module, either [hinted directly](Configuring-Lazy-Loading-@-Server#modulehints) or using [ModulesHost strategy](Creating-a-Lazy-Loadable-Module#creating-an-aggregated-module). |
| 6 | + |
| 7 | +# Render by using TypeFullName |
| 8 | + |
| 9 | +The is no extra prerequisite to render an `IComponent` by using **TypeFullName**: |
| 10 | + |
| 11 | +```razor |
| 12 | +<Lazy Name="MyApplication.Hello" /> |
| 13 | +``` |
| 14 | + |
| 15 | +This snippet renders a `Hello` Component assuming the type is `MyApplication.Hello`. It will **automatically fetch** the manifests, consume them to **locate** the Component and **download** the minimum assemblies to make it work 😄 |
| 16 | + |
| 17 | +# Named Components |
| 18 | + |
| 19 | +It is possible to **manually name** your Components and use that name later to resolve them.<br /> |
| 20 | +This is done by adding a simple **attribute** `BlazorLazyLoading.LazyNameAttribute` to your Component: |
| 21 | + |
| 22 | +* Syntax: `.razor` |
| 23 | + ```razor |
| 24 | + @attribute [LazyName("SayHello")] |
| 25 | + <h1>Hello!</h3> |
| 26 | + ``` |
| 27 | +
|
| 28 | +* Syntax: `.cs` |
| 29 | + ```cs |
| 30 | + [LazyName("SayHello")] |
| 31 | + public class Hello : IComponent { ... } |
| 32 | + ``` |
| 33 | +
|
| 34 | +And then **render** it like the following: |
| 35 | +
|
| 36 | +```razor |
| 37 | +<Lazy Name="SayHello" /> |
| 38 | +``` |
| 39 | + |
| 40 | +In order to *debug* if your component **name** is generated properly, you can check the contents of `_lazy.json`. |
| 41 | +```json |
| 42 | +{ |
| 43 | + "MyApplication": { |
| 44 | + "Components": [ |
| 45 | + { |
| 46 | + "TypeFullName": "MyApplication.Hello", |
| 47 | + "Name": "SayHello" |
| 48 | + } |
| 49 | + ] |
| 50 | + } |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +# Custom 'Loading' view |
| 55 | + |
| 56 | +It is possible to customize the `<Lazy>` Component with a **loading** `RenderFragment` that will get rendered while everything is being initialized. |
| 57 | + |
| 58 | +It only requires setting a `RenderFragment` called `Loading`: |
| 59 | + |
| 60 | +```razor |
| 61 | +<Lazy Name="SayHello"> |
| 62 | + <Loading> |
| 63 | + <p>Loading, please wait</p> |
| 64 | + <div class="spinner" /> |
| 65 | + </Loading> |
| 66 | +</Lazy> |
| 67 | +``` |
| 68 | + |
| 69 | +# Custom 'Error' view |
| 70 | + |
| 71 | +It is possible to customize the 'error' `RenderFragment` that gets renderd if the Component fails to initialize *(because some assembly failed to load, such element doesn't exist, etc)*. |
| 72 | + |
| 73 | +It only requires setting a `RenderFragment` called `Error`: |
| 74 | + |
| 75 | +```razor |
| 76 | +<Lazy Name="SayHello"> |
| 77 | + <Error> |
| 78 | + <p class="error">Something bad happened</p> |
| 79 | + </Error> |
| 80 | +</Lazy> |
| 81 | +``` |
| 82 | + |
| 83 | +# Handling Errors |
| 84 | + |
| 85 | +It is possible to specify if a Component is **Required** (if a loading error throws an exception) by setting the property `Required` *(bool)* on it. |
| 86 | + |
| 87 | +```razor |
| 88 | +<Lazy Required="false" Name="Unknown" /> @* this will simply not get rendered *@ |
| 89 | +<Lazy Required="true" Name="Unknown" /> @* this will throw an exception *@ |
| 90 | +@* both will render the 'error' view *@ |
| 91 | +``` |
| 92 | + |
| 93 | +# Hooking into Events |
| 94 | + |
| 95 | +There are 2 Events you can hook to by just setting Callbacks in the Component: |
| 96 | + |
| 97 | +* #### OnBeforeLoadAsync |
| 98 | + |
| 99 | + This callback will be awaited **before** trying to resolve the Component from the manifests. |
| 100 | + Useful for delaying a Component render to perform another operation before, and Debugging with `Task.Delay`. |
| 101 | + |
| 102 | +* #### OnAfterLoad |
| 103 | + |
| 104 | + This callback will be invoked **after** resolving and rendering the lazy Component. |
| 105 | + |
| 106 | +```razor |
| 107 | +<Lazy |
| 108 | + Name="SayHello" |
| 109 | + OnBeforeLoadAsync="l => Task.Delay(500)" |
| 110 | + OnAfterLoad='l => Console.WriteLine($"Loaded LazyComponent: {l.Name}")' /> |
| 111 | +``` |
| 112 | + |
| 113 | +# SEO and Prerendering Support |
| 114 | + |
| 115 | +Don't worry about SEO. If you use BlazorServer or Prerendering, the Component HTML will be **fully rendered** automatically by the server so there is no difference between rendering it directly and using `<Lazy>`. |
0 commit comments