Jive Apps: Actions in RTE

Version 2

    Overview

     

    Jive for Teams and Jive 6 will allow apps to register !App experiences (OpenSocial Action Contributions) which can be invoked in the rich text editor (RTE), similar to @ mentions, but using the ! character. Once a user types a ! symbol, a pop-up similar to the existing @ mention pop-up will appear and show app actions which can be invoked via the RTE. If an action is invoked, the app will render within a modal dialog. The user will be able to interact with the app and perform some action that will return some data to be rendered in the RTE as HTML.

    Note: An RTE is not used for status messages, direct messages and for commenting against them, !app feature is available only where RTE is used for editing text.

     

    Summary of workflow:

    1. User App Mentions an app or app action link
    2. The app picker launches
    3. User selects an app action
    4. The app is rendered in a modal dialog, displaying the view, to be named by developer. If developer does not specify a view, Jive will attempt to launch a view called "embedded". Note, this can be a sub-view of embedded as well.
    5. The app loads and action callback runs, passing in the contents of the RTE via gadget selection
    6. When app is ready to close and return content to the RTE, it calls a method to return JSON back to the RTE
    7. The RTE interprets the returned JSON and inserts an app artifact - either an icon & link, or an image.
    8. When the content is rendered, the app renders the embedded experience in a model when by a user clicks on the app artifact.

     

    References:

     

    Sample XML

     

    Similar to action links in content, RTE action contributions are declared in an app's gadget.xml in the "ModulePrefs" section. One or more action contributions can be declared for each app.


    <Require feature="actions">
        <Param name="action-contributions">
           <![CDATA[
                <action id="org.salesforce.linkToCase"
                      path="jive/actions/rte"
                      label="Link to case"
                      view="embedded.link_to_case"
                      icon="http://www.example.com/images/link_to_case.gif" />
           ]]>
        </Param>
    </Require>
    <Require feature="embedded-experiences" />
    

     

    In this example, a Sales Force app is registering an RTE action to insert a link to a case within SalesForce. Once the action is invoked, the user will choose the case which will then be returned back to the RTE to be rendered as a link.

     

    • id: the ID of the action contribution, for use by the app as reference when the action is invoked. The id value should use a namespace.
    • path: the container action to register. for the rte, we are currently only supporting one path for all rte content - "jive/actions/rte"
    • label: a text label for the action. This can be internationalized by using the standard OpenSocial i18n format: label="__MSG_str__" where "str" matches a variable in a message bundle for the current locale. The first word of the action label should be capitalized and other words in lower case (except proper names).
    • view: the view of the app that should be launched when the action contribution is launched. Must be "embedded" or a sub-view of "embedded" (e.g. "embedded.manage_case") - see spec on gadget.views.ViewType
    • icon: a 16x16 icon associated with the action. It must be the full or relative URL to an icon, or reserved icon name (full details below).

     

    Launching an App from Search Result

    When an app action is launched by a user from the app action picker search results, Jive will pass context to the app using the same context passing mechanism. The selection object will contain a Jive Context (please refer to the Understanding App Selection and Embedded Context Reference  for definition and examples) describing the jive object context for which the RTE (and !app experience) is targeted.

     

    For example, if the !app experience was invoked while editing a document, the Jive Context included in the selection object will contain metadata pertaining to that document. Detail relating to the RTE itself will also be included in the Jive Context.

     

    The selection object made available to an app will be structured as follows (details of the Jive Context omitted):

     

    {
        jive: {
            content: {
                ..
            },
            rte: {
                ..
            }
        }
    }
    

    Returning Data from App to RTE

    Data may be returned from the app back to the container to render an artifact in the RTE. App developers must use the osapi.jive.core.container.closeApp() function which takes a data parameter. The data object parameter is a JavaScript object used to encode an macro into the RTE html, for the purposes of creating an artifact  which may (1) render a simple text or image, (2) create a simple hyperlink for navigating to a page within Jive or an external URL, or (3) invoke an embedded app experience.

     

    Example of invoking .closeApp with the data object:

     

    osapi.jive.core.container.closeApp({
    data: {
        display: {
            ..
        },
        target: {
            ..
        }
    }
    });
    

     

    Note:

    • The Artifact Display is required. Data objects omitting this property will not be encoded as an app artifact macro.
    • The Artifact Target is optional. If no target is specified, the artifact will be display-only.

     

    Please refer to the Artifact Display and Artifact Target sections of Understanding App Selection and Embedded Context Reference  to see how developers control the rendering and behavior app artifacts returned to the RTE. Any app-specific context (which is free-form developer-controlled JSON useful to the app when invoked in embedded experiences such as view) in the artifact target is encoded along with other metadata.

     

    Icon and previewImage values

    These can be absolute URLs or just relative paths. That is they should not start with a /. Relative paths should always be relative to the app's XML file not relative to where the HTML is.

    For example:

    <Content type="html" view="home,canvas" href="html/app.html" preferred_height="250" />

    in the app.html

     

    <img src="images/maps.png">


    does not mean html/images/maps.png but ../images/maps.png.

     

    Upon submitting the text being edited in the RTE, Jive will make a copy of icon and preview image URLs in local storage and embed a URL to it in the content. So the next time same content is edited the HTML view of it will reveal the local path where the image is stored. By making a copy the app's hosted location is freed from image fetch requests and also solves two other issues

    1. http/https mixed mode errors if the hosted location of image is http.
    2. Document history will actually show a history of previous images that were used.

     

    Rendering App Artifacts when Viewing Content

    App artifacts dropped into the RTE are visible on Jive content such as documents, discussions, and comments, once the RTE is saved, and the content object is loaded for viewing. As described above, developers may control the way artifacts are rendered, and the manner in which users may be interact with the app artifact.

    If the artifact is configured to invoke an embedded experience, Jive will make context available to the app via opensocial data context. Developers may retrieve this context by registering a listener which is called when  the container sets the context for their app (on user invocation of the embedded experience).

     

    gadgets.util.registerOnLoadHandler(function() {
    
         // register a listener for embedded experience context
         opensocial.data.getDataContext().registerListener('org.opensocial.ee.context', function(key) {
              var data = opensocial.data.getDataContext().getDataSet(key);
    
              // ... do something with context ..
    var jira_id = data.target.context.jira_id;
    display_jira( jira_id );
         });
    });
    

     

    The app must require the "embedded-experienes" feature in their app gadget XML:

     

         <Require feature="embedded-experiences" />
    

     

    The context object will contain properties for Jive Context and Artifact Target (see these sections in the Understanding App Selection and Embedded Context Reference):

    • The Jive Context describes the content object which contains the app artifact (from which the embedded experience was invoked).
    • The Artifact Target may contain a context property which was encoded into the artifact when it was dropped by the app on invoking osapi.jive.core.container.closeApp(). App developers may use this context to inform the context interaction with Jive object before.

     

    Example context object (details omitted):

     

    {
        jive: {
         ..
        },
    target: {
      ..
      context: {
    jira_id: "JIVE-1000"
    }
      }
    }
    

     

    To allow Jive to pass the context back to the application, the application developers have to add "embedded" view to handle rendering of the application when viewing the document. This special view will be invoked only when the initial artifact passed back has type "embed" (see  Understanding App Selection and Embedded Context Reference).

     

    Rendering App Artifacts in Mobile, Outlook, and other alternative clients

    If the app returned a url in the data, it should render a standard HTML link to the url. If the app returned context and view but did not return a url, render a static text / image.

     

    Editing existing App Artifacts

    Users may wish to edit an app artifact, while inside the RTE in edit mode. When the edit link is invoked, Jive will invoke the same app action that was used to create the app artifact, and pass context into the app via gadget selection.

     

    The selection object will be structure as follows (seeUnderstanding App Selection and Embedded Context Reference for details):

     

    {
        jive: {
            content: {
                ..
            },
            rte: {
                ..
            }
    },
    display: {
    ..
    },
    target: {
    ..
    }
    }
    

     

    • Action Display and Action Target will inform the app about the current appearance and behavior of the artifact, which will be replaced .onClose(). Developers may choose to mutate these properties, or replace them entirely when dropping back to the RTE.

     

    Testing apps