search

dotnet-websharper / ui

A reactive UI library for WebSharper.
https://websharper-samples.github.io/ui/
Apache License 2.0
77 stars 22 forks source link

Ease syntax for server-client bridge in markup #240

Closed granicz closed 1 year ago

granicz commented 2 years ago

When constructing server-side HTML with dynamic, client-side content/functionality, we rely on client/clientSide/Doc.Hydrate to embed client-side content, and historically we required explicit quotations <@ ... @> around the client-side expression. The reasoning was "to mark the server-client bridge so it stands out."

This ticket is to extend the API to allow for variants of the above functions not to require explicit quotations, as to remove the "strangeness" factor associated with the quotation symbols.

Given F#'s current limitation of having auto-quotation available only on members of a type, one proposal would be to make these functions available as Doc.Client, Doc.ClientSide (already "there" but needs to a member, filed as #239), and Doc.Hydrate (already there).

granicz commented 2 years ago

More thoughts we should take into consideration:

1) Old code using client <@ ... @> should receive warnings to help migrating to the newer syntax. 2) Changing to the new syntax should not require name changes, unless the old name is obscure. 3) client, Doc.Hydrate, and any other function dealing with mixed tiers, are special functions and they need to be named and placed accordingly. 4) We should clear up/standardize how to refer to mixed-tier functions (client/ClientSide/Doc.ClientSide/Doc.Hydrate/etc.)

Based on these, I think the following makes most sense:

1) Creating a new holder class (proposal is WebSharper.UI.ClientServer) with static members (named with lowercase to denote significance), applying auto-quoting where appropriate: a. client b. clientLinq c. hydrate 2) Obsoleting the original functions with a reference to the new counterparts: a. client -> use ClientServer.client (and revise #241) b. Doc.ClientSide -> use ClientServer.client (and revise #239) c. Doc.Hydrate (too bad as this was just recently introduced) -> use ClientServer.hydrate d. ClientSide (the alias to InlineControl) -> use InlineControl(...) e. Doc.ClientSideLinq -> use ClientServer.clientLinq 3) Giving guidance in the documentation about migrating to the new syntax: a. Use open type WebSharper.UI.ClientServer to override the old syntax and to require the new one b. Old code can also reference the new functions from ClientServer.* directly.

Jand42 commented 2 years ago

@granicz ClientSideLinq is for C# use, already aliased for C# as client to look same as F#. Not really worth aliasing for F# use.

granicz commented 2 years ago

@Jand42 This ticket is not about who uses those functions but from where. There is now a separate place for mixed-tier functions, and clientLinq belongs there too. And yes, the C# alias should point to the new place.

granicz commented 2 years ago

ClientServer.* needs XMLDOC comments to describe what they do - not sure how we missed these...