Overview

This document aims to outline the features provided by Socites model. It currently is in draft state.
Socites Graphs API (SG API for short) is the way to interact with our cloud based social apps. It is made of full Javascript libraries, and exposes a vast set of social features. SG API is readily available in Socites Packs and can also be used in custom Beyond.js projects.

Note

If you are customizing a Community or a Network Of Communities, you will find Socites Graphs Libraries on the following folder:

  • libraries/model

As its name suggests, SG API is based on an atomic unit of data, called graph. Each graph is an instance of an entity, which means that its attributes match the specification given by the entity from which it inherits.
Each graph on the plataform shares a common set of properties.
  • A unique ID.
  • An owner.
  • An entity type.
  • The community that the graph belongs to.
  • Permissions set for privacy settings.
  • A list of attributes. (see Graph Object for details)
  • A document with the fields specified by the entity.
There is also another relevant abstraction, that goes by the name of collections, which are an ordered set of graphs. A Collection helps you deal with a group of related graphs, handling the loading of the graphs and its pagination, among others.
Most of the SG APIs requires session tokens to handle authentication and authorization. In order to interact with the model  with the user credentials you would be required to see Accounts- Registration - Login.
Credentials are available as follows:

Current Level (default)

auth.session
  • .account
    • .ID
    • .clusterId
    • .valid
    • .user
      • .ID
      • .birthday
      • .email
      • .lastName
      • .name
      • .picture
  • .ds
  • .me (User Graph Object)
  • .name
  • .recover
  • .signin
  • .signout
  • .token

Network of communities level

auth.sessions.vertical
  • .account
    • .ID
    • .clusterID
    • .user
  • .ds
  • .me
  • .name
  • .recover
  • .signin
  • .sigout
  • .token

Community level

auth.sessions.community
  • .account
    • .ID
    • .clusterID
    • .user
  • .ds
  • .me
  • .name
  • .recover
  • .signin
  • .sigout
  • .token
The model implementation of the graphs  are through the graph object, which several entities inherit from and have the following structure:.

Attributes

  • atributes
    • ID
    • DS
    • authorized
    • created
    • enabled
    • language
    • picture
    • updated
    • url
  • containers
  • document
  • enity
    • ID
  • owner
  • picture
  • version
    • ID

Methods

  • bind
  • unbind
  • fetch
  • discard -> discards draft
  • save -> saves draft
  • publish
  • remove
  • contributors.fetch -> Only in entities which support permissions
  • contributors.add -> Only in entities which support permissions
  • contributors.remove -> Only in entities which support permissions
  • contributors.update -> Only in entities which support permissions
  • contributors.push -> Only in entities which support permissions
  • picture.upload -> upload image to graph, bindable event 'uploading'
  • picture.external.set -> sets external image to graph
  • picture.external.clean -> cleans external image in graph
  • picture.external.stored -> image stored in graph
  • picture.external.url -> external image url
  • picture.temp.clean -> cleans temp image
  • picture.temp.unsaved -> Bool flag
  • picture.temp.set -> sets temp image(until it’s published)

Bindable events

  • edited
  • fetched
  • loaded
  • published
Collections are materialized by the Collection Object, they have the following attributes, methods and events:

Attributes

  • limit
  • length
  • next
  • object
  • offset

Methods

  • fetch
  • bind
  • unbind
  • shift

Bindable events

  • changed
  • fetched
In Socites, graphs are specialized using entities that have certain fields and relations, each entity belongs to a unique library as described below: (Graphs, Contents and Opinions are the standard libraries, but other custom libraries can be used / created)

GRAPHS Entities:

Communiverses

Users

CONTENTS Entities:

Sections

Topics Articles Open Graph Videos Galleries Posts Status

OPINIONS Entities:

Opinions

Comments Debates

LEGEND:

  • FT = Full text indexed field. (Searchable)
  • M = Mandatory fiels.

To interact with the model, you should first require and instantiate the library, for example using opinions the following code gets the first page of comments on an article and show the texts in the console:

Code:
copy

var articles;
new Promise (function(resolve){
        require(['libraries/contents/assets'], function (model) {
        articles = new model.Articles();
        resolve();
    });
})
.then(function() {
    /* Get First Article contained on user 536bbdcd31333027aabcfc28 */
    var firstArticle;
    articles.attributes.containerID = '536bbdcd31333027aabcfc28';
    var page = articles.pages.get(1);

    page.bind('fetched', function (objects) {
        firstArticle = objects[0];
    });
    page.fetch();
})
.then(function() {
    /* Get comments on first article */
    var opinions;
    new Promise(function(resolve) {
        require(['libraries/comments/main'], function (model) {
            opinions = new model.Opinions();
            resolve();
        });

    })
    .then(function() {
        opinions.attributes.containerID = firstArticle.ID;

        var page = opinions.pages.get(1);
        page.bind('fetched', function (objects) {
            for (var i in objects) {
                console.log(objects[i].document.text.value);
            }
        }
        page.fetch();
    });
});

Console Output:

very nice!
Good as always.
Thanks for sharing!

Similar procedures should be followed for other entities / libraries.
Graphs also supports "embedded" images, the functionality is integrated to SG API graph object.
Images can be uploaded from your computer or linked from external sources.
Users who owns graphs which support permissions can allow others to administrate, publish or collaborate in them. Every perm level can assign permissions below it.
  • Owner
    • Assign all levels of permissions.
    • Full control over graph.
    • Full control over graph's content
  • Admin
    • Assign Publisher and Collaborator permissions.
    • Full control over graph's content.
    • Cannot delete graph.
  • Publisher
    • Assign Collaborator permissions.
    • Add new graphs contained in the one that the permission is on.Add new graphs contained in the one that the permission is on.
    • Publish or unpublish graph’s contents created by collaborators and himself.
  • Collaborator
    • Add new graphs contained in the one that the perm is on (unpublished).
This functionality is included in the graph object  for the entities which support it.
The concept of channels  it’s tightly tied to permissions, some graphs define channels, and ownership or admin rights over them also give the user permission to share or publish in them.
When a new graph is created, it also generate the channels that the entity define, and each channel allows certain graph entities to be published or shared as listed below.

Community defines:

  • <ID>-posts-<lang>  ->  allows: article, gallery, ogvideo, status, posts
  • <ID>-topics-<lang>  ->  allows: topics
  • <ID>-members  ->  allows: users
  • <ID>-brands  ->  allows: brands

Vertical defines:

  • <ID>-communities-<lang> -> allows: communities
  • <ID>-posts-<lang> -> allows: article, gallery, ogvideo, status, posts
  • <ID>-topics-<lang> -> allows: topics
  • <ID>-members -> allows: users
  • <ID>-brands -> allows: brands

User defines:

  • <ID>-self -> allows: topics, article, gallery, ogvideo, status, posts
  • <ID>-private -> allows: topics, article, gallery, ogvideo, status, posts

Section defines:

  • <ID>-<lang> -> allows: topics

Topic defines:

  • <ID>-<lang> -> allows: article, gallery, ogvideo, status, posts

LEGEND:

  • <ID> = replaced by the unique ID of the graph that represents the ‘root’ of the channel.
  • <lang> = replaced by an int, which indicates the language of the contents of the channel.


Code:
copy

var channels;
var page;
new Promise(function(resolve) {
    require(['libraries/graphs/channels'], function (model) {
        channels = new model.ChannelEntries('entries');
        resolve();
    });
})
.then(function() {
    page = channels.pages.get(1);

    page.bind('fetched', function (objects) {
        for (var i in objects) {
            var entry = objects[i];
            console.log(entry.graph.__proto__);
        }
    });
    page.fetch();
});

Console Output:

▶ Article {}
▶ Post {}
▶ OGVideo {}
▶ Article {}
▶ OGVideo {}
▶ Article {}
▶ Post {}
▶ Post {}
Users can send messages to each other, as part of conversations.
Conversations can involve 2 or more users of the same community, or be public (privacy is configurable).
Messages can carry graphs as attachments.
Conversation fileds:
  • ID
  • subject
  • lastMessage (message Object)
Message fields:
  • conversationID
  • text
  • sent
  • from
  • to
  • attachments (graph objects)

Getting messages:
copy

var inbox;
new Promise(function(resolve) {
    require(['libraries/graphs/inbox'], function (model) {
        inbox = new model.Conversations();
        resolve();
    });
})
.then(function() {
    /* Get first page of conversations for logged user */
    /* Logged User Community token */
    inbox.attributes.token = auth.sessions.community.token;
    /* Get attached graph object, = gets only IDs */
    inbox.attributes.attachment_data = 1;

    var page = inbox.pages.get(1); // inbox is CollectionPage
    page.bind('fetched', function(objects) {
        for (var i in objects) {
            console.log(objects[i]);
        }
    });
    page.fetch();
});
As you can see, every collection behaves the same way.


Sending messages:

var message;
new Promise(function(resolve) {
    require(['libraries/graphs/inbox'], function (model) {
        message = new model.Message();
    });
    resolve();
})
.then(function() {
    /* Send a message with an attachment */
    message.conversationID = conversation.ID;
    /* Target User Id(s), comma separated for multiple receivers */
    message.to = '536bad943033666bb09b4e16' // Target User Id
    message.text = 'Just testing messaging';
    /* Attached graph_id(s), comma separated for multiple attachments */
    message.attachments = '000000000000000000000006';

    /* Send message */
    message.send(function () {
        console.log('message sent');
    });
});
Every user receive notifications about relevant questions and has a newsfeed which shows information about his interests and his friends’ activity on per community basis.

Notifications

  • User receive notifications when:

    • A content is published / updated / shared on a owned or administered topic.

    • A content is published on a owned or administered community.

    • A content is published on a owned or administered network of communities.

    • A followed interests on a topic.

    • A user is interested on a owned or administered topic.

    • A followed start following another user.

    • A user start following you.

    • A comment is made in an content under a owned or administered topic.

    • Receive a permission.

    • A user joins a community owned or administered.

    • A user joins a community on a community network owned or administered.

    • A community is created on a community network owned or administered.

Newsfeed

  • User get a newsfeed entry when:

    • Publish / share a content.

    • A followed publish / share a content.

    • A topic of the user interest gets a new publication.

Both feeds (news and notifications) are SG API collections.
The SG API provides out-of-the-box user registration - login. Users are identified by e-mail address and each can have different accounts for different communities, this allow users to cross-share contents to different communities in which the user has enough rights (or to his 'self' channel).
Through the auth library, a user can register using his email address, after validation, an account for the email-community pair will be created.
Socites offers methods for registration. login, 'forgot password', and other useful actions. For each email registered, a 'cluster' is created, which allows the user to have multiple accounts for multiple communities (or community networks) using the same email, and making possible to share contents between different sites that the user access. (see Authentication)

Code:
copy

/* Sign In */
auth.session.signin('some@email.com', 'somePassword', callback);

/* Sign Out */
auth.session.signout(callback);

/* Register */
/* @TODO */
When contents are created or edited, they can be left in a 'draft' state, meaning that the user can keep preliminary or partial  versions (or editions) of the content without publishing it.
The functionality is integrated to the SG API graph object.
The fields that are full-text indexed on the entities are indexed using Apache Lucene.
There are several indexes allowing different search approaches and thus giving more flexibility to the functionality.
Search results are SG API collections.

Code:
copy

/* Coming Soon */
/* @TODO */
Communiverses entities can be configured in one of three ways:
  • Community: Regular communities, grouped with others by 'vertical'.
  • Self-Contained: A regular community but with the difference that's not a part of a vertical.
  • Vertical: Special case of community that serves as a backend for the communities that are grouped by it.
This entities, act as root of the sites hierarchy, and every graph has a property that determines to which community it belongs to (ds_id).
Communiverses also have a exclusive property that shows to which network of communities correspond (can be the unique ID for the 'Vertical' for the 'regular' communities, the self unique ID for the self-contained communities, or NULL for the networks of communities).