From 32ee70c7dddde84bc56b516a504caa9f35158bef Mon Sep 17 00:00:00 2001 From: Sorita Heng <69398037+soritaheng@users.noreply.github.com> Date: Wed, 14 May 2025 21:32:17 +1000 Subject: [PATCH] DOC-3186: Update Blazor public documentation (#3724) * Update Blazor Tiny Cloud page * Add instructions for VS Code * Update quick start content structure and add Zip instruction * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Update modules/ROOT/partials/integrations/blazor-quick-start.adoc Co-authored-by: Karl Kemister-Sheppard * Add 'link:' prefix to hyperlinks * Add step to include either the API key or License Key based on product source * Update modules/ROOT/partials/integrations/blazor-postinstall.adoc * Update modules/ROOT/partials/integrations/blazor-postinstall.adoc * DOC-3186: replace your-api-key with no-api-key. * Fix missing tag in example code --------- Co-authored-by: Sorita Heng Co-authored-by: Karl Kemister-Sheppard --- .../integrations/blazor-postinstall.adoc | 71 ++++++++++++++++--- .../integrations/blazor-quick-start.adoc | 57 ++++++++++++--- .../integrations/blazor-tech-ref.adoc | 4 +- 3 files changed, 109 insertions(+), 23 deletions(-) diff --git a/modules/ROOT/partials/integrations/blazor-postinstall.adoc b/modules/ROOT/partials/integrations/blazor-postinstall.adoc index ff54231f2..212562fea 100644 --- a/modules/ROOT/partials/integrations/blazor-postinstall.adoc +++ b/modules/ROOT/partials/integrations/blazor-postinstall.adoc @@ -1,6 +1,4 @@ -. Verify the installation by checking the `+ItemGroup+` references in `+BlazorApp.csproj+`, such as: -+ -_File:_ `+BlazorApp.csproj+` +. Verify the installation by checking the `+ItemGroup+` references in the project file. For example, if the project is named _BlazorApp_, the relevant file would be `+BlazorApp.csproj+` with the dependency referenced as follows: + [source,xml] ---- @@ -8,30 +6,59 @@ _File:_ `+BlazorApp.csproj+` ---- -. Add the `+tinymce-blazor.js+` script to the main page. -* Using Blazor Server add the script in `+Pages/_Host.cshtml+`, for example: +. Add the `+tinymce-blazor.js+` script to the main page. If using the Blazor Web App, add the script in `+Components/App.razor+`, for example: ++ +[source,html] +---- + + +---- ++ +[NOTE] +==== +The location of the script depends on the type of Blazor app, including Blazor Server and Blazor WebAssembly (WASM) which are not covered in this guide. + +* If using Blazor Server, add the script in `+Pages/_Host.cshtml+`, for example: + [source,html] ---- ---- -* Using WASM add the script in `+wwwroot/index.html+`, for example: +* If using WASM, add the script in `+wwwroot/index.html+`, for example: + [source,html] ---- ---- -. Add the `+Editor+` component to a page by either: -* Using the `+using+` directive +==== ++ + +. Add the `+Editor+` component to a page by either: +* Using the `+using+` directive: + [source,cs] ---- @using TinyMCE.Blazor ---- -* Using the full component and package name ++ +For example: ++ +_File:_ `+Pages/Index.razor+` ++ +[source,cs] +---- +@page "/" +@rendermode InteractiveServer +@using TinyMCE.Blazor + +

Hello, world!

+

Welcome to your new app.

+ +---- +* Using the component with its namespace: + [source,cs] ---- @@ -45,14 +72,38 @@ _File:_ `+Pages/Index.razor+` [source,cs] ---- @page "/" +@rendermode InteractiveServer @using TinyMCE.Blazor

Hello, world!

-Welcome to your new app. +

Welcome to your new app.

+---- ++ +[IMPORTANT] +In a Blazor Web App, different render modes determine how components are rendered and how interactivity is handled. To enable JavaScript interactivity, ensure that `+@rendermode InteractiveServer+` is specified in a page component. ++ + +ifeval::["{productSource}" == "cloud"] +. Update the `+ApiKey+` option in the editor element and include your link:{accountsignup}/[{cloudname} API key]. + ++ +[source,cs] ---- + +---- ++ +endif::[] ifeval::["{productSource}" != "cloud"] +. Update the `+LicenseKey+` option in the editor element and include your xref:license-key.adoc[License Key]. + ++ +[source,cs] +---- + +---- ++ . To load {productname} from the self-hosted package instead of the {cloudname}, configure the `+ScriptSrc+` property: + diff --git a/modules/ROOT/partials/integrations/blazor-quick-start.adoc b/modules/ROOT/partials/integrations/blazor-quick-start.adoc index a9810722d..8532fc562 100644 --- a/modules/ROOT/partials/integrations/blazor-quick-start.adoc +++ b/modules/ROOT/partials/integrations/blazor-quick-start.adoc @@ -1,10 +1,35 @@ -The https://github.com/tinymce/tinymce-blazor[Official {productname} Blazor component] integrates {productname} into https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor[Blazor applications]. This procedure creates a basic Blazor application and adds a {productname} editor using the {productname} Blazor integration. The basic Blazor application is based on the following tutorial: https://dotnet.microsoft.com/learn/aspnet/blazor-tutorial/[Microsoft .NET Blazor Tutorial - Build your first Blazor app]. +The link:https://github.com/tinymce/tinymce-blazor[Official {productname} Blazor component^] integrates {productname} into link:https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor[Blazor applications^]. This procedure creates a basic Blazor application and adds a {productname} editor using the {productname} Blazor integration. The basic Blazor application is based on the following tutorial: link:https://dotnet.microsoft.com/learn/aspnet/blazor-tutorial/[Microsoft .NET Blazor Tutorial - Build your first Blazor app^]. Select from the following guides: +* xref:using-visual-studio-code[Using Visual Studio Code (VS Code)] * xref:using-visual-studio[Using Visual Studio] * xref:using-a-command-prompt-or-terminal[Using a command prompt or terminal] +[[using-visual-studio-code]] +== Using Visual Studio Code (VS Code) + +=== Prerequisites + +This procedure requires: + +* link:https://code.visualstudio.com/[Visual Studio Code (VS Code)^] +* link:https://dotnet.microsoft.com/en-us/download[.NET SDK^] +* link:https://learn.microsoft.com/en-us/visualstudio/subscriptions/vs-c-sharp-dev-kit[C# Dev Kit VS Code Extension^] + +Alternatively, the link:https://learn.microsoft.com/en-us/dotnet/core/install/windows#install-with-visual-studio-code[.NET WinGet Configuration file^] can be downloaded to install the necessary dependencies. + +=== Procedure + +. In VS Code, open the Command Palette by pressing `+Ctrl+Shift+P+`. Find `.NET: New Project` and select it to create a new project. +. Select *Blazor Web App* from the list of templates and follow the steps to set up the project. +. Using the Command Palette, find and select `.NuGet: Add NuGet Package`. Enter `+TinyMCE.Blazor+` and select the package along with the version to install. + +ifeval::["{productSource}" == "package-manager"] + +. To use the self-hosted version of `{productname}`, install the `{productname}` package from the Command Pallette. +endif::[] + [[using-visual-studio]] == Using Visual Studio @@ -12,13 +37,13 @@ Select from the following guides: This procedure requires: -* https://docs.microsoft.com/en-us/visualstudio/windows/[Microsoft Visual Studio] -* https://docs.microsoft.com/en-us/dotnet/core/install/[Microsoft .NET] +* link:https://docs.microsoft.com/en-us/visualstudio/windows/[Microsoft Visual Studio^] +* link:https://docs.microsoft.com/en-us/dotnet/core/install/[Microsoft .NET^] === Procedure -. On the Visual Studio toolbar, click the https://docs.microsoft.com/en-us/visualstudio/ide/create-new-project[*New Project* button]. -. Select the *Blazor Server App* template. +. On the Visual Studio toolbar, click the link:https://docs.microsoft.com/en-us/visualstudio/ide/create-new-project[*New Project* button^]. +. Select the *Blazor Web App* template and follow the steps to set up the project. . Use the NuGet package manager console to install the `+TinyMCE.Blazor+` package, such as: + [source,sh] @@ -36,9 +61,8 @@ Install-Package TinyMCE ---- endif::[] -include::partial$integrations/blazor-postinstall.adoc[] -. To test the application, run the application by pressing *Ctrl+F5*. +. To test the application, run the application by pressing `+Ctrl+F5+`. [[using-a-command-prompt-or-terminal]] == Using a command prompt or terminal @@ -47,7 +71,7 @@ include::partial$integrations/blazor-postinstall.adoc[] This procedure requires: -* https://docs.microsoft.com/en-us/dotnet/core/install/[Microsoft .NET] +* link:https://docs.microsoft.com/en-us/dotnet/core/install/[Microsoft .NET^] === Procedure @@ -55,7 +79,7 @@ This procedure requires: + [source,sh] ---- -dotnet new blazorserver -o BlazorApp --no-https +dotnet new blazor -o BlazorApp --no-https ---- . Change into the new application directory: + @@ -80,7 +104,6 @@ dotnet add package TinyMCE ---- endif::[] -include::partial$integrations/blazor-postinstall.adoc[] . Test the application using the .NET development server. * To start the development server, in the project's root directory, run: @@ -90,9 +113,21 @@ include::partial$integrations/blazor-postinstall.adoc[] dotnet watch run ---- + -This will start a local development server, accessible at http://localhost:5000. +This will start a local development server accessible at `http://localhost:{PORT}`, where `{PORT}` is specified in the project's `+Properties/launchSettings.json+` file. * To stop the development server, select on the command line or command prompt and press _Ctrl+C_. + +ifeval::["{productSource}" == "zip"] + +== Download {productname} Zip + +To use the self-hosted version of `{productname}`, download the link:https://www.tiny.cloud/my-account/downloads/[{productname} zip^]. Unzip the content and place it in the project, such as in the `+wwwroot+` folder for storing public static assets. +endif::[] + +== Post-installation + +include::partial$integrations/blazor-postinstall.adoc[] + == Next Steps For information on customizing the integration, see: diff --git a/modules/ROOT/partials/integrations/blazor-tech-ref.adoc b/modules/ROOT/partials/integrations/blazor-tech-ref.adoc index d42c495e8..9022dea6e 100644 --- a/modules/ROOT/partials/integrations/blazor-tech-ref.adoc +++ b/modules/ROOT/partials/integrations/blazor-tech-ref.adoc @@ -18,7 +18,7 @@ The `+TinyMCE.Blazor+` `+Editor+` component accepts the following properties: Disable=false JsConfSrc="path_to_jsObj" Conf="@yourConf" - ApiKey="your-api-key" + ApiKey="no-api-key" LicenseKey="your-license-key" ScriptSrc="/path/to/tinymce.min.js" ClassName="tinymce-wrapper" @@ -40,7 +40,7 @@ None of the configuration properties are required for the TinyMCE Blazor integra [source,cs] ---- ----