mirror of
https://github.com/vector-im/hydrogen-web.git
synced 2024-12-23 03:25:12 +01:00
update SDK doc, use it as sdk package readme
This commit is contained in:
parent
441fa13bfd
commit
c3ff571af7
74
doc/SDK.md
74
doc/SDK.md
@ -1,40 +1,44 @@
|
|||||||
# 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
|
```sh
|
||||||
# you can pick "vanilla-ts" here for project type if you're not using react or vue
|
# you can pick "vanilla-ts" here for project type if you're not using react or vue
|
||||||
yarn create vite
|
yarn create vite
|
||||||
cd <your-project-name>
|
cd <your-project-name>
|
||||||
yarn
|
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
|
```ts
|
||||||
import {
|
import {
|
||||||
Platform,
|
Platform,
|
||||||
SessionContainer,
|
Client,
|
||||||
LoadStatus,
|
LoadStatus,
|
||||||
createNavigation,
|
createNavigation,
|
||||||
createRouter,
|
createRouter,
|
||||||
RoomViewModel,
|
RoomViewModel,
|
||||||
TimelineView
|
TimelineView
|
||||||
} from "hydrogen-web";
|
} from "hydrogen-view-sdk";
|
||||||
import {olmPaths, downloadSandboxPath} from "hydrogen-web/src/sdk/paths/vite";
|
import assetPaths from "hydrogen-view-sdk/paths/vite";
|
||||||
|
import "hydrogen-view-sdk/style.css";
|
||||||
|
|
||||||
|
async function main() {
|
||||||
const app = document.querySelector<HTMLDivElement>('#app')!
|
const app = document.querySelector<HTMLDivElement>('#app')!
|
||||||
|
const platform = new Platform(app, assetPaths, { development: import.meta.env.DEV });
|
||||||
// bootstrap a session container
|
|
||||||
const platform = new Platform(app, {
|
|
||||||
downloadSandbox: downloadSandboxPath,
|
|
||||||
olm: olmPaths,
|
|
||||||
}, null, { development: true });
|
|
||||||
const navigation = createNavigation();
|
const navigation = createNavigation();
|
||||||
platform.setNavigation(navigation);
|
platform.setNavigation(navigation);
|
||||||
const urlRouter = createRouter({
|
const urlRouter = createRouter({
|
||||||
@ -42,29 +46,24 @@ const urlRouter = createRouter({
|
|||||||
history: platform.history
|
history: platform.history
|
||||||
});
|
});
|
||||||
urlRouter.attach();
|
urlRouter.attach();
|
||||||
const sessionContainer = new SessionContainer({
|
const client = new Client(platform);
|
||||||
platform,
|
|
||||||
olmPromise: platform.loadOlm(),
|
|
||||||
workerPromise: platform.loadOlmWorker()
|
|
||||||
});
|
|
||||||
|
|
||||||
// wait for login and first sync to finish
|
const loginOptions = await client.queryLogin("matrix.org").result;
|
||||||
const loginOptions = await sessionContainer.queryLogin("matrix.org").result;
|
client.startWithLogin(loginOptions.password("username", "password"));
|
||||||
sessionContainer.startWithLogin(loginOptions.password("user", "password"));
|
|
||||||
await sessionContainer.loadStatus.waitFor((status: string) => {
|
await client.loadStatus.waitFor((status: string) => {
|
||||||
return status === LoadStatus.Ready ||
|
return status === LoadStatus.Ready ||
|
||||||
status === LoadStatus.Error ||
|
status === LoadStatus.Error ||
|
||||||
status === LoadStatus.LoginFailed;
|
status === LoadStatus.LoginFailed;
|
||||||
}).promise;
|
}).promise;
|
||||||
// check the result
|
|
||||||
if (sessionContainer.loginFailure) {
|
if (client.loginFailure) {
|
||||||
alert("login failed: " + sessionContainer.loginFailure);
|
alert("login failed: " + client.loginFailure);
|
||||||
} else if (sessionContainer.loadError) {
|
} else if (client.loadError) {
|
||||||
alert("load failed: " + sessionContainer.loadError.message);
|
alert("load failed: " + client.loadError.message);
|
||||||
} else {
|
} else {
|
||||||
// we're logged in, we can access the room now
|
const {session} = client;
|
||||||
const {session} = sessionContainer;
|
// looks for room corresponding to #element-dev:matrix.org, assuming it is already joined
|
||||||
// room id for #element-dev:matrix.org
|
|
||||||
const room = session.rooms.get("!bEWtlqtDwCLFIAKAcv:matrix.org");
|
const room = session.rooms.get("!bEWtlqtDwCLFIAKAcv:matrix.org");
|
||||||
const vm = new RoomViewModel({
|
const vm = new RoomViewModel({
|
||||||
room,
|
room,
|
||||||
@ -77,4 +76,15 @@ if (sessionContainer.loginFailure) {
|
|||||||
const view = new TimelineView(vm.timelineViewModel);
|
const view = new TimelineView(vm.timelineViewModel);
|
||||||
app.appendChild(view.mount());
|
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.
|
||||||
|
@ -5,6 +5,7 @@ yarn tsc -p tsconfig-declaration.json
|
|||||||
./scripts/sdk/create-manifest.js ./target/package.json
|
./scripts/sdk/create-manifest.js ./target/package.json
|
||||||
mkdir target/paths
|
mkdir target/paths
|
||||||
./scripts/sdk/transform-paths.js ./src/platform/web/sdk/paths/vite.js ./target/paths/vite.js
|
./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 target
|
||||||
pushd asset-build/assets
|
pushd asset-build/assets
|
||||||
mv main.*.js ../../main.js
|
mv main.*.js ../../main.js
|
||||||
|
Loading…
Reference in New Issue
Block a user