Tavenem.Wiki.Blazor.Shared
0.7.0-preview
Prefix Reserved
The features of this package are now directly provided by the Client and Server packages
See the version list below for details.
dotnet add package Tavenem.Wiki.Blazor.Shared --version 0.7.0-preview
NuGet\Install-Package Tavenem.Wiki.Blazor.Shared -Version 0.7.0-preview
<PackageReference Include="Tavenem.Wiki.Blazor.Shared" Version="0.7.0-preview" />
paket add Tavenem.Wiki.Blazor.Shared --version 0.7.0-preview
#r "nuget: Tavenem.Wiki.Blazor.Shared, 0.7.0-preview"
// Install Tavenem.Wiki.Blazor.Shared as a Cake Addin #addin nuget:?package=Tavenem.Wiki.Blazor.Shared&version=0.7.0-preview&prerelease // Install Tavenem.Wiki.Blazor.Shared as a Cake Tool #tool nuget:?package=Tavenem.Wiki.Blazor.Shared&version=0.7.0-preview&prerelease
Tavenem.Wiki.Blazor
This is an implementation of Tavenem.Wiki for Blazor. It is comprised of a pair of Razor class libraries: a Client library which can be included in a Blazor client app, and a Server library which can be included in an ASP.NET Core host project. Working together, this hosted Blazor project will function as a complete wiki.
It is also possible to use only the client library, and provide your own implementation for the server library. Its source code could easily be adapted to integrate more closely with your main server project, or reimagined as a cloud-native set of functions and APIs, or replaced by any number of other implementations.
It is also possible to use the client library "offline" by providing direct access to wiki data, without the need for any back-end at all. Data might be persisted locally on the client in browser storage, or the local filesystem.
Installation
Tavenem.Wiki.Blazor is available as a pair of NuGet packages: one for the client library, and one for the server library.
The client package should be installed in your Blazor client app, and the server library can optionally be installed in your host app.
Configuration
In order to use Tavenem.Wiki.Blazor, the following steps should be taken:
The Client App
Call one of the overloads of
AddWikiClient
on anIServiceCollection
instance in yourProgram.cs
file.For example:
var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.Services.AddWikiClient();
AddWikiClient
has three optional parameters.The first parameter is either an instance of
WikiOptions
or a function which provides one. This interface allows you to configure the wiki's core features. See the README for Tavenem.Wiki for more information.The second parameter is either an instance of
WikiBlazorClientOptions
or a function which provides one. This interface allows you to configure the wiki's Blazor implementation features, and includes the following properties:AppBar
: The type of an optional component (typically containing an AppBar from the Tavenem Blazor Framework) which will appear at the top of wiki pages.AppBarRenderMode
: The render mode to use for theAppBar
component, ornull
to use static rendering.The type must implement
IComponent
.ArticleFrontMatter
andArticleEndMatter
: these can be set to functions which accept anArticle
parameter and should return type of a component which should be displayed before or after the content of the given wiki article (before the category list), or null if no additional component should be displayed.ArticleFrontMatterRenderMode
andArticleEndMatterRenderMode
: The render mode to use for theArticleFrontMatter
andArticleEndMatter
components, ornull
to use static rendering.CanEditOffline
: Can be set to a function which determines whether content may be edited locally.If this function is not defined, no content may be edited locally (i.e. local content may only be viewed).
CompactLayout
: The type of layout used when requesting a compact version of a wiki page. Wiki pages will be nested within this layout.If omitted, a default layout will be used.
CompactRouteHostPart
: The host part which will be recognized as indicating a request for the compact version of the wiki.If left empty the compact view cannot be reached at a particular host path.
CompactRouteHostPosition
: The position (zero-based) within the parts of the host string which will be examined to determine a request for the compact version of the wiki.If left null position zero will be assumed.
Only used when
CompactRouteHostPart
is non-empty.CompactRoutePort
: The port which will be recognized as indicating a request for the compact version of the wiki.If left null the compact view cannot be reached at a particular port.
DataStore
: An optional data store which the client can access directly (i.e. without reaching the server).If the
WikiServerApiRoute
has also been defined, the client will try to reach the server first for all wiki operations. If the server cannot be reached or the requested content is unavailable at the server, the client will fall back to the local data store.If both the server and the local data store are unavailable, the wiki will remain operational, but will show no content and will not allow any content to be added.
No automatic synchronization occurs from the local data store to the server (for instance when an offline client reestablishes network connectivity). If your app model requires synchronization of offline content to a server, that logic must be implemented separately.
IsOfflineDomain
: A function which determines whether the given domain should always be retrieved from the localDataStore
, and never from theWikiServerApiRoute
.LoginPath
: The relative path to the site's login page.For security reasons, only a local path is permitted. If your authentication mechanisms are handled externally, this should point to a local page which redirects to that source (either automatically or via interaction).
A query parameter with the name "returnUrl" whose value is set to the page which initiated the logic request will be appended to this URL (if provided). Your login page may ignore this parameter, but to improve user experience it should redirect the user back to this URL after performing a successful login. Be sure to validate that the value of the parameter is from a legitimate source to avoid exploits.
If this option is omitted, a generic "not signed in" message will be displayed whenever a user who is not logged in attempts any action which requires an account.
MainLayout
: The type of the main layout for the wiki. Wiki pages will be nested within this layout.If omitted, a default layout will be used.
TenorAPIKey
: The API key to be used for Tenor GIF integration. If omitted, discussion pages will not have built-in GIF functionality.WikiServerApiRoute
: The relative URL of the wiki's server API.This is initialized to <see langword="null"/> by default,
WikiBlazorClientOptions.DefaultWikiServerApiRoute
may be assigned to use the default value for a hosting server app with default values.
The third parameter to
AddWikiClient
is either an instance ofISearchClient
, theType
of an implementation, or a function which provides one. This service provides search capabilities when using the local data source. If omitted, an instance ofDefaultSearchClient
will be used.Note: the
DefaultSearchClient
is not recommended for production use. It is provided only to ensure that basic search functionality operates when an implementation ofISearchClient
is not available (e.g. during debugging if the production client cannot be used during development).Add a page with the following content to your client:
@page "/wiki/{*route}" <Wiki /> @code { [Parameter] public string? Route { get; set; } }
Replace "wiki" in the page route with your preferred wiki route prefix (which should match what your configure in your
WikiOptions
instance).This page will handle requests for wiki pages.
(Optional) In your main
App.razor
component, place aWiki
component in theNotFound
content slot of yourRouter
component. This will allow the wiki to handle requests for unrecognized routes (i.e. users who do not add your wiki prefix to a typed URL will still get to the expected page). Routes which do not match wiki content will display an "article not found" wiki page.If you prefer not to handle unrecognized routes as requests for wiki pages, this step can be skipped.
The Server App
(Optional) Call
AddWikiJsonContext
on anIServiceCollection
instance in yourProgram.cs
file. This configures theJsonOptions
for MVC with theWikiBlazorJsonSerializerContext
andWikiJsonSerializerContext
source gererated serializer contexts.This is an optional step. If you wish to provide your own JSON serializer context, or use reflection-based JSON serialization, or use an alternative JSON serializer, you should skip this step.
If you will provide your own context, it is recommended that you combine it with
WikiBlazorJsonSerializerContext
andWikiJsonSerializerContext
viaJsonTypeInfoResolver.Combine
to ensure that all necessary wiki types are included.For example:
var resolver = JsonTypeInfoResolver.Combine( YourCustomContext.Default, WikiBlazorJsonSerializerContext.Default, WikiJsonSerializerContext.Default, new DefaultJsonTypeInfoResolver()); services.Configure<JsonOptions>(options => options.JsonSerializerOptions.TypeInfoResolver = resolver);
Call one of the overloads of
AddWikiServer
on anIServiceCollection
instance in yourProgram.cs
file.AddWikiServer
has two required parameters and four optional parameters.The first parameter is either an instance of
IWikiUserManager
, or the type of an implementation of that interface which is available via dependency injection, or a function which provides one. This interface allows the wiki to get information about users. Typically this will be a wrapper around your actual user persistence mechanism (e.g. ASP.NET Core Identity).The second parameter is either an instance of
IWikiGroupManager
, or the type of an implementation of that interface which is available via dependency injection, or a function which provides one. This interface allows the wiki to get information about user groups. Typically this will be a wrapper around your actual user group persistence mechanism.The next parameter is either an instance of
WikiOptions
or a function which provides one. This interface allows you to configure the wiki's core features. See the README for Tavenem.Wiki for more information.The next parameter is either an instance of
IWikiBlazorServerOptions
or a function which provides one. This interface allows you to configure the wiki's Blazor implementation features, and includes the following properties:DomainArchivePermission
: The minimum permission the user must have in order to create an archive of a domain.This property does not apply when creating an archive for content without a domain, or for the entire wiki.
Since it would be prohibitive to check individual pages' permission, archiving only requires that a user has this level of permission (defaults to Read) for the target domain. This could represent a potential security breach, if individual pages within the domain are further restricted. It is strongly recommended that the ability to create archives is restricted in your client code in a manner specific to your implementation's use of domains, which guarantees that only those with the correct permissions can create archives.
LoginPath
: The relative path to the site's login page.For security reasons, only a local path is permitted. If your authentication mechanisms are handled externally, this should point to a local page which redirects to that source (either automatically or via interaction).
A query parameter with the name "returnUrl" whose value is set to the page which initiated the logic request will be appended to this URL (if provided). Your login page may ignore this parameter, but to improve user experience it should redirect the user back to this URL after performing a successful login. Be sure to validate that the value of the parameter is from a legitimate source to avoid exploits.
If this option is omitted, a generic "not signed in" message will be displayed whenever a user who is not logged in attempts any action which requires an account.
WikiServerApiRoute
: The relative URL of the wiki's server API.If omitted, the path "/wikiapi" will be used.
The next parameter is either an instance of
IFileManager
, or the type of an implementation of that interface which is available via dependency injection, or a function which provides one. If omitted, an instance ofLocalFileManager
will be used, which stores files in a subfolder of wwwroot. Note that you can disable file uploads entirely inWikiOptions
.The next parameter is either an instance of
ISearchClient
, or the type of an implementation of that interface which is available via dependency injection, or a function which provides one. If omitted, an instance ofDefaultSearchClient
will be used.Note: the
DefaultSearchClient
is not recommended for production use. It is provided only to ensure that basic search functionality operates when an implementation ofISearchClient
is not available (e.g. during debugging if the production client cannot be used during development).Call
MapWiki
on anIEndpointRouteBuilder
instance in yourProgram.cs
file.For example:
var builder = WebAssemblyHostBuilder.CreateDefault(args); var app = builder.Build(); app.MapWiki();
This call should normally precede any other mapped endpoints.
It is possible to implement an authorization policy with the name "WikiPolicy" which will be applied to the built-in wiki controller. Note, however, that the
AllowAnonymous
attribute is applied to this controller. This means that while authentication will be performed according to the rules defined in the policy, access to the actions of the controller will not be denied on the basis of authorization.
Roadmap
Tavenem.Wiki.Blazor is currently in a prerelease state. Development is ongoing, and breaking changes are possible before the first production release.
No release date is currently set for v1.0 of Tavenem.Wiki.Blazor. The project is currently in a "wait and see" phase while Tavenem.DataStore (a dependency of Tavenem.Wiki.Blazor) is in prerelease. When that project has a stable release, a production release of Tavenem.Wiki.Blazor will follow.
Contributing
Contributions are always welcome. Please carefully read the contributing document to learn more before submitting issues or pull requests.
Code of conduct
Please read the code of conduct before engaging with our community, including but not limited to submitting or replying to an issue or pull request.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- Tavenem.Wiki (>= 0.24.0-preview)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated | |
---|---|---|---|
0.7.1-preview | 114 | 2/1/2024 | |
0.7.0-preview | 68 | 1/12/2024 | |
0.6.6-preview | 89 | 1/9/2024 | |
0.6.5-preview | 92 | 1/3/2024 | |
0.6.4-preview | 119 | 11/29/2023 | |
0.6.3-preview | 120 | 9/26/2023 | |
0.6.2-preview | 97 | 9/12/2023 | |
0.6.1-preview | 93 | 9/12/2023 | |
0.6.0-preview | 84 | 9/8/2023 | |
0.5.8-preview | 91 | 9/5/2023 | |
0.5.7-preview | 92 | 9/5/2023 | |
0.5.6-preview | 98 | 9/1/2023 | |
0.5.5-preview | 102 | 8/14/2023 | |
0.5.4-preview | 96 | 8/9/2023 | |
0.5.3-preview | 105 | 8/4/2023 | |
0.5.2-preview | 98 | 8/4/2023 | |
0.5.1-preview | 105 | 8/4/2023 | |
0.5.0-preview | 93 | 8/4/2023 | |
0.4.1-preview | 104 | 7/27/2023 | |
0.4.0-preview | 105 | 7/26/2023 | |
0.3.0-preview | 115 | 3/6/2023 | |
0.2.8-preview | 118 | 3/2/2023 | |
0.2.7-preview | 111 | 3/2/2023 | |
0.2.6-preview | 104 | 3/1/2023 | |
0.2.5-preview | 114 | 3/1/2023 | |
0.2.4-preview | 111 | 2/28/2023 | |
0.2.3-preview | 110 | 2/28/2023 | |
0.2.2-preview | 107 | 2/28/2023 | |
0.2.1-preview | 119 | 2/3/2023 | |
0.2.0-preview | 121 | 1/12/2023 | |
0.1.1-preview | 122 | 9/30/2022 | |
0.1.0-preview | 139 | 9/8/2022 |