Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 21 additions & 123 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,145 +1,43 @@
# ToastUI Editor Blazor [![NuGet](https://img.shields.io/nuget/v/ToastUIEditor.svg)](https://www.nuget.org/packages/ToastUIEditor/)

`tui.editor.blazor` is a Blazor component that provides a Markdown editor based on the [tui.editor](https://github.com/nhn/tui.editor) library.

Supports .NET 9 and .NET 10 for Blazor Server and Blazor WebAssembly applications.

## Development

```shell
dotnet build ToastUIEditor.sln --configuration Release
dotnet test tests/ToastUIEditor.Tests/ToastUIEditor.Tests.csproj --configuration Release
```

Packages are built automatically by GitHub Actions for pushes and pull requests. A NuGet
publication can be triggered by publishing a GitHub Release (the tag is used as the package
version) or manually from the `Publish NuGet Package` workflow. The repository must have a
`NUGET_API_KEY` secret configured for publishing.
English | [简体中文](README.zh-CN.md)

`tui.editor.blazor` is a Blazor wrapper for the [Toast UI Editor](https://github.com/nhn/tui.editor).
It supports Blazor Server and Blazor WebAssembly on .NET 6, .NET 7, .NET 8, .NET 9, and .NET 10.

## Installation

Install the package using following command:

``` Package Manager
Install-Package ToastUIEditor
```

or

``` powershell
```shell
dotnet add package ToastUIEditor
```

or just use nuget package manager.


## Usage

1. Add the following import statement to your `_Imports.razor` file

``` razor
@using ToastUI
```


2. Use the `Editor` component in your Blazor page or component

``` razor
<Editor @bind-Value="content" Options="@options" />
```

- `@bind-Value`: Binds the editor's content to a string property in your Blazor component.
- `Options`: Sets the configuration options for the editor. Refer to the `EditorOptions` class for available options.


3. Use the `Viewer` component in your Blazor page or component

``` razor
<Viewer Value="@content" />
```

- `Value`: Sets the content to be displayed in the viewer. It will update automatically when `content` changes.


4. Handle the available events by specifying event callbacks

``` razor
<Editor @bind-Value="content"
Load="HandleLoad"
Change="HandleChange"
CaretChange="HandleCaretChange"
Focus="HandleFocus"
Blur="HandleBlur"
KeyDown="HandleKeyDown"
KeyUp="HandleKeyUp"
BeforePreviewRender="HandleBeforePreviewRender"
BeforeConvertWYSIWYGToMarkdown="HandleBeforeConvertWYSIWYGToMarkdown" />

<Viewer Value="content"
Load="HandleLoad"
UpdatePreview="HandleUpdatePreview" />
```

These events are the same as the native public events, and the parameters are detailed in the code comments.


5. Access the `Editor` or `Viewer` instance to invoke methods

``` razor
<Editor @ref="editorRef" @bind-Value="markdown" Options="@options" />

<Viewer @ref="viewerRef" Value="markdown" />
## Quick start

<button @onclick="HandlePreview">Preview</button>
Add `@using ToastUI` to `_Imports.razor`:

<Viewer @ref="viewerRef2"/>
```razor
<Editor @bind-Value="content" Options="options" />
<Viewer Value="content" />

@code {
Editor editorRef = default!;
Viewer viewerRef = default!;
Viewer viewerRef2 = default!;
string markdown = string.Empty;

async Task HandlePreview()
{
var markdown = await editorRef.GetMarkdown();
await viewerRef2.SetMarkdown(markdown);
}
private string content = "# Hello, Toast UI!";
private EditorOptions options = new();
}
```

Most of all native methods have been implemented. Refer to the Editor class for available methods.
The components expose editor/viewer events and methods through `@ref`. See the package README for
a concise API example and the source code XML documentation for the complete API.

## Development

6. Add custom language

- Use `Editor.SetLanguage` static method to add custom language.
- Use `Editor.SetDefaultLanguage` static method to set default language, it will be used when no language is set in `EditorOptions`.

> Note: Please make sure Editor.SetLanguage and Editor.SetDefaultLanguage are called before `Editor` component is rendered.


7. Widget rules

Due to `BlazorServer` mode not supporting JavaScript call .NET method synchronously, the widget rules only support in `BlazorWebAssembly` mode.


## Implemented Features

- [x] `Editor` and `Viewer` basic usage
- [x] `Editor` and `Viewer` events
- [x] Language setting and custom language
- [x] `Editor` and `Viewer` instance methods
- [ ] Toolbar with custom button
- [ ] Add command and execute command
- [x] Add widget and set widget rules (only support in `BlazorWebAssembly` mode)
- [x] Link attributes
- [ ] Custom markdown renderer
- [ ] Custom HTML renderer
- [ ] Custom HTML Sanitizer
```shell
dotnet build ToastUIEditor.sln --configuration Release
dotnet test tests/ToastUIEditor.Tests/ToastUIEditor.Tests.csproj --configuration Release
```

GitHub Actions build and test pull requests. Publishing a GitHub Release or manually dispatching
the publish workflow creates and publishes the NuGet package.

## License

This software is licensed under the [MIT License](LICENSE)
This project is licensed under the [MIT License](LICENSE).
58 changes: 58 additions & 0 deletions README.nuget.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# ToastUI Editor Blazor

English | [简体中文](README.nuget.zh-CN.md)

`ToastUIEditor` provides Toast UI Editor components for Blazor Server and Blazor WebAssembly.
It supports .NET 6, .NET 7, .NET 8, .NET 9, and .NET 10.

## Installation

```shell
dotnet add package ToastUIEditor
```

## Quick start

Add `@using ToastUI` to `_Imports.razor`, then use the editor or viewer:

```razor
<Editor @bind-Value="content" Options="options" />
<Viewer Value="content" />

@code {
private string content = "# Hello, Toast UI!";
private EditorOptions options = new();
}
```

Use `@ref` to access component methods such as `GetMarkdown`, `SetMarkdown`, and `GetHTML`.
See the [repository README](https://github.com/ling921/tui.editor.blazor) for complete usage,
events, languages, and widget rules.

## 简体中文

`ToastUIEditor` 为 Blazor Server 和 Blazor WebAssembly 提供 Toast UI Editor 组件,支持
.NET 6、.NET 7、.NET 8、.NET 9 和 .NET 10。

### 安装

```shell
dotnet add package ToastUIEditor
```

### 快速开始

在 `_Imports.razor` 中添加 `@using ToastUI`,然后使用编辑器或查看器:

```razor
<Editor @bind-Value="content" Options="options" />
<Viewer Value="content" />

@code {
private string content = "# 你好,Toast UI!";
private EditorOptions options = new();
}
```

可以通过 `@ref` 调用 `GetMarkdown`、`SetMarkdown` 和 `GetHTML` 等组件方法。完整用法请
参考[仓库 README](https://github.com/ling921/tui.editor.blazor)。
29 changes: 29 additions & 0 deletions README.nuget.zh-CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# ToastUI Editor Blazor

English | 简体中文

`ToastUIEditor` 为 Blazor Server 和 Blazor WebAssembly 提供 Toast UI Editor 组件,支持
.NET 6、.NET 7、.NET 8、.NET 9 和 .NET 10。

## 安装

```shell
dotnet add package ToastUIEditor
```

## 快速开始

在 `_Imports.razor` 中添加 `@using ToastUI`,然后使用 `<Editor>` 或 `<Viewer>` 组件:

```razor
<Editor @bind-Value="content" Options="options" />
<Viewer Value="content" />

@code {
private string content = "# 你好,Toast UI!";
private EditorOptions options = new();
}
```

可以通过 `@ref` 调用 `GetMarkdown`、`SetMarkdown` 和 `GetHTML` 等方法。更多事件、语言和
Widget Rule 用法,请参考[仓库 README](https://github.com/ling921/tui.editor.blazor)。
41 changes: 41 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# ToastUI Editor Blazor

English | 简体中文

`tui.editor.blazor` 是 [Toast UI Editor](https://github.com/nhn/tui.editor) 的 Blazor 封装,
支持 Blazor Server 和 Blazor WebAssembly,目标框架包括 .NET 6、.NET 7、.NET 8、.NET 9 和 .NET 10。

## 安装

```shell
dotnet add package ToastUIEditor
```

## 快速开始

在 `_Imports.razor` 中添加 `@using ToastUI`:

```razor
<Editor @bind-Value="content" Options="options" />
<Viewer Value="content" />

@code {
private string content = "# 你好,Toast UI!";
private EditorOptions options = new();
}
```

组件支持通过 `@ref` 访问编辑器/查看器事件和方法。更多 API 请查看 NuGet 包说明和源码中的 XML 文档。

## 开发

```shell
dotnet build ToastUIEditor.sln --configuration Release
dotnet test tests/ToastUIEditor.Tests/ToastUIEditor.Tests.csproj --configuration Release
```

GitHub Actions 会构建和测试 Pull Request;发布 GitHub Release 或手动运行发布工作流即可创建并发布 NuGet 包。

## 许可证

本项目采用 [MIT 许可证](LICENSE)。
Loading
Loading