Skip to content
This repository has been archived by the owner on Dec 11, 2022. It is now read-only.

Latest commit

 

History

History
134 lines (102 loc) · 4.13 KB

README.md

File metadata and controls

134 lines (102 loc) · 4.13 KB

Nymph Client - collaborative app data

Latest Stable Version Open Issues License

Powerful object data storage and querying for collaborative web apps.

Deprecation Notice

The PHP implementation of Nymph/Tilmeld has been deprecated. It will no longer have any new features added. Instead, a new version of Nymph running on Node.js, written entirely in TypeScript will replace the PHP implementation. You can find it over at the Nymph.js repo.

Installation

Automatic Setup

The fastest way to start building a Nymph app is with the Nymph App Template.

Manual Installation

npm install --save nymph-client

This repository is the JavaScript client for browsers. You can find UMD in dist, or ES modules in src. There is also a Node.js client. For more information, you can see the main Nymph repository.

Setup

<head>
  <!-- Nymph setup -->
  <script>
    NymphOptions = {
      restURL: 'https://yournymphrestserver/path/to/your/rest.php',
      pubsubURL: 'wss://yournymphpubsubserver',
    };
  </script>
  <!-- End Nymph setup -->

  <!-- Old school JS -->
  <script src="node_modules/nymph-client/dist/NymphClient.js"></script>
  <script src="path/to/your/entity/js/Todo.js"></script>
  <!-- End Old school JS -->
</head>

Babel Config

When you use Babel, you can add the @babel/plugin-transform-classes plugin to properly extend the Error class. Nymph throws error classes that extend this class.

{
  "plugins": [
    ["@babel/transform-classes", {
      "builtins": ["Error"]
    }]
  ]
}

Usage

For detailed docs, check out the wiki:

Here's an overview:

import { Nymph, PubSub } from 'nymph-client';
import Todo from 'Todo';

// Now you can use Nymph and PubSub.
const myTodo = new Todo();
myTodo.name = 'This is a new todo!';
myTodo.done = false;
await myTodo.$save();

let subscription = myTodo.$subscribe(() => {
  // When this is called, the entity will already contain new data from the
  // publish event. If the entity is deleted, the GUID will be set to null.
  if (myTodo.guid != null) {
    alert('Somebody touched my todo!');
  } else {
    alert('Somebody deleted my todo!');
    subscription.unsubscribe();
  }
});

// ...

// Subscribing to a query.
let todos = [];
let userCount = 0;
let subscription = Nymph.getEntities(
  {
    class: Todo.class,
  },
  {
    type: '&',
    '!tag': 'archived',
  }
).subscribe(
  newTodos => {
    // The first time this is called, newTodos will be an array of Todo entities.
    // After that, newTodos will be a publish event object.

    // This takes an existing array of entities and either updates it to match
    // another array, or performs actions from a publish event object to update
    // it.
    PubSub.updateArray(todos, newTodos);

    // `todos` is now up to date with the latest publishes from the server.
  },
  err => alert(err),
  count => {
    // If you provide this callback, the server will send updates of how many
    // clients are subscribed to this query.
    userCount = count;
  }
);

// ...

// Remember to clean up your subscriptions when you no longer need them.
subscription.unsubscribe();

For a thorough step by step guide to setting up Nymph on your own server, visit the Setup Guide.

API Docs

Check out the API Docs in the wiki.