docs: add welcome documentation #235
Conversation
|
I'm sure there's definitely holes here and will require some modifications, but wanted to put this up to get a 👍 to keep going in this direction, if it aligns with y'all's process |
| |-----------------|--------------------------|-----------|--------------------------------------------------------| | ||
| | `_format` | swiftui, jetpack, html | ✅ | The content type to be processed by LiveView Native | | ||
| | `_interface` | mobile, watch, tv | | The general device type | | ||
| | `os_version` | `string` | | The version of the client OS | |
There was a problem hiding this comment.
the only query params are _format and _interface. os_version and app_version are in the _interface map.
| | `app_version` | `string` | | The version of the client application | | ||
|
|
||
| This is formatted as `/?_format=xx&_interface=xx&os_version=xx&app_version=xx`, and when no query parameters are provided, | ||
| will default to the corresponding Phoenix LiveView route (presuming a route is provided). |
There was a problem hiding this comment.
Just FYI that we're looking at moving over to headers instead of query params. The QPs I think will continue to work as a fallback.
There was a problem hiding this comment.
That change won't take place until 0.5.0 if it does at all
|
|
||
| Once a request is sucessfully delegated by LiveView Native, it will attempt to match on your LiveView route. | ||
|
|
||
| By design, LiveView Native does not ship with a default rendering package, and instead seperates |
There was a problem hiding this comment.
It may be better to say "By design, LiveView Native does not ship with a client"
| By design, LiveView Native does not ship with a default rendering package, and instead seperates | ||
| itself into a series of distinct packages. Each package ships with its own modifiers to handle its respective client, | ||
| and unlike many framework agnostic development frameworks, intentionally seperates your markup by platform. | ||
|
|
There was a problem hiding this comment.
I think this is a good opportunity to show a matrix of the clients:
| platform | client | ready? |
|---|---|---|
| Apple | liveview-client-swiftui | ✅ |
| Android | liveview-client-jetpack |
We can expand on this in the future, for example when we add WinUI3. There is a Flutter client out there but I don't know the status of it (it's not built by us) and we have a semi-implemented Ice client.
There was a problem hiding this comment.
for sure ill add it here :))
| and unlike many framework agnostic development frameworks, intentionally seperates your markup by platform. | ||
|
|
||
| This is to maintain instant feature parity with your platform(s) of choice, as LiveView Native is not concerned with | ||
| cross-platform "bridging." This allows LiveView Native to serve native code to the platform target |
There was a problem hiding this comment.
We need to be careful with wording like "serve native code" as this is a violation of the AppStore's TOS, no remote code execution. Instead we are sending UI representation in the form of markup. So there is no actual runtime code sent over the network.
| end | ||
| ``` | ||
|
|
||
| The modules above show a distinct path to each format handled by its respective rendering package. |
There was a problem hiding this comment.
it may be good to show a mermaid diagram to visualize the delegation and how baserd upon the _format value render delegation will be handled by the correct render component. Seeing the request with no _format use the regular LiveView render/1 then with _format=swiftui being delegated to the correct render component and so on
| The modules above show a distinct path to each format handled by its respective rendering package. | ||
| We start in our Phoenix LiveView, which handles our mount and event handling. From there, LiveView Native | ||
| delegates the request to our markup modules, which handle our rendering. We use the `~LVN` sigil to define a | ||
| NEEx template, which stands for Native+EEx. They are nearly identical to HEEx templates, but used to denote |
There was a problem hiding this comment.
I have been intending to write a section on how NEEx differs from HEEx. If you want to tackle that I can help. It should go in LiveViewNative.Component and probably add a new section to the sigil_LVN macro documentation: https://github.com/liveview-native/live_view_native/blob/main/lib/live_view_native/component.ex#L190
Right now the only differences from HEEx:
- tag name casing is preserved, so we can emit
<Text>and not have it downcased to<text> - We don't permit boolean attributes, for example
<text on>would meanonistruein HTML. And the lack of that attribute would be presumed to befalse. In NEEx we cannot make that presumption because there are times in the upstream native clients that a value's default is false. So we run into a logic error. Instead everything must be explicit:<Text on={true}> - the
:interface-*special attribute, that docuemntation is already there but can just bre rolled into this section
There was a problem hiding this comment.
may be helpful to loop back with you
ill see what I can gather for now, but as I move along with this pr, ill start to ask for you help here
| Once a sucessful response is sent back from the server, we need a client to process this data. | ||
| Similar to most native development, we need the respective platform's development tools to build and deploy | ||
| your LiveView Native client, but as we continue to build our tooling, we are begining to offer platform-specific applications | ||
| to test your project. |
There was a problem hiding this comment.
It would be good to point people to LVN Go as an alternative to using Xcode because of Xcode's compilation time. It's just easy to get going. However, they should only use LVN Go if they're using a release version of LVN. For example, if they're on main or an RC version we don't support LVN Go for those situations.
There was a problem hiding this comment.
For sure I can put more of an emphasis on LVN Go
Hey first pr 👋
I've been spending a decent amount of time reading up on and trying to understand LVN, and wanted to open a pr to address some documentation regarding the core lib.
I see in the past a lot of SwiftUI specific docs have been moved to its corresponding repo, but the core docs seem like a good place to start pointing people to the right place.
Closes #221
Thanks!