5.2.0 Enhancements

[sbwalker]

Content Search

One of the major enhancements in the upcoming 5.2.0 release is a search capability for site content (credit to @zyhfish for his contribution in this area). The high level architecture is outlined in the following diagram:

There are 2 main extensibility points:

1. ISearchable - an interface which modules can implement that allows their content to be indexed.
2. ISearchProvider - an interface which allows developers to create custom Search Providers

ISearchable

This interface contains a single method for indexing content. A PageModule object is passed to the method, providing a variety of useful metadata which can be utilized during indexing. A LastIndexedOn property is also passed to the method indicating that only content which has been modified since that date needs to be re-indexed. The method expects a list of SearchContent objects to be returned.

namespace Oqtane.Interfaces
{
    public interface ISearchable
    {
        public Task<List<SearchContent>> GetSearchContentsAsync(PageModule pageModule, DateTime lastIndexedOn);
    }
}

The SearchContent properties which are most relevant to module developers are outlined below:

    public class SearchContent
    {
        public string EntityName - the name of the content "entity" being indexed (usually matches the name of the database table or model)
        public string EntityId // the unique identifier for the content entity 
        public string Title // the title of the content (optional - inherits the module title if not specified)
        public string Description // a summary description of the content (optional)
        public string Body // the actual content 
        public string Url // the url for accessing the page where the content exists (starting with the page path - not including any alias)
        public string Permissions // comma delimited list of any entity names/ids which identify View permissions for the content ie. Module:1,Page:2
        public string ContentModifiedBy // the date/time when the content was last modified
        public DateTime ContentModifiedOn // the username who last modified the content
        public string AdditionalContent // any additional content to be indexed (optional)
        public List<SearchContentProperty> SearchContentProperties  // any additional facets to be indexed (optional)
        public bool IsDeleted // whether the content is active or deleted
    }

One of the main benefits of having a native search capability is that it is integrated with Oqtane's dynamic security model. This allows both public and private content to be indexed. Oqtane's permission model is very flexible and is managed through a centralized service which provides consistency and scalability. It also ensures that content permissions are enforced in real-time, mitigating the risk of sensitive content from being exposed to unauthorized users.

SearchIndexJob

The ISearchable interface is utilized by the SearchIndexJob scheduled job which runs on regular intervals to retrieve new search content. The SearchIndexJob iterates through all tenants, all sites within those tenants, all pages within those sites, and all module instances on those pages. It understands the relationship between pages and modules and automatically re-indexes the module content if a page or module is modified. It also removes content from the index if pages or modules are deleted or expire.

File Management

The File Management module in the Admin Dashboard has included an implementation of the ISearchable interface. It indexes all of the folders/files within a site. For standard text files (ie. *.txt, *.htm, *.html) it indexes their content.

ISearchProvider

The ISearchProvider interface allows you to create custom providers for managing search content. This includes both the ability to store search content and retrieve it. The general idea is that if you do not want to use the default DatabaseSearchProvider, you can create a custom implementation. Some examples of custom search providers are providers which integrate with third party components or services such as Lucene, Solr, or Azure Cognitive Search. Each site within an Oqtane installation can specify its own Search Provider.

    public interface ISearchProvider
    {
        string Name { get; }

        Task<List<SearchResult>> GetSearchResultsAsync(SearchQuery searchQuery);

        Task SaveSearchContent(SearchContent searchContent, Dictionary<string, string> siteSettings);
        
        Task ResetIndex();
    }

DatabaseSearchProvider

The default search provider uses a standard inverted index to provide lexical search capabilities based on key words. The search content is stored in the Oqtane tenant database (ie. SQL Server, MySQL, SQLite, PostgreSQL). The default search provider requires no additional infrastructure or dependencies and should satisfy the needs of the majority of sites.

Search Admin

A module was added to the Admin Dashboard which allows the site administrator to manage various configuration options related to search indexing.

Search Component

A search component was created and integrated into the default Oqtane theme. It allows end users to enter key words and click a search icon.

Search Results

A search results page was added to sites which displays the items which match the search criteria entered.

Search Settings

A settings component allows you to manage various configuration options related to search results.

Default Module Template

The default module template which developers can use to scaffold new modules (using Create Module option in the Module Management page in the Admin Dashboard) now includes an ISearchable implementation to make it very easy for developers to utilize this new capability.

Module Search

The SearchResultsService can be also be used to provide search capabilities within individual modules. The SearchQuery object simply needs to set the IncludeEntities property to the entity name that relates to the module and the search results will be filtered accordingly.

        public async Task<SearchResults> GetSearchResultsAsync(SearchQuery searchQuery)
        {
            return await PostJsonAsync<SearchQuery, SearchResults>(ApiUrl, searchQuery);
        }

[sbwalker]

Text Editor

Another of the major enhancements in the upcoming 5.2.0 release is an extensibility option which allows developers to create custom text editor providers (also credit to @zyhfish for his contribution in this area).

Oqtane has always included a rich text editor based on QuillJS. It was originally created by @ADefWebserver and provides the most common functionality required by content editors. However for more advanced users who want the ability to write HTML, the QuillJS editor has some limitations. Rather than trying to create a text editor which meets the needs of everyone (which is impossible), it will now be possible for developers to create their own custom text editors.

ITextEditor

An interface has been introduced which contains a few basic methods that need to be implemented to create a custom text editor provider

    public interface ITextEditor
    {
        void Initialize(string content); 

        Task<string> GetContent();
    }

Each site has the ability to specify its default text editor

QuillJSTextEditor

The default text editor provided with Oqtane will continue to be based on QuillJS. A new QuillJSTextEditor component was created which implements the new ITextEditor interface. It contains a new Settings option which enables the editor to be customized for each site or for each module instance.

TextAreaTextEditor

An alternate text editor which is simply a wrapper around the primitive HTML textarea element. This text editor does not provide any advanced functionality but serves as an example of how the ITextEditor interface can support multiple implementations.

RichTextEditor

Developers should continue to use the standard RichTextEditor component within their modules. At run-time the framework will determine which text editor provider should be initialized dynamically based on the configuration.

<RichTextEditor Content="@_content" @ref="@RichTextEditorHtml"></RichTextEditor>

Compatibility

The goal was to avoid any breaking changes with this enhancement. That being said, the RichTextEditor options which were previously managed in the HtmlText module Settings UI have now been moved to the new QuillJSTextEditor Settings UI.