NuKVM/xen-orchestra
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix(README): update doc

Browse Source
This commit is contained in:
Julien Fontanet 2016-11-18 10:46:51 +01:00
parent 4294dfd8fe
commit caba246e0b
1 changed files with 87 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
packages/xo-lib/README.md
View File

@ -1,14 +1,8 @@
# xo-lib # xo-lib [![Build Status](https://travis-ci.org/vatesfr/xo-lib.png?branch=master)](https://travis-ci.org/vatesfr/xo-lib)
[![Build Status](https://img.shields.io/travis/vatesfr/xo-lib/master.svg)](http://travis-ci.org/vatesfr/xo-lib)
[![Dependency Status](https://david-dm.org/vatesfr/xo-lib/status.svg?theme=shields.io)](https://david-dm.org/vatesfr/xo-lib)
[![devDependency Status](https://david-dm.org/vatesfr/xo-lib/dev-status.svg?theme=shields.io)](https://david-dm.org/vatesfr/xo-lib#info=devDependencies)
> Library to connect to XO-Server. > Library to connect to XO-Server.
## Installation ## Install
### Node & Browserify
Installation of the [npm package](https://npmjs.org/package/xo-lib): Installation of the [npm package](https://npmjs.org/package/xo-lib):
@ -19,100 +13,47 @@ npm install --save xo-lib
Then require the package: Then require the package:
```javascript ```javascript
var xoLib = require('xo-lib'); import Xo from 'xo-lib'
``` ```
## High level API ## Usage
This high-level interface handles session sign-in and a cache of > If the URL is not provided and the current environment is a web
remote XO objects. It also automatically reconnect and retry method > browser, the location of the current page will be used.
calls when necessary.
```javascript ```javascript
// Connect to XO. // Connect to XO.
var xo = new xoLib.Xo('https://xo.company.tld'); const xo = new Xo({ url: 'https://xo.company.tld' })
// Let's start by opening the connection.
await xo.connect()
// Must sign in before being able to call any methods (all calls will // Must sign in before being able to call any methods (all calls will
// be buffered until signed in). // be buffered until signed in).
xo.signIn({ await xo.signIn({
email: 'admin@admin.net', email: 'admin@admin.net',
password: 'admin', password: 'admin'
}).then(function () { })
console('signed as', xo.user);
}); console('signed as', xo.user)
``` ```
The credentials can also be passed directly to the constructor: The credentials can also be passed directly to the constructor:
```javascript ```javascript
var xo = new xoLib.Xo({ const xo = Xo({
url: 'https://xo.company.tld', url: 'https://xo.company.tld',
credentials: { credentials: {
email: 'admin@admin.net', email: 'admin@admin.net',
password: 'admin', password: 'admin',
} }
}); })
```
> If the URL is not provided and the current environment is a web xo.open()
> browser, the location of the current page will be used.
### Method call xo.on('authenticated', () => {
console.log(xo.user)
```javascript })
xo.call('token.create').then(function (token) {
console.log('Token created', token);
});
```
### Status
The connection status is available through the status property which
is *disconnected*, *connecting* or *connected*.
```javascript
console.log('%s to xo-server', xo.status);
```
### Current user
Information about the user account used to sign in is available
through the `user` property.
```javascript
console.log('Current user is', xo.user);
```
> This property is null when the status is not connected.
### XO Objects
XO objects are cached locally in the `objects` collection.
```javascript
// Read-only dictionary of all objects.
var allObjects = xo.objects.all;
// Looks up a given object by its identifier.
var object = allObjects[id];
// Read-only dictionary of all indexes.
var indexes = xo.objects.indexes;
// Read-only dictionary of types.
var byTypes = indexes.type;
// Read-only view of all VMs.
var vms = byTypes.VM;
```
Available indexes are: `ref`, `type` and `UUID`.
## Low level
```javascript
var api = new xoLib.Api('https://xo.company.tld');
``` ```
> If the URL is not provided and the current environment is a web > If the URL is not provided and the current environment is a web
@ -121,48 +62,94 @@ var api = new xoLib.Api('https://xo.company.tld');
### Connection ### Connection
```javascript ```javascript
api.connect().then(function () { await xo.open()
console.log('connected');
}); console.log('connected')
``` ```
### Disconnection ### Disconnection
```javascript ```javascript
api.close(); xo.close()
console.log('disconnected')
``` ```
### Method call ### Method call
```javascript ```javascript
api.call('session.signInWithPassword', { const token = await xo.call('token.create')
email: 'admin@admin.net',
password: 'admin', console.log('Token created', token)
}).then(function (user) {
console.log('Connected as', user);
});
``` ```
> A method call automatically trigger a connection if necessary. ### Status
The connection status is available through the status property which
is *open*, *connecting* or *closed*.
```javascript
console.log('%s to xo-server', xo.status)
```
### Current user
Information about the user account used to sign in is available
through the `user` property.
```javascript
console.log('Current user is', xo.user)
```
> This property is null when the status is not connected.
### Events ### Events
```javascript ```javascript
api.on('connected', function () { xo.on('open', () => {
console.log('connected'); console.log('connected')
}); })
``` ```
```javascript ```javascript
api.on('disconnected', function () { xo.on('closed', () => {
console.log('disconnected'); console.log('disconnected')
}); })
``` ```
```javascript ```javascript
api.on('notification', function (notif) { xo.on('notification', function (notif) {
console.log('notification:', notif.method, notif.params); console.log('notification:', notif.method, notif.params)
}); })
```
```javascript
xo.on('authenticated', () => {
console.log('authenticated as', xo.user)
})
xo.on('authenticationFailure', () => {
console.log('failed to authenticate')
})
```
## Development
```
# Install dependencies
> npm install
# Run the tests
> npm test
# Continuously compile
> npm run dev
# Continuously run the tests
> npm run dev-test
# Build for production (automatically called by npm install)
> npm run build
``` ```
## Contributions ## Contributions