Show:

Streams Class

Defined in: platform/plugins/Streams/web/js/Streams.js:4249
Module: Streams

Streams plugin's front end code

Methods

_connectSockets

(
  • refresh
)
private static

Defined in platform/plugins/Streams/web/js/Streams.js:478

Connects or reconnects sockets for all participating streams

Parameters:

_disconnectSockets

() private static

Defined in platform/plugins/Streams/web/js/Streams.js:507

Disconnects all Streams sockets which have been connected. Note that this also affects other plugins that might be listening on the sockets (maybe we should have another thing, I don't know, but for now it's ok).

actionUrl

(
  • publisherId
  • streamName
  • [what='stream']
)
String static

Defined in platform/plugins/Streams/web/js/Streams.js:519

A convenience method to get the URL of the streams-related action

Parameters:

  • publisherId String

    The id of the publisher

  • streamName String

    The name of the stream

  • [what='stream'] String optional

    Can be one of 'stream', 'message', 'relation', etc.

Returns:

String:

The corresponding URL

batchFunction

(
  • baseUrl
  • action
)
Function static

Defined in platform/plugins/Streams/web/js/Streams.js:712

Parameters:

Returns:

Function:

construct

(
  • fields
  • [extra={}]
  • [callback]
  • [updateCache=false]
)
Q.Stream static

Defined in platform/plugins/Streams/web/js/Streams.js:860

This function is similar to _activateTools in Q.js That one is to create "controllers" on the front end, and this one is to create "models" on the front end. They have very similar conventions.

Parameters:

  • fields Object

    Provide any stream fields here. Requires at least the "type" of the stream.

  • [extra={}] Object optional

    Can include "messages" and "participants"

  • [callback] Function optional

    The function to call when all constructors and event handlers have executed The first parameter is an error, in case something went wrong. The second one is the stream object.

  • [updateCache=false] Boolean optional

    Whether to update the Streams.get cache after constructing the stream

Returns:

Q.Stream:

create

(
  • fields
  • callback
  • [related]
  • [options]
)
static

Defined in platform/plugins/Streams/web/js/Streams.js:744

Create a new stream

Parameters:

  • fields Object

    Should contain at least the publisherId and type of the stream. Fields are passed to the Streams/stream POST handler. The attributes field can be an object.

  • callback Function 
    if there were errors, first parameter is the error message

    otherwise, first parameter is null and second parameter is a Streams.Stream object

  • [related] Object optional

    Optional information to add a relation from the newly created stream to another one. Can include:

    • [publisherId] String optional

      the id of whoever is publishing the related stream

    • [streamName] String optional

      the name of the related stream

    • [type] Mixed optional

      the type of the relation

  • [options] Object optional

    Any extra options involved in creating the stream

    • [fields] Object optional

      Used to override any fields passed in the request

    • [filename] String optional

      Overrides the default filename for file uploads

    • [form] HTMLElement optional

      If you want to upload a file or an icon, pass a form element here which includes input elements of type "file", named "file" or "icon". If they have files selected in them, they will be passed along with the rest of the fields. Setting this option will cause a call to Q.formPost which will load the result in an iframe. That resulting webpage must contain javascript to call the resultFunction.

    • [resultFunction=null] String optional

      The path to the function to handle inside the contentWindow of the resulting iframe, e.g. "Foo.result". Your document is supposed to define this function if it wants to return results to the callback's second parameter, otherwise it will be undefined

define

(
  • type
  • ctor
  • methods
)
static

Defined in platform/plugins/Streams/web/js/Streams.js:291

Call this function to define a stream type

Parameters:

  • type String

    The type of the stream, e.g. "Streams/smalltext"

  • ctor String | Function

    Your tool's constructor, or path to a javascript file which will define it

  • methods Object

    An optional hash of methods

displayType

(
  • type
)
String static

Defined in platform/plugins/Streams/web/js/Streams.js:4253

Try to figure out a displayable title from a stream's type

Parameters:

Returns:

String:

followup

(
  • options
)
static

Defined in platform/plugins/Streams/web/js/Streams.js:1274

Parameters:

  • options Object
    • [show="alert"] String optional

      Can be "alert" or "confirm", or empty

    • [mobile] Object optional
      • [numbers] Array optional
        The list of phone numbers to send to
      • [text] String optional
        Override template for sms body
      • [alert] String optional
        Override template for alert
      • [confirm] String optional
        Override template for confirmation dialog to continue
    • [email] Object optional
      • [addresses] Array optional
        The list of email addresses to send to
      • [subject] String optional
        Override template for subject
      • [body] String optional
        Override template for email body
      • [alert] String optional
        Override template for alert
      • [confirm] String optional
        Override template for confirmation dialog to continue
    • facebook Object
      • uids Array
        The facebook uids to send followup push notifications to messenger

get

(
  • publisherId
  • name
  • callback
  • [extra]
)
static

Defined in platform/plugins/Streams/web/js/Streams.js:579

Streams batch getter.

Parameters:

  • publisherId String

    Publisher's user id

  • name String

    Name of the stream published by this publisher

  • callback Function

    If there were errors, first parameter is an array of errors. Otherwise, first parameter is null and second parameter is a Streams.Stream object

  • [extra] Object optional

    Optional object which can include the following keys:

    • [participants=0] Number | Object optional

      Optionally fetch up to that many participants

    • [messages=0] Number | Object optional

      Optionally fetch up to that many latest messages

    • [messageType] String optional

      optional String specifying the type of messages to fetch

    • [withMessageTotals] Array optional

      an array of message types to get messageTotals for in the returned stream object

    • [withRelatedToTotals] Array optional

      an array of relation types to get relatedToTotals for in the returned stream object

    • [withRelatedFromTotals] Array optional

      an array of relation types to get relatedFromTotals for in the returned stream object

    • [cacheIfMissing] Boolean optional

      defaults to false. If true, caches the "missing stream" result.

    • [fields] Array optional

      the stream is obtained again from the server if any fields named in this array are == null

    • ["$Module_$fieldname"] Mixed optional

      any other fields you would like can be added, to be passed to your hooks on the back end

iconUrl

(
  • icon
  • [basename=40]
)
String static

Defined in platform/plugins/Streams/web/js/Streams.js:325

Calculate the url of a stream's icon

Parameters:

  • icon String

    the value of the stream's "icon" field

  • [basename=40] String | Number optional

    The last part after the slash, such as "50.png"

Returns:

String:

the url

invite

(
  • publisherId
  • streamName
  • [options]
  • callback
)
Q.Request static

Defined in platform/plugins/Streams/web/js/Streams.js:1147

Invite other users to a stream. Must be logged in first.

Parameters:

  • publisherId String

    The user id of the publisher of the stream

  • streamName String

    The name of the stream you are inviting to

  • [options] Object optional

    More options that are passed to the API, which can include:

    • [identifier] String | Array optional

      An email address or mobile number to invite. Might not belong to an existing user yet. Can also be an array of identifiers.

    • [token=false] Boolean optional

      Pass true here to generate an invite which you can then send to anyone however you like. When they show up with the token and presents it via "Q.Streams.token" querystring parameter, the Streams plugin will accept this invite either right away, or as soon as they log in. They will then be added to the list of Streams_Invited for this stream, thus keeping track of who accepted whose invite.

    • [appUrl] String optional

      Can be used to override the URL to which the invited user will be redirected and receive "Q.Streams.token" in the querystring.

    • [userId] String optional

      user id or an array of user ids to invite

    • [platform] String optional

      platform for which uids are passed

    • [uid] String optional

      uid or arary of uids to invite

    • [label] String optional

      label or an array of labels to invite, or tab-delimited string

    • [addLabel] String | Array optional

      label or an array of labels for adding publisher's contacts

    • [addMyLabel] String | Array optional

      label or an array of labels for adding logged-in user's contacts

    • [readLevel] String optional

      the read level to grant those who are invited

    • [writeLevel] String optional

      the write level to grant those who are invited

    • [adminLevel] String optional

      the admin level to grant those who are invited

    • [displayName] String optional

      Optionally override the name to display in the invitation for the inviting user

    • [callback] String optional

      Also can be used to provide callbacks, which are called before the followup.

    • [followup="future"] Boolean optional

      Whether to set up a followup email or sms for the user to send. Set to true to always send followup, or false to never send it. Set to "future" to send followups only to users who haven't registered yet.

    • [uri] String optional

      If you need to hit a custom "Module/action" endpoint

  • callback Function

    Called with (err, result) . In this way you can obtain the invite token, email addresses, etc. See Streams::invite on the PHP side for the possible return values. This is called before the followup flow.

Returns:

Q.Request:

represents the request that was made if an identifier was provided

isStream

(
  • value
)
Boolean static

Defined in platform/plugins/Streams/web/js/Streams.js:4264

Use this to check whether variable is a Q.Streams.Stream object

Parameters:

  • value Mixed

Returns:

Boolean:

key

(
  • publisherId
  • streamName
)
String static

Defined in platform/plugins/Streams/web/js/Streams.js:374

Calculate the key of a stream used internally for retaining and releasing

Parameters:

Returns:

String:

the key

refresh

(
  • callback
  • [options]
)
Boolean static

Defined in platform/plugins/Streams/web/js/Streams.js:1049

Refreshes all the streams the logged-in user is participating in If your app is using socket.io, then calling this manually is largely unnecessary.

Parameters:

  • callback Function

    optional callback

  • [options] Object optional

    A hash of options, including:

    • [messages] Boolean optional

      If set to true, then besides just reloading the stream, attempt to catch up on the latest messages

    • [max] Number optional

      The maximum number of messages to wait and hope they will arrive via sockets. Any more and we just request them again.

    • [duringEvents] Array optional

      Streams.refresh.options.duringEvents are the window events that can lead to an automatic refresh

    • [minSeconds] Number optional

      Streams.refresh.options.minEvents is the minimum number of seconds to wait between automatic refreshes

    • [timeout] Number optional

      The maximum amount of time to wait and hope the messages will arrive via sockets. After this we just request them again.

    • [unlessSocket] Number optional

      Whether to avoid doing any requests when a socket is attached

    • [changed=null] Object optional

      An Object of {fieldName: true} pairs naming fields to trigger change events for, even if their values stayed the same.

    • [evenIfNotRetained] Boolean optional

      If the stream wasn't retained (for example because it was missing last time), then refresh anyway

    • [extra] Object optional

      Any extra parameters to pass to the callback

Returns:

Boolean:

whether the refresh occurred

relate

(
  • publisherId
  • streamName
  • relationType
  • fromPublisherId
  • fromStreamName
  • [callback]
)

Defined in platform/plugins/Streams/web/js/Streams.js:3076

Relates streams to one another

Parameters:

  • publisherId String

    the publisher id of the stream to relate to

  • streamName String

    the name of the stream to relate to

  • relationType String

    the type of the relation, such as "parent" or "photo"

  • fromPublisherId String

    the publisher id of the stream to relate from

  • fromStreamName String

    the name of the stream to relate from

  • [callback] Function optional

    callback to call with the results First parameter is the error, the second will be relations data

release

(
  • key
)
static

Defined in platform/plugins/Streams/web/js/Streams.js:1110

Releases all retained streams under a given key. See Streams.retain() It also closes sockets corresponding to all the released streams, if they were the last streams to be retained on their respective nodes.

Parameters:

retainedByKey

(
  • publisherId
  • streamName
)
Boolean static

Defined in platform/plugins/Streams/web/js/Streams.js:1568

Detect whether stream retained

Parameters:

Returns:

Boolean:

Whether stream retained (true) or not (false)

retainWith

(
  • key
)
Object static

Defined in platform/plugins/Streams/web/js/Streams.js:1095

When a stream is retained, it is refreshed when Streams.refresh() or stream.refresh() are called. You can release it with stream.release(). Call this function in a chain before calling Streams.get, Streams.related, etc. in order to set the key for retaining the streams those functions obtain.

Parameters:

Returns:

Object:

returns Streams object for chaining with .get() or .related()

unrelate

(
  • publisherId
  • streamName
  • relationType
  • fromPublisherId
  • fromStreamName
  • [callback]
)
static

Defined in platform/plugins/Streams/web/js/Streams.js:3115

Removes relations from streams to one another

Parameters:

  • publisherId String

    the publisher id of the stream to relate to

  • streamName String

    the name of the stream to relate to

  • relationType String

    the type of the relation, such as "parent" or "photo"

  • fromPublisherId String

    the publisher id of the stream to relate from

  • fromStreamName String

    the name of the stream to relate from

  • [callback] Function optional

    callback to call with the results First parameter is the error, the second will be relations data

updateRelation

(
  • toPublisherId
  • toStreamName
  • relationType
  • fromPublisherId
  • fromStreamName
  • weight
  • adjustWeights
  • callback
)

Defined in platform/plugins/Streams/web/js/Streams.js:3153

Later we will probably make Streams.Relation objects which will provide easier access to this functionality. For now, use this to update weights of relations, etc.

Parameters:

Properties

ADMIN_LEVEL

Object

Defined in platform/plugins/Streams/web/js/Streams.js:232

Admin levels

ADMIN_LEVEL.invite

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:251

Able to create invitations for others, granting access and permissions up to what they themselves have

Default: 20

ADMIN_LEVEL.manage

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:259

Can approve posts, and give people any adminLevel < 'manage'

Default: 30

ADMIN_LEVEL.max

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:273

Max admin level

Default: 40

ADMIN_LEVEL.none

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:237

Cannot do anything related to admin / users

Default: 0

ADMIN_LEVEL.own

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:266

Can give people any adminLevel <= 'own'

Default: 40

ADMIN_LEVEL.tell

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:244

Can prove things about the stream's content or participants

Default: 10

READ_LEVEL

Object

Defined in platform/plugins/Streams/web/js/Streams.js:62

Read levels

READ_LEVEL.content

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:81

Can see the stream's content

Default: 20

READ_LEVEL.max

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:109

Max read level

Default: 40

READ_LEVEL.messages

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:102

Can play stream in a player

Default: 40

READ_LEVEL.none

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:67

Can't see the stream

Default: 0

READ_LEVEL.participants

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:95

Can see participants in the stream

Default: 30

READ_LEVEL.relations

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:88

Can see relations to other streams

Default: 25

READ_LEVEL.see

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:74

Can see icon and title

Default: 10

WRITE_LEVEL

Object

Defined in platform/plugins/Streams/web/js/Streams.js:126

Write levels

WRITE_LEVEL.close

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:201

Don't delete, just prevent any new changes to stream however, joining and leaving is still ok

Default: 40

WRITE_LEVEL.closePending

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:194

Can post a message requesting to close the stream

Default: 35

WRITE_LEVEL.edit

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:187

Can post messages to edit stream content immediately

Default: 30

WRITE_LEVEL.join

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:138

Can become a participant, chat, and leave

Default: 10

WRITE_LEVEL.max

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:209

Max write level

Default: 40

WRITE_LEVEL.messages

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:159

Can post messages which appear immediately

Default: 20

WRITE_LEVEL.none

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:131

Cannot affect stream or participants list

Default: 0

WRITE_LEVEL.postPending

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:152

Can post messages, but manager must approve

Default: 15

WRITE_LEVEL.relate

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:166

Can post messages relating other streams to this one

Default: 23

WRITE_LEVEL.relations

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:173

Can update properties of relations directly

Default: 25

WRITE_LEVEL.suggest

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:180

Can post messages requesting edits of stream

Default: 28

WRITE_LEVEL.vote

Integer final

Defined in platform/plugins/Streams/web/js/Streams.js:145

Can vote for a relation message posted to the stream.

Default: 13

Events

create.onError

Defined in platform/plugins/Streams/web/js/Streams.js:854

Occurs when Streams.create encounters an error trying to create a stream on the server

get.onError

Defined in platform/plugins/Streams/web/js/Streams.js:701

Occurs when Streams.get encounters an error loading a stream from the server

get.onStream

Defined in platform/plugins/Streams/web/js/Streams.js:706

Occurs when Streams.get constructs a stream loaded from the server

onAvatar

Defined in platform/plugins/Streams/web/js/Streams.js:448

Returns Q.Event that occurs when an avatar has been returned, possibly because it was refreshed. Any tools displaying an avatar should add a handler to this event, and refresh their avatar displays.

Event Payload:

  • userId String

    the id of the user whose avatar it is

onConstruct

Defined in platform/plugins/Streams/web/js/Streams.js:428

Returns Q.Event that occurs after a stream is constructed on the client side

Event Payload:

  • type String

    type of the stream being constructed on the client side

onError

Defined in platform/plugins/Streams/web/js/Streams.js:386

This event is fired if an error occurs in any Streams function

onInviteComplete

Defined in platform/plugins/Streams/web/js/Streams.js:471

Event occurs when the user enters their full name after following an invite, completing their registration

onInvitedDialog

Defined in platform/plugins/Streams/web/js/Streams.js:458

This event is fired when a dialog is presented to a newly invited user.

onInvitedUserAction

Defined in platform/plugins/Streams/web/js/Streams.js:464

This event is fired when the invited user takes the first action after entering their name. It is a good time to start playing any audio, etc.

onMessage

Defined in platform/plugins/Streams/web/js/Streams.js:403

Returns Q.Event that occurs after the system learns of a new message that was posted. The platform makes sure the ordinals come in the right order, for each stream. So you just have to handle the messages to update your tools, pages, etc. By the time this event happens, the platform has already taken any default actions for standard events such as "Streams/join", etc. so the stream and all caches are up-to-date, e.g. the participants include the newly joined participant, etc.

Event Payload:

  • type String

    type of the stream to which a message is posted, pass "" for all types

  • messageType String

    type of the message, pass "" for all types

onMessageUnseen

Defined in platform/plugins/Streams/web/js/Streams.js:417

Returns Q.Event that occurs on a message coming in that hasn't been seen yet. You can call .seen() on the message to mark it as seen, otherwise if no handlers mark it seen, some other code might show a badge for "unseen" messages.

Event Payload:

onRefresh

Defined in platform/plugins/Streams/web/js/Streams.js:436

Returns Q.Event that occurs when a stream is obtained via Streams.get() and gets pulled from the server again (whether it changed or not). If you just want to take some action whenever any field in the stream changes (via Stream.update() method, which is called for most standard Streams/ messages) then use the Streams.Stream.onFieldChanged event factory instead.

Event Payload:

  • type String

    type of the stream being refreshed on the client side

related.onError

Defined in platform/plugins/Streams/web/js/Streams.js:1562

Occurs when Streams.related encounters an error loading the response from the server