From c3ff571af742eda8af6a07e3c15f6beba6cd794e Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 22 Dec 2021 16:20:54 +0100 Subject: [PATCH] update SDK doc, use it as sdk package readme --- doc/SDK.md | 122 +++++++++++++++++++++++-------------------- scripts/sdk/build.sh | 1 + 2 files changed, 67 insertions(+), 56 deletions(-) diff --git a/doc/SDK.md b/doc/SDK.md index 4cd6c68c..c9897844 100644 --- a/doc/SDK.md +++ b/doc/SDK.md @@ -1,80 +1,90 @@ -# How to use Hydrogen as an SDK +# Hydrogen View SDK -If you want to use end-to-end encryption, it is recommended to use a [supported build system](../src/sdk/paths/) (currently only vite) to be able to locate the olm library files. -**NOTE**: For now, these instructions will only work at development time, support when building (e.g. `vite build`) is being worked on and tracked in [#529](https://github.com/vector-im/hydrogen-web/issues/529). +The Hydrogen view SDK allows developers to integrate parts of the Hydrogen application into the UI of their own application. Hydrogen is written with the MVVM pattern, so to construct a view, you'd first construct a view model, which you then pass into the view. For most view models, you will first need a running client. -You can create a project using the following commands +## Example + +The Hydrogen SDK requires some assets to be shipped along with your app for things like downloading attachments, and end-to-end encryption. A convenient way to make this happen is provided by the SDK (importing `hydrogen-view-sdk/paths/vite`) but depends on your build system. Currently, only [vite](https://vitejs.dev/) is supported, so that's what we'll be using in the example below. + +You can create a vite project using the following commands: ```sh # you can pick "vanilla-ts" here for project type if you're not using react or vue yarn create vite cd yarn -yarn add https://github.com/vector-im/hydrogen-web.git +yarn add hydrogen-view-sdk ``` -If you go into the `src` directory, you should see a `main.ts` file. If you put this code in there, you should see a basic timeline after login and initial sync have finished. +You should see a `index.html` in the project root directory, containing an element with `id="app"`. Add the attribute `class="hydrogen"` to this element, as the CSS we'll include from the SDK assumes for now that the app is rendered in an element with this classname. + +If you go into the `src` directory, you should see a `main.ts` file. If you put this code in there, you should see a basic timeline after login and initial sync have finished (might take a while before you see anything on the screen actually). + +You'll need to provide the username and password of a user that is already in the [#element-dev:matrix.org](https://matrix.to/#/#element-dev:matrix.org) room (or change the room id). ```ts import { Platform, - SessionContainer, + Client, LoadStatus, createNavigation, createRouter, RoomViewModel, TimelineView -} from "hydrogen-web"; -import {olmPaths, downloadSandboxPath} from "hydrogen-web/src/sdk/paths/vite"; +} from "hydrogen-view-sdk"; +import assetPaths from "hydrogen-view-sdk/paths/vite"; +import "hydrogen-view-sdk/style.css"; -const app = document.querySelector('#app')! - -// bootstrap a session container -const platform = new Platform(app, { - downloadSandbox: downloadSandboxPath, - olm: olmPaths, -}, null, { development: true }); -const navigation = createNavigation(); -platform.setNavigation(navigation); -const urlRouter = createRouter({ - navigation: navigation, - history: platform.history -}); -urlRouter.attach(); -const sessionContainer = new SessionContainer({ - platform, - olmPromise: platform.loadOlm(), - workerPromise: platform.loadOlmWorker() -}); - -// wait for login and first sync to finish -const loginOptions = await sessionContainer.queryLogin("matrix.org").result; -sessionContainer.startWithLogin(loginOptions.password("user", "password")); -await sessionContainer.loadStatus.waitFor((status: string) => { - return status === LoadStatus.Ready || - status === LoadStatus.Error || - status === LoadStatus.LoginFailed; -}).promise; -// check the result -if (sessionContainer.loginFailure) { - alert("login failed: " + sessionContainer.loginFailure); -} else if (sessionContainer.loadError) { - alert("load failed: " + sessionContainer.loadError.message); -} else { - // we're logged in, we can access the room now - const {session} = sessionContainer; - // room id for #element-dev:matrix.org - const room = session.rooms.get("!bEWtlqtDwCLFIAKAcv:matrix.org"); - const vm = new RoomViewModel({ - room, - ownUserId: session.userId, - platform, - urlCreator: urlRouter, - navigation, +async function main() { + const app = document.querySelector('#app')! + const platform = new Platform(app, assetPaths, { development: import.meta.env.DEV }); + const navigation = createNavigation(); + platform.setNavigation(navigation); + const urlRouter = createRouter({ + navigation: navigation, + history: platform.history }); - await vm.load(); - const view = new TimelineView(vm.timelineViewModel); - app.appendChild(view.mount()); + urlRouter.attach(); + const client = new Client(platform); + + const loginOptions = await client.queryLogin("matrix.org").result; + client.startWithLogin(loginOptions.password("username", "password")); + + await client.loadStatus.waitFor((status: string) => { + return status === LoadStatus.Ready || + status === LoadStatus.Error || + status === LoadStatus.LoginFailed; + }).promise; + + if (client.loginFailure) { + alert("login failed: " + client.loginFailure); + } else if (client.loadError) { + alert("load failed: " + client.loadError.message); + } else { + const {session} = client; + // looks for room corresponding to #element-dev:matrix.org, assuming it is already joined + const room = session.rooms.get("!bEWtlqtDwCLFIAKAcv:matrix.org"); + const vm = new RoomViewModel({ + room, + ownUserId: session.userId, + platform, + urlCreator: urlRouter, + navigation, + }); + await vm.load(); + const view = new TimelineView(vm.timelineViewModel); + app.appendChild(view.mount()); + } } + +main(); ``` + +## Typescript support + +There is partial typescript support while we are still in the process of converting the Hydrogen codebase to typesccript. + +## API Stability + +This library follows semantic versioning; there is no API stability promised as long as the major version is still 0. Once 1.0.0 is released, breaking changes will be released with a change in major versioning. diff --git a/scripts/sdk/build.sh b/scripts/sdk/build.sh index c22eb4ec..3145df80 100755 --- a/scripts/sdk/build.sh +++ b/scripts/sdk/build.sh @@ -5,6 +5,7 @@ yarn tsc -p tsconfig-declaration.json ./scripts/sdk/create-manifest.js ./target/package.json mkdir target/paths ./scripts/sdk/transform-paths.js ./src/platform/web/sdk/paths/vite.js ./target/paths/vite.js +cp doc/SDK.md target/README.md pushd target pushd asset-build/assets mv main.*.js ../../main.js