Interface Group

A distribution group may have nested distribution groups. This collection may initially be empty, as the UI may not need to display the nested groups, but can be loaded from the server either via a call to groups.get or via a subscription to the groups:added event.

To get the list of names of nested groups without sending requests to the server:

var nestedGroups = thisGroup.groups();
nestedGroups.forEach((group) => {
    console.log(group.name());
});

To request the list of nested groups from the server:

thisGroup.groups.get().then((nestedGroups) => {
    // now these groups in the local cache, so
    // nestedGroups == thisGroup.groups()

    nestedGroups.forEach((group) => {
        console.log(group.name());
    });
});

To observe the collection of nested groups:

thisGroup.groups.added((group) => {
    console.log(group.name() + " has been added");
});

thisGroup.groups.removed((group) => {
    console.log(group.name() + " has been removed");
});

There are two predefined groups created by the server, with the following names:

   - Other Contacts
   - Pinned Contacts
     ("Pinned Contacts" corresponds to the "Favorites" group.)

The setter of the name attribute can be used to rename the group, which leads to a "PUT" request being sent to UCWA. This "PUT" request, upon success (with a 204 response), results in a new group being created by UCWA (indicated by a "group added" event) with the new name, and the old group (with the old name) being deleted by UCWA (indicated by a "group deleted" event). For this reason, such a setter call will return the (old) name of the old group, since the caller would still hold the reference to the old group object (which will be deleted when the "group deleted" event arrives).

Consider this example to rename a group:

// assume getGroupByName returns the Group object by its name
var group = getGroupByName("oldName");

client.personsAndGroupsManager.all.groups.added(() => {
    g.name.get().then((a) => {
        // the new group with the new name has been created
        // update the reference if want to reuse it
        if (a == "newGroup") group = g;
    });
});

client.personsAndGroupsManager.all.groups.removed((g) => {
    g.name.get().then((a) => {
        // the old group with the old name has been deleted
        // the old reference is no long valid if not updated yet
        // so renew it to point to the new group object
        if (a == "oldGroup") group = getGroupByName("newName");
    });
});

group.name.set("newName").then((a) => {
    // a should be the name "oldName" of the old group
    console.log(a);
});

// at this moment, the group reference is likely still pointing
// to the old group, with name "oldName"
console.log(group.name());
// ...
// some moments later, after the "group added" event is received
// the group reference has been updated to point to the new group
// with name "newName"
console.log(group.name());

The constructor does not populate this collection because the UI may not need to display the contacts immediately. Instead it waits until someone subscribes to the collection and then loads contacts from the server.

When writing UI controls on top of this class, consider the following approach of reading contacts:

group.persons.added((person) =>{
    person.displayName.changed((displayName) =>{
        $('.displayName').text(...);
    });
});

The handler attached to the "added" event will be invoked for all contacts in the collection even if they were added to it before the handler is attached.

To get the list of contacts once from the server use the async get method that sends a GET request(s) to the server and resolves the returned promise to the array of Person models. In addition to that it saves the list of Person models in the cache, so next time these contacts can be retrieved without the need to go to the server.

group.persons.get().then((persons) => {
    persons.forEach((person) => {
        console.log(group.name() + " contains " + person.displayName());
    });
});

To add or remove a contact use the async add/remove methods:

group.persons.add(person).then(null, (err) => {
    console.log("The contact cannot be added: " + err);
});

group.persons.remove(person).then(null, (err) => {
    console.log("The contact cannot be removed: " + err);
});

These methods send a request to the server to add or remove a contact. The contact gets actually removed or added after the server sends a corresponding event that can be observed in the added and removed events of the collection.

Not all groups support adding and removing contacts. For instance distribution groups discovered via search cannot be edited this way.