docs/jscripts/opensocial/activity.js

   1 /*
   2  * Licensed under the Apache License, Version 2.0 (the "License");
   3  * you may not use this file except in compliance with the License.
   4  * You may obtain a copy of the License at
   5  *
   6  *     http://www.apache.org/licenses/LICENSE-2.0
   7  *
   8  * Unless required by applicable law or agreed to in writing, software
   9  * distributed under the License is distributed on an "AS IS" BASIS,
  10  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11  * See the License for the specific language governing permissions and
  12  * limitations under the License.
  13  */
  14
  15 /**
  16  * @class
  17  * Representation of an activity.
  18  *
  19  * <p>Activities are rendered with a title and an optional activity body.</p>
  20  *
  21  * <p>You may set the title and body directly as strings when calling
  22  * opensocial.newActivity. However, it is usually beneficial to create activities using
  23  * Message Templates for the title and body.</p>
  24  *
  25  * <p>Users will have many activities in their activity streams, and containers
  26  * will not show every activity that is visible to a user. To help display
  27  * large numbers of activities, containers will summarize a list of activities
  28  * from a given source to a single entry.</p>
  29  *
  30  * <p>You can provide Activity Summaries to customize the text shown when
  31  * multiple activities are summarized. If no customization is provided, a
  32  * container may ignore your activities altogether or provide default text
  33  * such as "Bob changed his status message + 20 other events like this."</p>
  34  * <ul>
  35  *  <li>Activity Summaries will always summarize around a specific key in a
  36  *   key/value pair. This is so that the summary can say something concrete
  37  *   (this is clearer in the example below).</li>
  38  *  <li>Other variables will have synthetic "Count" variables created with
  39  *   the total number of items summarized.</li>
  40  *  <li>Message ID of the summary is the message ID of the main template + ":" +
  41  *   the data key</li>
  42  * </ul>
  43  *
  44  * <p>Example summaries:
  45  * <pre>
  46  * &lt;messagebundle&gt;
  47  *   &lt;msg name="LISTEN_TO_THIS_SONG:Artist"&gt;
  48  *     ${Subject.Count} of your friends have suggested listening to songs
  49  *     by ${Artist}!
  50  *   &lt;/msg&gt;
  51  *   &lt;msg name="LISTEN_TO_THIS_SONG:Song"&gt;
  52  *     ${Subject.Count} of your friends have suggested listening to ${Song}
  53  *   !&lt;/msg&gt;
  54  *   &lt;msg name="LISTEN_TO_THIS_SONG:Subject"&gt;
  55  *    ${Subject.DisplayName} has recommended ${Song.Count} songs to you.
  56  *   &lt;/msg&gt;
  57  * &lt;/messagebundle&gt;
  58  * </pre></p>
  59  *
  60  * <p>
  61  * <b>See also:</b>
  62  * <a href="opensocial.Message.html">opensocial.Message</a>,
  63  * <a href="opensocial.html#newActivity">opensocial.newActivity()</a>,
  64  * <a href="opensocial.html#requestCreateActivity">
  65  * opensocial.requestCreateActivity()</a>
  66  *
  67  * @name opensocial.Activity
  68  */
  69
  70
  71 /**
  72  * Base interface for all activity objects.
  73  *
  74  * Private, see opensocial.createActivity() for usage.
  75  *
  76  * @param {Map.&lt;opensocial.Activity.Field, Object&gt;} params
  77  *    Parameters defining the activity
  78  * @private
  79  * @constructor
  80  */
  81 opensocial.Activity = function() {};
  82
  83
  84 /**
  85  * @static
  86  * @class
  87  * All of the fields that activities can have.
  88  *
  89  * <p>It is only required to set one of TITLE_ID or TITLE. In addition, if you
  90  * are using any variables in your title or title template,
  91  * you must set TEMPLATE_PARAMS.</p>
  92  *
  93  * <p>Other possible fields to set are: URL, MEDIA_ITEMS, BODY_ID, BODY,
  94  * EXTERNAL_ID, PRIORITY, STREAM_TITLE, STREAM_URL, STREAM_SOURCE_URL,
  95  * and STREAM_FAVICON_URL.</p>
  96  *
  97  * <p>Containers are only required to use TITLE_ID or TITLE, they may ignore
  98  * additional parameters.</p>
  99  *
 100  * <p>
 101  * <b>See also:</b>
 102  * <a
 103  * href="opensocial.Activity.html#getField">opensocial.Activity.getField()</a>
 104  * </p>
 105  *
 106  * @name opensocial.Activity.Field
 107  */
 108 opensocial.Activity.Field = {
 109   /**
 110    * <p>A string specifying the title template message ID in the gadget
 111    *   spec.</p>
 112    *
 113    * <p>The title is the primary text of an activity.</p>
 114    *
 115    * <p>Titles may only have the following HTML tags: &lt;b&gt; &lt;i&gt;,
 116    * &lt;a&gt;, &lt;span&gt;.
 117    * The container may ignore this formatting when rendering the activity.</p>
 118    *
 119    * <p>This field may be used interchangeably with the string 'titleId'.</p>
 120    *
 121    * @member opensocial.Activity.Field
 122    */
 123   TITLE_ID : 'titleId',
 124
 125   /**
 126    * <p>A string specifying the primary text of an activity.</p>
 127    *
 128    * <p>Titles may only have the following HTML tags: &lt;b&gt; &lt;i&gt;,
 129    * &lt;a&gt;, &lt;span&gt;.
 130    * The container may ignore this formatting when rendering the activity.</p>
 131    *
 132    * <p>This field may be used interchangeably with the string 'title'.</p>
 133    *
 134    * @member opensocial.Activity.Field
 135    */
 136   TITLE : 'title',
 137
 138   /**
 139    * <p>A map of custom key/value pairs associated with this activity.
 140    * These will be used for evaluation in templates.</p>
 141    *
 142    * <p>The data has type <code>Map&lt;String, Object&gt;</code>. The
 143    * object may be either a String or an opensocial.Person.</p>
 144    *
 145    * <p>When passing in a person with key PersonKey, can use the following
 146    * replacement variables in the template:</p>
 147    * <ul>
 148    *  <li>PersonKey.DisplayName - Display name for the person</li>
 149    *  <li>PersonKey.ProfileUrl. URL of the person's profile</li>
 150    *  <li>PersonKey.Id -  The ID of the person</li>
 151    *  <li>PersonKey - Container may replace with DisplayName, but may also
 152    *     optionally link to the user.</li>
 153    * </ul>
 154    *
 155    * <p>This field may be used interchangeably with the string
 156    * 'templateParams'.</p>
 157    *
 158    * @member opensocial.Activity.Field
 159    */
 160   TEMPLATE_PARAMS : 'templateParams',
 161
 162   /**
 163    * <p>A string specifying the URL that represents this activity.</p>
 164    *
 165    * <p>This field may be used interchangeably with the string 'url'.</p>
 166    *
 167    * @member opensocial.Activity.Field
 168    */
 169   URL : 'url',
 170
 171   /**
 172    * <p>Any photos, videos, or images that should be associated
 173    * with the activity. Higher priority ones are higher in the list.
 174    * The data has type <code>Array&lt;
 175    * <a href="opensocial.MediaItem.html">MediaItem</a>&gt;</code>.</p>
 176    *
 177    * <p>This field may be used interchangeably with the string 'mediaItems'.</p>
 178    *
 179    * @member opensocial.Activity.Field
 180    */
 181   MEDIA_ITEMS : 'mediaItems',
 182
 183   /**
 184    * <p>A string specifying the body template message ID in the gadget spec.</p>
 185    *
 186    * <p>The body is an optional expanded version of an activity.</p>
 187    *
 188    * <p>Bodies may only have the following HTML tags: &lt;b&gt; &lt;i&gt;,
 189    * &lt;a&gt;, &lt;span&gt;.
 190    * The container may ignore this formatting when rendering the activity.</p>
 191    *
 192    * <p>This field may be used interchangeably with the string 'bodyId'.</p>
 193    *
 194    * @member opensocial.Activity.Field
 195    */
 196   BODY_ID : 'bodyId',
 197
 198   /**
 199    * <p>A string specifying an optional expanded version of an activity.</p>
 200    *
 201    * <p>Bodies may only have the following HTML tags: &lt;b&gt; &lt;i&gt;,
 202    * &lt;a&gt;, &lt;span&gt;.
 203    * The container may ignore this formatting when rendering the activity.</p>
 204    *
 205    * <p>This field may be used interchangeably with the string 'body'.</p>
 206    *
 207    * @member opensocial.Activity.Field
 208    */
 209   BODY : 'body',
 210
 211   /**
 212    * <p>An optional string ID generated by the posting application.</p>
 213    *
 214    * <p>This field may be used interchangeably with the string 'externalId'.</p>
 215    *
 216    * @member opensocial.Activity.Field
 217    */
 218   EXTERNAL_ID : 'externalId',
 219
 220   /**
 221    * <p>A string specifing the title of the stream.</p>
 222    *
 223    * <p>This field may be used interchangeably with the string
 224    * 'streamTitle'.</p>
 225    *
 226    * @member opensocial.Activity.Field
 227    */
 228   STREAM_TITLE : 'streamTitle',
 229
 230   /**
 231    * <p>A string specifying the stream's URL.</p>
 232    *
 233    * <p>This field may be used interchangeably with the string 'streamUrl'.</p>
 234    *
 235    * @member opensocial.Activity.Field
 236    */
 237   STREAM_URL : 'streamUrl',
 238
 239   /**
 240    * <p>A string specifying the stream's source URL.</p>
 241    *
 242    * <p>This field may be used interchangeably with the string
 243    * 'streamSourceUrl'.</p>
 244    *
 245    * @member opensocial.Activity.Field
 246    */
 247   STREAM_SOURCE_URL : 'streamSourceUrl',
 248
 249   /**
 250    * <p>A string specifying the URL for the stream's favicon.</p>
 251    *
 252    * <p>This field may be used interchangeably with the string
 253    * 'streamFaviconUrl'.</p>
 254    *
 255    * @member opensocial.Activity.Field
 256    */
 257   STREAM_FAVICON_URL : 'streamFaviconUrl',
 258
 259   /**
 260    * <p>A number between 0 and 1 representing the relative priority of
 261    * this activity in relation to other activities from the same source</p>
 262    *
 263    * <p>This field may be used interchangeably with the string 'priority'.</p>
 264    *
 265    * @member opensocial.Activity.Field
 266    */
 267   PRIORITY : 'priority',
 268
 269   /**
 270    * <p>A string ID that is permanently associated with this activity.
 271    * This value can not be set.</p>
 272    *
 273    * <p>This field may be used interchangeably with the string 'id'.</p>
 274    *
 275    * @member opensocial.Activity.Field
 276    */
 277   ID : 'id',
 278
 279   /**
 280    * <p>The string ID of the user who this activity is for.
 281    * This value can not be set.</p>
 282    *
 283    * <p>This field may be used interchangeably with the string 'userId'.</p>
 284    *
 285    * @member opensocial.Activity.Field
 286    */
 287   USER_ID : 'userId',
 288
 289   /**
 290    * <p>A string specifying the application that this activity is associated
 291    * with. This value can not be set.</p>
 292    *
 293    * <p>This field may be used interchangeably with the string 'appId'.</p>
 294    *
 295    * @member opensocial.Activity.Field
 296    */
 297   APP_ID : 'appId',
 298
 299   /**
 300    * <p>A string specifying the time at which this activity took place
 301    * in milliseconds since the epoch.
 302    * This value can not be set.</p>
 303    *
 304    * <p>This field may be used interchangeably with the string 'postedTime'.</p>
 305    *
 306    * @member opensocial.Activity.Field
 307    */
 308   POSTED_TIME : 'postedTime'
 309 };
 310
 311
 312 /**
 313  * Gets an ID that can be permanently associated with this activity.
 314  *
 315  * @return {String} The ID
 316  * @member opensocial.Activity
 317  */
 318 opensocial.Activity.prototype.getId = function() {};
 319
 320
 321 /**
 322  * Gets the activity data that's associated with the specified key.
 323  *
 324  * @param {String} key The key to get data for;
 325  *   see the <a href="opensocial.Activity.Field.html">Field</a> class
 326  * for possible values
 327  * @param {Map.&lt;opensocial.DataRequest.DataRequestFields, Object&gt;}
 328  *  opt_params Additional
 329  *    <a href="opensocial.DataRequest.DataRequestFields.html">params</a>
 330  *    to pass to the request.
 331  * @return {String} The data
 332  * @member opensocial.Activity
 333  */
 334 opensocial.Activity.prototype.getField = function(key, opt_params) {};
 335
 336 /**
 337  * Sets data for this activity associated with the given key.
 338  *
 339  * @param {String} key The key to set data for
 340  * @param {String} data The data to set
 341  */
 342 opensocial.Activity.prototype.setField = function(key, data) {};