Release Docs | Suggestions

[David-Moreira]

On release docs, we should start adding anchors, so we can easily refer people to certain sections in the release notes.

(If we could add a table of contents for easier navigation that would be plus :))

[stsrki]

Clearing milestone flag. We can do this after the release with other improvements in the docs.

[oaldrian]

A suggestion from my side (as a regular user of the docs) is some sort of a search function. I frequently am scrolling up and down in the list of available components and extensions, which gets a bit annoying in the long run.

I am not suggesting a Search component (which would be a cool addition in later versions, but I'm not really sure how I would spec such a function, or maybe this is a dumb idea anyway).

But I suggest a "Quick Component Navigator" that is either in the topbar or the navmenu and gets focus immediately on page load in the whole docs area. It could be implemented with a Autocomplete with a list of all components / extensions / really every doc page / any degree of detail wanted, and on SelectedTextChanged navigates to the selected component.

Thinking about it, it may be better placed in the navMenu as the TopBar isnt visible anymore on longer pages, and if somebody copied some text, then the autocomplete would have lost focus.

[stsrki]

A search function might be too complicated, considering that all our content is strongly-typed. Maybe it can be done, TBH I didn't investigate it. @David-Moreira Do you think it would be possible?

We do have in plan to add a TOC, or quick menu to jump to the sections within the currently open page. I think it would at least speed things up when searching for something.

[oaldrian]

thought about a rough scratch:

• Autocomplete component in Navbar at the top
• SelectedTextChanged Navigates to the specific page (hitting Enter works already)
• Data of Autocomplete is a static List of "SearchItems" which are really two strings, the text and the url
• As a prebuild step in the project runs a script that looks for all '<Seo Canonical="/docs' and fetches the Title (without the words "Blazorise", "component" and "system") and the url, and fills the found values in the SearchItems List constructor

Would be a way to automatically generate the content of the "Search" with already existing data.

[David-Moreira]

Right, as @oaldrian said. I think his idea would be already quite nice to have.

If you want it even more powerful, I think you will always have to pre-load the stuff into some kind of indexing engine and I think SQL might be enough to handle it. https://docs.microsoft.com/en-us/sql/relational-databases/search/full-text-search?view=sql-server-ver15

Don't think I ever implemented a use case like this but I'm sure we can find stuff/patterns online if we look it up.

[oaldrian]

What is the time horizon on this issue? If it is not too urgent, I will find some free time and implement the approach I outlined.

Better indexing/other sources for the autocomplete could be added later.

[stsrki]

It would have to be done at compile-time only as making it at runtime would not be possible. Some kind of trimming engine would remove all Blazor tags and component names and then parse only the textual content. After that, it would have to index everything by:

• page route
• sections: h1, h2, h3
• finally, do the paragraphs

Then save all that into DB, JSON, or something.

I think that is the approach we would have to do.

[oaldrian]

Pretty much what I thought. I would go JSON and read that in once into static, so there is no delay accessing the function itself.

Documentation/Blazor.Docs.Parser ?

[stsrki]

I would do it all in the Blazorise.Docs.Compiler. It is already used to build the docs from the source.

[David-Moreira]

It would have to be done at compile-time only as making it at runtime would not be possible. Some kind of trimming engine would remove all Blazor tags and component names and then parse only the textual content. After that, it would have to index everything by:

• page route
• sections: h1, h2, h3
• finally, do the paragraphs

Then save all that into DB, JSON, or something.

I think that is the approach we would have to do.

Might be able to borrow BUnit's api to generate the proper html?

[oaldrian]

Sounds like an idea. For starters I would take a simpler approach to get a feeling if the feature fits.

• Loop over all Files in Documentation/Blazorise.Docs/Pages/Docs and Regex out the path and the description. put it in a JSON file. Alternatively the DocsLayout.razor also contains pretty much all needed info, and could be the only file read from the parser.
• Add a singleton service to the server that reads the json into a JSON List in the constructor.
• Autocomplete component itself into the NavMenu.

[oaldrian]

I will make time this weekend and implement a scratch version, for you to look at and evaluate the functionality. (Mostly because I really would like this feature in the docs).

[stsrki]

@oaldrian Are you on Discord?

[oaldrian]

another suggestion: in the datagrid features section, include a int? column in the examples. for ex: in custom filtering, how to define a <FilterTemplate> for a int? column is not obvious.

just as info, I do it that way:

`          <FilterTemplate>
            @{
              var selectedValue = @context.SearchValue ?? "*";
              <Select TValue="string" SelectedValue="@selectedValue.ToString()" SelectedValueChanged="@(e => context.TriggerFilterChange(e == "*" ? "" : e.ToString()))">
                <SelectItem Value="@("*")"># Alle #</SelectItem>
                <SelectItem TValue="int?" Value="@(1)">A</SelectItem>
                <SelectItem TValue="int?" Value="@(2)">B</SelectItem>
                <SelectItem TValue="int?" Value="@(3)">C</SelectItem>
              </Select>
            }
          </FilterTemplate>

`