diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2aaf27f5dd..326c9944e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,7 +51,7 @@ This repository uses the following tooling. See below for more info. 1. Write a spec describing the API and behavior of the component. See instructions for [component specs](/specs/README.md). 2. Ensure UX specs are up to date and tokens are generated. See instructions for [contributing to Nimble Tokens](/packages/nimble-tokens/CONTRIBUTING.md). 3. Expose any tokens in the token provider and add web component logic. See instructions for [contributing to Nimble Components](/packages/nimble-components/CONTRIBUTING.md). -4. Add wrappers for each framework. See instructions for [adding Angular wrappers](/packages/angular-workspace/nimble-angular/CONTRIBUTING.md). See instructions for [adding Blazor wrappers](/packages/nimble-blazor/CONTRIBUTING.md). +4. Add wrappers for each framework. See instructions for [adding Angular wrappers](/packages/angular-workspace/nimble-angular/CONTRIBUTING.md). See instructions for [adding Blazor wrappers](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md). 5. Publish and use! 🎉 ## Documentation policies diff --git a/change/@ni-nimble-blazor-a9914c9f-4ea3-473f-b8a9-372855b20c2c.json b/change/@ni-nimble-blazor-a9914c9f-4ea3-473f-b8a9-372855b20c2c.json new file mode 100644 index 0000000000..5d37fdabcb --- /dev/null +++ b/change/@ni-nimble-blazor-a9914c9f-4ea3-473f-b8a9-372855b20c2c.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "Update Blazor docs for Spright and workspace change", + "packageName": "@ni/nimble-blazor", + "email": "7282195+m-akinc@users.noreply.github.com", + "dependentChangeType": "patch" +} diff --git a/change/@ni-nimble-components-77f57124-12c0-45f1-b1e7-69f211fc2e7b.json b/change/@ni-nimble-components-77f57124-12c0-45f1-b1e7-69f211fc2e7b.json new file mode 100644 index 0000000000..3cb2d90204 --- /dev/null +++ b/change/@ni-nimble-components-77f57124-12c0-45f1-b1e7-69f211fc2e7b.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "Update Blazor docs for Spright and workspace change", + "packageName": "@ni/nimble-components", + "email": "7282195+m-akinc@users.noreply.github.com", + "dependentChangeType": "patch" +} diff --git a/change/@ni-nimble-tokens-e091ea87-cc71-4f0c-9a76-45ef350779a8.json b/change/@ni-nimble-tokens-e091ea87-cc71-4f0c-9a76-45ef350779a8.json new file mode 100644 index 0000000000..a829e88346 --- /dev/null +++ b/change/@ni-nimble-tokens-e091ea87-cc71-4f0c-9a76-45ef350779a8.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "Update Blazor docs for Spright and workspace change", + "packageName": "@ni/nimble-tokens", + "email": "7282195+m-akinc@users.noreply.github.com", + "dependentChangeType": "patch" +} diff --git a/change/@ni-spright-blazor-aecd2f90-e8d3-4a09-96c2-c5db85ec2d13.json b/change/@ni-spright-blazor-aecd2f90-e8d3-4a09-96c2-c5db85ec2d13.json new file mode 100644 index 0000000000..342c84cdd7 --- /dev/null +++ b/change/@ni-spright-blazor-aecd2f90-e8d3-4a09-96c2-c5db85ec2d13.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "Update Blazor docs for Spright and workspace change", + "packageName": "@ni/spright-blazor", + "email": "7282195+m-akinc@users.noreply.github.com", + "dependentChangeType": "patch" +} diff --git a/packages/blazor-workspace/CONTRIBUTING.md b/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md similarity index 97% rename from packages/blazor-workspace/CONTRIBUTING.md rename to packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md index 7662468497..323fed9080 100644 --- a/packages/blazor-workspace/CONTRIBUTING.md +++ b/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md @@ -121,13 +121,13 @@ When creating a new project in the Blazor workspace, ensure it includes the foll ### Enabling IIS Click Start, open "Turn Windows features on or off", and configure "Web Management Tools" and "World Wide Web Services" in the following way: -![IIS Feature Configuration](/packages/nimble-blazor/docs/WindowsFeatures-IIS.jpg) +![IIS Feature Configuration](/packages/blazor-workspace/docs/WindowsFeatures-IIS.jpg) ### Running published output The commandline build will create a published distribution of the Blazor client example app, which can also be tested via IIS: - Open Internet Information Services (IIS) Manager - In the left pane, right click "Sites" and click "Add Website..." - Pick a site name -- Under "Physical Path", click [...] and browse to your `nimble-blazor\dist\blazor-client-app` directory +- Under "Physical Path", click [...] and browse to your `blazor-workspace\dist\blazor-client-app` directory - Under "Binding", pick a port other than 80 (such as 8080), then click "OK" - Open http://localhost:8080 (or whatever port you chose) \ No newline at end of file diff --git a/packages/blazor-workspace/NimbleBlazor/NimbleBlazor.csproj b/packages/blazor-workspace/NimbleBlazor/NimbleBlazor.csproj index 2440f5fa6e..17962684fe 100644 --- a/packages/blazor-workspace/NimbleBlazor/NimbleBlazor.csproj +++ b/packages/blazor-workspace/NimbleBlazor/NimbleBlazor.csproj @@ -6,6 +6,7 @@ enable embedded NI + README.md https://github.com/ni/nimble https://github.com/ni/nimble git @@ -57,6 +58,7 @@ + diff --git a/packages/blazor-workspace/NimbleBlazor/README.md b/packages/blazor-workspace/NimbleBlazor/README.md new file mode 100644 index 0000000000..b37ff01262 --- /dev/null +++ b/packages/blazor-workspace/NimbleBlazor/README.md @@ -0,0 +1,150 @@ +# Nimble Blazor + +[![Nimble Nuget Version](https://img.shields.io/nuget/v/NimbleBlazor.svg)](https://www.nuget.org/packages/NimbleBlazor) + +## Getting Started + +### Prerequisites + +1. IDE: + - **Windows with Visual Studio**: For Blazor development on Windows, the suggested IDE is: + - Visual Studio 2022 ([Enterprise, if available](https://my.visualstudio.com/Downloads?PId=8229)): Choose the "ASP.NET and Web Development" Workload in the installer + - Ensure Visual Studio is completely up to date (v17.1.6+): In Visual Studio click "Help" then "Check for Updates" + - **Mac with Visual Studio Code**: Install [Visual Studio Code](https://code.visualstudio.com/) and open it. Open the Extensions pane ("Preferences" >> "Extensions"), and search for / install the `ms-dotnettools.csharp` extension. +2. .NET SDK: See [the main contributing doc](/CONTRIBUTING.md) for the required version. + +### Creating a new Blazor project + +The built-in Blazor template projects are good starting points. First, decide whether to create a Blazor Server or Blazor Client/WebAssembly application (see the [Blazor hosting model documentation](https://docs.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0) for more information on both models). + +**Visual Studio**: Choose "New" >> "Project", and pick "Blazor Server app" or "Blazor WebAssembly app". +**VS Code**: Create a new folder, then open it in VS Code. Choose "View" >> "Terminal", and type `dotnet new blazorserver -f net6.0` (for Blazor Server) or `dotnet new blazorwasm -f net6.0` (for Blazor WebAssembly) and press Enter. Open the Command Palette ("View" >> "Command Palette" or Ctrl-Shift-P), enter ".NET Generate Assets for Build and Debug" and press Enter. + +Additional Resources: [Microsoft tutorial: Build a web app with Blazor](https://docs.microsoft.com/en-us/learn/modules/build-blazor-webassembly-visual-studio-code/); [`dotnet new` documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new) + +### Reference NimbleBlazor in a Blazor project + +1. Add a PackageReference to the NimbleBlazor NuGet package: + - Using the published NimbleBlazor NuGet package (recommended) + - Visual Studio: "Project" >> "Manage NuGet Packages", pick "nuget.org" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button. + - VS Code: Run the command `dotnet add package NimbleBlazor --source https://api.nuget.org/v3/index.json --prerelease` in the Terminal window. + - For Nimble developers, with a locally built NimbleBlazor NuGet (built from the Nimble repo): + - Run `npm run build`, and then `npm run pack -w @ni/nimble-blazor` from the root of the Nimble repo + - Visual Studio: "Project" >> "Manage NuGet Packages". Click the gear/Settings button. Add a new Package Source ("NimbleBlazor") as `[NimbleRepoDirectory]\packages\blazor-workspace\dist` and commit/ close Settings. Pick "NimbleBlazor" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button. + - VS Code: Run the command `dotnet add package NimbleBlazor --source [NimbleRepoDirectory]\packages\blazor-workspace\dist` in the Terminal window. +2. Add required references to Blazor code + - Open `_Imports.razor`, and add a new line at the bottom: `@using NimbleBlazor` + - Open `_Layout.cshtml` (BlazorServer) / `wwwroot/index.html` (Blazor WebAssembly). + At the bottom of the `` section (right before ``), add + ```html + + ``` + At the bottom of the `` section (right before ``), add + ```html + + ``` + +Additional Resources: [`dotnet add package` documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package) + +### Use Nimble Blazor components + +For a simple modification to the Blazor template project: open `Index.razor` and add the following code at the bottom, to add a Nimble text field that updates when a Nimble button is clicked: +```cs + +Click Me +@code { + protected string ButtonClickStatus { get; set; } = string.Empty; + private int _buttonClickCount = 0; + + private void OnButtonClicked(MouseEventArgs args) + { + _buttonClickCount++; + ButtonClickStatus = $"Button Clicked {_buttonClickCount} times"; + } +} +``` + +To test out your changes, do "Debug" >> "Start without Debugging" in Visual Studio, or `dotnet watch run` in the VS Code Terminal. + +More complete examples can be found in the Demo.Client/Server example projects. + +#### NimbleTable usage + +The `NimbleTable` requires that its data be set via the `SetDataAsync` method. The appropriate place to call this method is either in the `OnAfterRenderAsync` override of the hosting component or after that method has been called for the first time. + +As the `NimbleTable` is generic a client must supply its generic type in the markup using the `TData` property syntax. The following code represents a typical usage of the `NimbleTable`: +```html + +@code { + private NimbleTable? _table; + private IEnumerable TableData { get; set; } = Enumerable.Empty(); + ... + public override async Task OnAfterRenderAsync(bool firstRender) + { + await base.OnAfterRenderAsync(firstRender); + await _table.SetDataAsync(TableData); // populate TableData before here + } + + public class MyRecordType + { + ... + } +} +``` + +For more information regarding the Blazor component lifecycle mechanisms (such as `OnAfterRenderAsync`), please consult the [Microsoft Blazor docs](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/lifecycle). + +### Theming and Design Tokens + +To use Nimble's theme-aware design tokens in a Blazor app, you should have a `` element as an ancestor to all of the Nimble components you use. The app's default layout (`MainLayout.razor` in the examples) is a good place to put the theme provider (as the root content of the page). + +#### Using Nimble Design Tokens (CSS/SCSS) + +Blazor doesn't have built-in support for using/ building SCSS files, however Nimble's design tokens can be used as CSS variables (`var(--ni-nimble-...)`) in Blazor apps without any additional work. +For a full list of supported variable names, see the [Nimble Storybook, "Tokens" >> "Theme-aware tokens"](https://nimble.ni.dev/storybook/?path=/story/tokens-theme-aware-tokens--theme-aware-tokens&args=propertyFormat:CSS). + +**Experimental: Manually including Nimble Tokens SCSS files** +There are currently extra manual steps required to use the Nimble design tokens as SCSS in Blazor projects (which results in better IntelliSense and compile-time checking for the Nimble tokens and variables): +1. Copy the Nimble tokens SCSS files into your Blazor project: Include `tokens.scss` and `tokens-internal.scss` from the `nimble-components` in your Blazor project directory. The simplest way to get these files is via `unpkg.com` (latest versions: [tokens.scss](https://unpkg.com/@ni/nimble-components/dist/tokens-internal.scss), [tokens-internal.scss](https://unpkg.com/@ni/nimble-components/dist/tokens-internal.scss)) +2. In `tokens.scss`, add a file extension to the `@import` statement at the top (`'./tokens-internal'` => `'./tokens-internal.scss'`) +3. Add a NuGet package reference to a SASS/SCSS compiler to your Blazor project. Both [LibSassBuilder](https://www.nuget.org/packages/LibSassBuilder) and [DartSassBuilder (latest/prerelease)](https://www.nuget.org/packages/DartSassBuilder) have been tested with Blazor projects and work with no additional configuration required. +4. Add new SCSS files for your Razor components (e.g. `MyComponent.razor.scss`), and `@import 'tokens.scss'` in it (updating the import relative path as needed). +5. Use the `$ni-nimble-...` variables in your Blazor application SCSS. + +The SCSS compilation happens before the rest of Blazor's compilation, so this approach works fine with Blazor CSS isolation. +Note: This approach requires periodically updating the Nimble tokens SCSS files manually (whenever the Nimble Blazor NuGet version is updated). + +### Localization (Optional) + +Most user-visible strings displayed by Nimble components are provided by the client application and are expected to be localized by the application if necessary. However, some strings are built into Nimble components and are provided only in English. + +To provide localized strings in a localized Blazor app: +1. Add the label providers as children of your ``: + - ``: Used for labels for all components besides the table + - ``: Used for labels for the table (and table sub-components / column types) +2. For each Nimble-provided label shown in the [Label Provider Storybook documentation](https://nimble.ni.dev/storybook/?path=/docs/tokens-label-providers--docs): + - Add a new entry for the label in a resource file (`.resx`). You can either add to an existing resx file, or create a new one just for the Nimble strings. The resource value should be the Nimble-provided English default string shown in Storybook. + - Follow [standard Blazor localization patterns](https://learn.microsoft.com/en-us/aspnet/core/blazor/globalization-localization) to localize the strings, and load the localized versions at runtime in your application. + - Provide Nimble the localized strings with the label provider APIs. For example, to provide the `popupDismiss` label on `NimbleLabelProviderCore`, if you load your string resources with a .NET `IStringLocalizer` instance, your label provider may look like the following: + ```xml + + ``` + +### Using Nimble Blazor in a Blazor Hybrid app + +There is currently an [issue in ASP.NET Core](https://github.com/dotnet/aspnetcore/issues/42349) that prevents the necessary JavaScript that Nimble Blazor relies on from loading in a Blazor Hybrid application. The Demo.Hybrid project illustrates the current required steps for getting Nimble Blazor to work properly. This simply involves adding the script `NimbleBlazor.HybridWorkaround.js` in the `index.html` file in `wwwroot`: + +wwwroot/index.html +```html + ... + + + + + +``` + +## Contributing + +Follow the instructions in [CONTRIBUTING.md](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md) to modify this library. diff --git a/packages/blazor-workspace/README.md b/packages/blazor-workspace/README.md index 55b39b9268..7bf51f1b69 100644 --- a/packages/blazor-workspace/README.md +++ b/packages/blazor-workspace/README.md @@ -1,161 +1,9 @@ -
-

ni | nimble | blazor

-
+# Blazor Workspace -# Nimble and Spright Blazor - -[![Nimble Nuget Version](https://img.shields.io/nuget/v/NimbleBlazor.svg)](https://www.nuget.org/packages/NimbleBlazor) -[![Spright Nuget Version](https://img.shields.io/nuget/v/SprightBlazor.svg)](https://www.nuget.org/packages/SprightBlazor) - -NI-styled UI components for Blazor applications - -This repo contains: -1. Blazor components and styles matching the NI brand. These are published as a Nuget package to be consumed by either Blazor WebAssembly or Blazor Server applications. +This workspace contains: +1. Blazor components and styles matching the NI brand. These are published as Nuget packages to be consumed by either Blazor WebAssembly or Blazor Server applications. + - `NimbleBlazor` contains general-purpose components + - `SprightBlazor` contains special-purpose or application-specific components 2. Three Blazor demo applications that consume the components: a Blazor WebAssembly application (`Demo.Client`), a Blazor Server application (`Demo.Server`), and a Blazor Hybrid application (`Demo.Hybrid`). -## Getting Started - -### Prerequisites - -1. IDE: - - **Windows with Visual Studio**: For Blazor development on Windows, the suggested IDE is: - - Visual Studio 2022 ([Enterprise, if available](https://my.visualstudio.com/Downloads?PId=8229)): Choose the "ASP.NET and Web Development" Workload in the installer - - Ensure Visual Studio is completely up to date (v17.1.6+): In Visual Studio click "Help" then "Check for Updates" - - **Mac with Visual Studio Code**: Install [Visual Studio Code](https://code.visualstudio.com/) and open it. Open the Extensions pane ("Preferences" >> "Extensions"), and search for / install the `ms-dotnettools.csharp` extension. -2. .NET SDK: See [the main contributing doc](/CONTRIBUTING.md) for the required version. - -### Creating a new Blazor project - -The built-in Blazor template projects are good starting points. First, decide whether to create a Blazor Server or Blazor Client/WebAssembly application (see the [Blazor hosting model documentation](https://docs.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0) for more information on both models). - -**Visual Studio**: Choose "New" >> "Project", and pick "Blazor Server app" or "Blazor WebAssembly app". -**VS Code**: Create a new folder, then open it in VS Code. Choose "View" >> "Terminal", and type `dotnet new blazorserver -f net6.0` (for Blazor Server) or `dotnet new blazorwasm -f net6.0` (for Blazor WebAssembly) and press Enter. Open the Command Palette ("View" >> "Command Palette" or Ctrl-Shift-P), enter ".NET Generate Assets for Build and Debug" and press Enter. - -Additional Resources: [Microsoft tutorial: Build a web app with Blazor](https://docs.microsoft.com/en-us/learn/modules/build-blazor-webassembly-visual-studio-code/); [`dotnet new` documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new) - -### Reference NimbleBlazor in a Blazor project - -1. Add a PackageReference to the NimbleBlazor NuGet package: - - Using the published NimbleBlazor NuGet package (recommended) - - Visual Studio: "Project" >> "Manage NuGet Packages", pick "nuget.org" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button. - - VS Code: Run the command `dotnet add package NimbleBlazor --source https://api.nuget.org/v3/index.json --prerelease` in the Terminal window. - - For Nimble developers, with a locally built NimbleBlazor NuGet (built from the Nimble repo): - - Run `npm run build`, and then `npm run pack -w @ni/nimble-blazor` from the root of the Nimble repo - - Visual Studio: "Project" >> "Manage NuGet Packages". Click the gear/Settings button. Add a new Package Source ("NimbleBlazor") as `[NimbleRepoDirectory]\packages\nimble-blazor\dist` and commit/ close Settings. Pick "NimbleBlazor" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button. - - VS Code: Run the command `dotnet add package NimbleBlazor --source [NimbleRepoDirectory]\packages\nimble-blazor\dist` in the Terminal window. -2. Add required references to Blazor code - - Open `_Imports.razor`, and add a new line at the bottom: `@using NimbleBlazor` - - Open `_Layout.cshtml` (BlazorServer) / `wwwroot/index.html` (Blazor WebAssembly). - At the bottom of the `` section (right before ``), add - ```html - - ``` - At the bottom of the `` section (right before ``), add - ```html - - ``` - -Additional Resources: [`dotnet add package` documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package) - -### Use Nimble Blazor components - -For a simple modification to the Blazor template project: open `Index.razor` and add the following code at the bottom, to add a Nimble text field that updates when a Nimble button is clicked: -```cs - -Click Me -@code { - protected string ButtonClickStatus { get; set; } = string.Empty; - private int _buttonClickCount = 0; - - private void OnButtonClicked(MouseEventArgs args) - { - _buttonClickCount++; - ButtonClickStatus = $"Button Clicked {_buttonClickCount} times"; - } -} -``` - -To test out your changes, do "Debug" >> "Start without Debugging" in Visual Studio, or `dotnet watch run` in the VS Code Terminal. - -More complete examples can be found in the Demo.Client/Server example projects. - -#### NimbleTable usage - -The `NimbleTable` requires that its data be set via the `SetDataAsync` method. The appropriate place to call this method is either in the `OnAfterRenderAsync` override of the hosting component or after that method has been called for the first time. - -As the `NimbleTable` is generic a client must supply its generic type in the markup using the `TData` property syntax. The following code represents a typical usage of the `NimbleTable`: -```html - -@code { - private NimbleTable? _table; - private IEnumerable TableData { get; set; } = Enumerable.Empty(); - ... - public override async Task OnAfterRenderAsync(bool firstRender) - { - await base.OnAfterRenderAsync(firstRender); - await _table.SetDataAsync(TableData); // populate TableData before here - } - - public class MyRecordType - { - ... - } -} -``` - -For more information regarding the Blazor component lifecycle mechanisms (such as `OnAfterRenderAsync`), please consult the [Microsoft Blazor docs](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/lifecycle). - -### Theming and Design Tokens - -To use Nimble's theme-aware design tokens in a Blazor app, you should have a `` element as an ancestor to all of the Nimble components you use. The app's default layout (`MainLayout.razor` in the examples) is a good place to put the theme provider (as the root content of the page). - -#### Using Nimble Design Tokens (CSS/SCSS) - -Blazor doesn't have built-in support for using/ building SCSS files, however Nimble's design tokens can be used as CSS variables (`var(--ni-nimble-...)`) in Blazor apps without any additional work. -For a full list of supported variable names, see the [Nimble Storybook, "Tokens" >> "Theme-aware tokens"](https://nimble.ni.dev/storybook/?path=/story/tokens-theme-aware-tokens--theme-aware-tokens&args=propertyFormat:CSS). - -**Experimental: Manually including Nimble Tokens SCSS files** -There are currently extra manual steps required to use the Nimble design tokens as SCSS in Blazor projects (which results in better IntelliSense and compile-time checking for the Nimble tokens and variables): -1. Copy the Nimble tokens SCSS files into your Blazor project: Include `tokens.scss` and `tokens-internal.scss` from the `nimble-components` in your Blazor project directory. The simplest way to get these files is via `unpkg.com` (latest versions: [tokens.scss](https://unpkg.com/@ni/nimble-components/dist/tokens-internal.scss), [tokens-internal.scss](https://unpkg.com/@ni/nimble-components/dist/tokens-internal.scss)) -2. In `tokens.scss`, add a file extension to the `@import` statement at the top (`'./tokens-internal'` => `'./tokens-internal.scss'`) -3. Add a NuGet package reference to a SASS/SCSS compiler to your Blazor project. Both [LibSassBuilder](https://www.nuget.org/packages/LibSassBuilder) and [DartSassBuilder (latest/prerelease)](https://www.nuget.org/packages/DartSassBuilder) have been tested with Blazor projects and work with no additional configuration required. -4. Add new SCSS files for your Razor components (e.g. `MyComponent.razor.scss`), and `@import 'tokens.scss'` in it (updating the import relative path as needed). -5. Use the `$ni-nimble-...` variables in your Blazor application SCSS. - -The SCSS compilation happens before the rest of Blazor's compilation, so this approach works fine with Blazor CSS isolation. -Note: This approach requires periodically updating the Nimble tokens SCSS files manually (whenever the Nimble Blazor NuGet version is updated). - -### Localization (Optional) - -Most user-visible strings displayed by Nimble components are provided by the client application and are expected to be localized by the application if necessary. However, some strings are built into Nimble components and are provided only in English. - -To provide localized strings in a localized Blazor app: -1. Add the label providers as children of your ``: - - ``: Used for labels for all components besides the table - - ``: Used for labels for the table (and table sub-components / column types) -2. For each Nimble-provided label shown in the [Label Provider Storybook documentation](https://nimble.ni.dev/storybook/?path=/docs/tokens-label-providers--docs): - - Add a new entry for the label in a resource file (`.resx`). You can either add to an existing resx file, or create a new one just for the Nimble strings. The resource value should be the Nimble-provided English default string shown in Storybook. - - Follow [standard Blazor localization patterns](https://learn.microsoft.com/en-us/aspnet/core/blazor/globalization-localization) to localize the strings, and load the localized versions at runtime in your application. - - Provide Nimble the localized strings with the label provider APIs. For example, to provide the `popupDismiss` label on `NimbleLabelProviderCore`, if you load your string resources with a .NET `IStringLocalizer` instance, your label provider may look like the following: - ```xml - - ``` - -### Using Nimble Blazor in a Blazor Hybrid app - -There is currently an [issue in ASP.NET Core](https://github.com/dotnet/aspnetcore/issues/42349) that prevents the necessary JavaScript that Nimble Blazor relies on from loading in a Blazor Hybrid application. The Demo.Hybrid project illustrates the current required steps for getting Nimble Blazor to work properly. This simply involves adding the script `NimbleBlazor.HybridWorkaround.js` in the `index.html` file in `wwwroot`: - -wwwroot/index.html -```html - ... - - - - - -``` - -## Contributing - -Follow the instructions in [CONTRIBUTING.md](/packages/nimble-blazor/CONTRIBUTING.md) to modify this library. +Refer to the `README.md` files in the individual project directories for more details. diff --git a/packages/blazor-workspace/SprightBlazor/CONTRIBUTING.md b/packages/blazor-workspace/SprightBlazor/CONTRIBUTING.md new file mode 100644 index 0000000000..32395b36ca --- /dev/null +++ b/packages/blazor-workspace/SprightBlazor/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing to Spright Blazor + +Contributions should follow the equivalent patterns and guidelines as for Nimble Blazor, so refer to that [CONTRIBUTING.md](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md) document. Any differences are listed below. \ No newline at end of file diff --git a/packages/blazor-workspace/SprightBlazor/README.md b/packages/blazor-workspace/SprightBlazor/README.md new file mode 100644 index 0000000000..5e6aab8229 --- /dev/null +++ b/packages/blazor-workspace/SprightBlazor/README.md @@ -0,0 +1,41 @@ +# Spright Blazor + +[![Spright Nuget Version](https://img.shields.io/nuget/v/SprightBlazor.svg)](https://www.nuget.org/packages/SprightBlazor) + +Spright Blazor generally works equivalently to Nimble Blazor, so refer to the Nimble Blazor [README.md](/packages/blazor-workspace/NimbleBlazor/README.md). Any Spright-specific differences are listed below. + +## Getting Started + +Any project using SprightBlazor components will typically also be using NimbleBlazor components (e.g. `NimbleThemeProvider` if nothing else). SprightBlazor is not a superset of NimbleBlazor, but the `spright-components` bundle _is_ a superset of the `nimble-components` bundle. Follow the directions below to avoid issues: + +- Add references to **both** the SprightBlazor and NimbleBlazor NuGet packages in your project + +- Include **only** the Spright all-components bundle in `_Layout.cshtml` (for BlazorServer) or `wwwroot/index.html` (for Blazor WebAssembly): + + ```html + + ... + + + + ``` + +### In a Blazor Hybrid app + +- Include **both** `SprightBlazor.HybridWorkaround.js` and `NimbleBlazor.HybridWorkaround.js` in `wwwroot/index.html`: + + ```html + + ... + + + + + + + ``` + +## Contributing + +Follow the instructions in [CONTRIBUTING.md](/packages/blazor-workspace/SprightBlazor/CONTRIBUTING.md) to modify this library. diff --git a/packages/blazor-workspace/SprightBlazor/SprightBlazor.csproj b/packages/blazor-workspace/SprightBlazor/SprightBlazor.csproj index c4a796c7f2..ae8164c97b 100644 --- a/packages/blazor-workspace/SprightBlazor/SprightBlazor.csproj +++ b/packages/blazor-workspace/SprightBlazor/SprightBlazor.csproj @@ -6,6 +6,7 @@ enable embedded NI + README.md https://github.com/ni/nimble https://github.com/ni/nimble git @@ -57,6 +58,7 @@ + diff --git a/packages/nimble-components/README.md b/packages/nimble-components/README.md index 2ea97b4eaa..e077842749 100644 --- a/packages/nimble-components/README.md +++ b/packages/nimble-components/README.md @@ -15,7 +15,7 @@ NI-styled web components for web applications. If you are using one of the following frameworks see associated wrapper documentation: 1. Angular: See the [nimble-angular](/packages/angular-workspace/nimble-angular) documentation. -2. Blazor WebAssembly or Blazor Server: See the [nimble-blazor](/packages/nimble-blazor) documentation. +2. Blazor WebAssembly or Blazor Server: See the [nimble-blazor](/packages/blazor-workspace/NimbleBlazor) documentation. ### Using in a Webpack Application diff --git a/packages/nimble-tokens/README.md b/packages/nimble-tokens/README.md index 6486f472d2..7cccd8aad6 100644 --- a/packages/nimble-tokens/README.md +++ b/packages/nimble-tokens/README.md @@ -14,7 +14,7 @@ NI base design tokens. Design tokens are primitive elements of component style l If you are using one of the following frameworks you should consume tokens via components implemented in the following libraries. These libraries provide styled components that use the design tokens to implement several color themes. 1. Angular: See the [nimble-angular](/packages/angular-workspace/nimble-angular) documentation. -2. Blazor WebAssembly or Blazor Server: See the [nimble-blazor](/packages/nimble-blazor) documentation. +2. Blazor WebAssembly or Blazor Server: See the [nimble-blazor](/packages/blazor-workspace/NimbleBlazor) documentation. 3. Vanilla / Frameworkless: See the [nimble-components](/packages/nimble-components) documentation. ## Using Theme-Aware Tokens diff --git a/specs/templates/custom-component.md b/specs/templates/custom-component.md index dee58d9827..069d11f7f8 100644 --- a/specs/templates/custom-component.md +++ b/specs/templates/custom-component.md @@ -77,7 +77,7 @@ ### Blazor integration -*Describe the plan for Blazor support, including form integration. See the [nimble-blazor CONTRIBUTING.md](/packages/nimble-blazor/CONTRIBUTING.md) for details. Depending on the contributor's needs, implementing Blazor integration may be deferred but the initial spec should still document what work will be needed.* +*Describe the plan for Blazor support, including form integration. See the [nimble-blazor CONTRIBUTING.md](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md) for details. Depending on the contributor's needs, implementing Blazor integration may be deferred but the initial spec should still document what work will be needed.* ### Visual Appearance diff --git a/specs/templates/fast-based-component.md b/specs/templates/fast-based-component.md index 3bd79913da..5f088f485d 100644 --- a/specs/templates/fast-based-component.md +++ b/specs/templates/fast-based-component.md @@ -45,7 +45,7 @@ ### Blazor integration -*Describe the plan for Blazor support, including form integration. See the [nimble-blazor CONTRIBUTING.md](/packages/nimble-blazor/CONTRIBUTING.md) for details. Depending on the contributor's needs, implementing Blazor integration may be deferred but the initial spec should still document what work will be needed.* +*Describe the plan for Blazor support, including form integration. See the [nimble-blazor CONTRIBUTING.md](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md) for details. Depending on the contributor's needs, implementing Blazor integration may be deferred but the initial spec should still document what work will be needed.* ### Additional requirements