Understanding App Selection and Embedded Context Reference

Version 3


    Jive Context

    Where is the app placed, in which jive object?

    Structure

     

    contentContent ContextRequired property describing the type and ID of the Jive object to which the embedded artifact exists within or will be added to.
    rteRTE ContextIf an app is launched from within an RTE, Jive Context MAY contain additional detail about the state of the RTE when the app was launched.

     

    RTE Context


    htmlBodyString
    Required, contains the current HTML contents of the RTE from which the app was invoked. May be empty.

     

    Content Context

     

    idStringRequired, non-empty property representing a Jive object ID. If that object is not yet persisted (eg. working with a new Jive Document, Comment, etc.) this value may be "0", indicating that the object is new.If the Jive object has already been persisted (eg. is not new), this value maybe non-zero.0
    typeString

    Required, non-empty property representing a Jive object type.
    May be one of the Classes published in the JS API for Jive Apps Documentation

    (such as, osapi.jive.corev3.contents.Document, osapi.jive.corev3.contents.Comment)

    parentContent ContextOptional. Describes the ultimate parent of the Jive Object represented by the id and type of this Current Context. "Parent" represents the object of which the discussion is about. This value only applies when this Content Context is found anywhere within the discussion tree.
    inReplyToContent ContextOptional. Describes the immediate parent of the Jive Object represented by the id and type of this Current Context. "InReplyTo" represents the JiveObject immediately preceding the current object in the discussion tree. This value only applies when this Content Context is found deep within the discussion tree. When replying to the "parent" object, this property is not present.

     

    Examples Action Contribution Selection when viewing content (partial, direction: container -> app)

     

    jive: {
        content: {
            id: 1234,
            type: "osapi.jive.corev3.contents.Document"
        }
    }
    
    

     

    RTE Action Contribution Selection when creating a document (partial, direction: container's RTE -> app)


    jive: {
         content: {
             id: 0,
             type: "osapi.jive.corev3.contents.Document"
         },
         rte: {
             htmlBody: "<p>Document content</p>"
         }
    }
    
    


    RTE Action Contribution Selection when editing a document (partial, direction: Container's RTE -> app)


    jive: {
        content: {
            id: 1234,
            type: "osapi.jive.corev3.contents.Document"
       },
        rte: {
            htmlBody: "<p>Document content</p>"
        }
    }
    
    


    RTE Action Contribution Selection when creating a root reply comment to a document (partial, direction: Container's RTE -> app)


    jive: {
        content: {
            id: 0,
            type: "osapi.jive.corev3.contents.Comment",
            parent: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            }
        },
        rte: {
            htmlBody: "<p>Creating a comment</p>"
        }
    }
    
    


    RTE Action Contribution Selection when editing a root reply comment to a document (partial, direction Container's RTE -> app)

    1. jive: {
    2.     content: {
    3.         id: 5678,
    4.         type: "osapi.jive.core.Comment",
    5.         parent: {
    6.             id: 1234,
    7.             type: "osapi.jive.core.Document"
    8.         }
    9.     },
    10.     rte: {
    11.         htmlBody: "<p>Editing a comment</p>"
    12.     }
    13. }

     

    RTE Action Contribution Selection when creating a secondary reply comment to another comment on a document (partial, direction: Container's RTE -> app)

     

    jive: {
        content: {
            id: 0,
            type: "osapi.jive.corev3.contents.Comment",
            inReplyTo: {
                id: 5678,
                type: "osapi.jive.corev3.contents.Comment"
            },
            parent: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            }
        },
        rte: {
            htmlBody: "<p>Creating a comment</p>"
        }
    }
    
    


    RTE Action Contribution Selection when editing a secondary reply comment to another comment on a document (partial, direction: Container's RTE -> app)


    jive: {
        content: {
            id: 9012,
            type: "osapi.jive.corev3.contents.Comment",
            inReplyTo: {
                id: 5678,
                type: "osapi.jive.corev3.contents.Comment"
            },
            parent: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            }
        },
        rte: {
            htmlBody: "<p>Editing a comment</p>"
        }
    }
    
    


    Embedded experience context within a document when viewing content  (partial, direction: Container -> app)

     

    jive: {
        content: {
            id: 1234,
            type: "osapi.jive.corev3.contents.Document"
        }
    }
    
    


    Embedded experience context within a root reply when viewing content  (partial, direction: Container -> app)


    jive: {
        content: {
            id: 5678,
            type: "osapi.jive.corev3.contents.Comment",
            parent: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            }
        }
    }
    
    


    Embedded experience context within a secondary reply when viewing content  (partial, direction: Container -> app)


    jive: {
        content: {
            id: 9012,
            type: "osapi.jive.corev3.contents.Comment",
            inReplyTo: {
                id: 5678,
                type: "osapi.jive.corev3.contents.Comment"
            },
            parent: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            }
        }
    }
    
    

     

     

    Artifact Display

    How is the artifact is displayed?

     

    Structure

    To express an artifact displayed as a image

     

    typeStringRequired, must be "image"
    previewImageURLRequired. MAY be relative to app gadget.xml, or absolute or base64 encoded image data.Relative URLs  should not start with a /. Relative paths should always be relative to the app's XML file not relative to where the HTML is.
    labelStringOptional. If specified, becomes tooltip.

     

    To express an artifact displayed as text

     

    typeStringRequired, must be "text"
    iconURLOptional. If specified, the icon image is displayed before label. MAY be relative to app gadget.xml, or absolute.Relative URLs  should not start with a /. Relative paths should always be relative to the app's XML file not relative to where the HTML is.
    labelStringRequired. Becomes link text.

     

    Examples


    Artifact to be rendered as a an image with a tooltip (partial, direction: app -> Container, Container's RTE -> app, and Container -> app)
    Note the relative URL used for the previewImage


    display: {
        type: "image",
        previewImage: "images/preview-128x128.png",
        label: "This is a tooltip."
    }
    
    


    Artifact to be rendered as text, with icon (partial, direction: app -> Container, Container's RTE -> app, and Container -> app)
    Note the relative URL used for the icon


    display: {
        type: "text",
        icon: "images/icon-16x16.png",
        label: "This is the artifact text."
    }
    
    


    Artifact to be rendered as text, without icon (partial, direction: app -> Container, Container's RTE -> app, and Container -> app)

     

    display: {
        type: "text",
        label: "This is the artifact text."
    }
    
    


    Note: See Icon and previewImage values section in Jive Apps: Actions in RTE for an explanation about relative URLs.


    Artifact Target

    What does the artifact do for the user (when invoked)?


    Structure

    To express an artifact which opens a webpage


    typeStringRequired, must be "url"
    urlURLRequired. MAY be relative to app gadget.xml, or absolute.


    To express an artifact which opens an embedded experience

    typeStringRequired, must be "embed"
    viewStringOptional. Default to "embedded" for now.
    contextObjectOptional. Unstructured JSON which is governed by the app.

     

    Examples


    Artifact which opens up a webpage when invoked (partial, direction: app -> Container, Container's RTE -> app, and Container -> app)

     

    target: {
        type: "url",
        url: "http://www.jivesoftware.com"
    }
    
    

     

    Artifact which produces an embedded app experience when invoked (partial, direction: app -> Container, Container's RTE -> app, and Container -> app)

     

    target: {
        type: "embed",
        view: "embedded.view_issue",
        context: {
            issueId: "1005"
        }
    }
    
    

    Complete Examples

    The examples in the sections above highlight details of the data that is passed around in various situations. They do not provide a complete picture of the data structures in which these properties live. Listed below are several complete examples of the data passed to or returned from apps when viewing and manipulating app artifacts.

     

    Complete artifact passed as selection when creating an artifact when creating a document (direction: Container's RTE -> app)

     

    selection = {
        jive: {
            content: {
                id: 0,
                type: "osapi.jive.corev3.contents.Document"
            },
            rte: {
                htmlBody: "<p>Document content</p>"
            }
        }
    };
    
    


    Complete artifact passed as selection when creating an artifact when editing a document (direction: Container's RTE -> app)

     

    selection = {
        jive: {
            content: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            },
            rte: {
                htmlBody: "<p>Document content</p>"
            }
        }
    };
    
    


    Complete artifact passed as selection when editing an artifact when creating a document (direction: Container's RTE -> app)

     

    selection = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 0,
                type: "osapi.jive.corev3.contents.Document"
            },
            rte: {
                htmlBody: "<p>Document content</p>"
            }
        }
    };
    
    


    Complete artifact passed as selection when editing an artifact when editing a document (direction: Container's RTE -> app)

     

    selection = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            },
            rte: {
                htmlBody: "<p>Document content</p>"
            }
        }
    };
    
    

     

    Complete artifact passed as selection when creating an artifact when creating a root reply (direction: Container's RTE -> app)

     

    selection = {
        jive: {
            content: {
                id: 0,
                type: "osapi.jive.corev3.contents.Comment",
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Creating a comment</p>"
            }
        }
    };
    
    


    Complete artifact passed as selection when creating an artifact when editing a root reply (direction: Container's RTE -> app)

     

    selection = {
        jive: {
            content: {
                id: 9012,
                type: "osapi.jive.corev3.contents.Comment",
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Editing a comment</p>"
            }
        }
    };
    
    


    Complete artifact passed as selection when editing an artifact when creating a root reply (direction: Container's RTE -> app)

     

    selection = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 0,
                type: "osapi.jive.corev3.contents.Comment",
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Creating a comment</p>"
            }
        }
    };
    
    


    Complete artifact passed as selection when editing an artifact when editing a root reply (direction: Container's RTE -> app)

     

    selection = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 9012,
                type: "osapi.jive.corev3.contents.Comment",
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Editing a comment</p>"
            }
        }
    };
    
    

     

    Complete artifact passed as selection when creating an artifact when creating a secondary reply (direction: Container's RTE -> app)

     

    selection = {
        jive: {
            content: {
                id: 0,
                type: "osapi.jive.corev3.contents.Comment",
                inReplyTo: {
                    id: 5678,
                    type: "osapi.jive.corev3.contents.Comment"
                },
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Creating a comment</p>"
            }
        }
    };
    
    

     

     

    Complete artifact passed as selection when creating an artifact when editing a secondary reply (direction: Container's RTE -> app)

     

    selection = {
        jive: {
            content: {
                id: 9012,
                type: "osapi.jive.corev3.contents.Comment",
                inReplyTo: {
                    id: 5678,
                    type: "osapi.jive.corev3.contents.Comment"
                },
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Editing a comment</p>"
            }
        }
    };
    
    

     

    Complete artifact passed as selection when editing an artifact when creating a secondary reply (direction: Container's RTE -> app)

     

    selection = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 0,
                type: "osapi.jive.corev3.contents.Comment",
                inReplyTo: {
                    id: 5678,
                    type: "osapi.jive.corev3.contents.Comment"
                },
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Creating a comment</p>"
            }
        }
    };
    
    

     

    Complete artifact passed as selection when editing an artifact when editing a secondary reply (direction: Container's RTE -> app)

     

    selection = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 9012,
                type: "osapi.jive.corev3.contents.Comment",
                inReplyTo: {
                    id: 5678,
                    type: "osapi.jive.corev3.contents.Comment"
                },
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            },
            rte: {
                htmlBody: "<p>Editing a comment</p>"
            }
        }
    };
    
    

     

    Complete artifact passed as the close parameter when creating or editing an image artifact that opens a web page (direction: app -> Container's RTE)

     

    osapi.jive.core.container.closeApp({
        data: {
            display: {
                type: "image",
                previewImage: "images/preview-128x128.png",
                label: "This is a tooltip."
            },
            target: {
                type: "url",
                view: "http://bugtrack.mydomain.com/issue/1005"
            }
        }
    });
    
    

     

    Complete artifact passed as the close parameter when creating or editing a text artifact that opens a web page (direction: app -> Container's RTE)

     

    osapi.jive.core.container.closeApp({
        data: {
            display: {
                type: "text",
                label: "open this issue"
            },
            target: {
                type: "url",
                view: "http://bugtrack.mydomain.com/issue/1005"
            }
        }
    });
    
    

     

    Complete artifact passed as the close parameter when creating or editing a text artifact that opens a web page with an icon (direction: app -> Container's RTE)

     

    osapi.jive.core.container.closeApp({
        data: {
            display: {
                type: "text",
                label: "open this issue",
                icon: "images/icon-16x16.png"
            },
            target: {
                type: "url",
                view: "http://bugtrack.mydomain.com/issue/1005"
            }
        }
    });
    
    

     

    Complete artifact passed as the close parameter when creating or editing an image artifact that opens an embedded experience (direction: app -> Container's RTE)

     

    osapi.jive.core.container.closeApp({
        data: {
            display: {
                type: "image",
                previewImage: "images/preview-128x128.png",
                label: "This is a tooltip."
            },
            target: {
                type: "embed",
                view: "embedded.view_issue",
                context: {
                    issueId: "1005"
                }
            }
        }
    });
    
    

     

    Complete artifact passed as the close parameter when creating or editing a text artifact that opens an embedded experience (direction: app -> Container's RTE)

     

    osapi.jive.core.container.closeApp({
        data: {
            display: {
                type: "text",
                label: "open this issue"
            },
            target: {
                type: "embed",
                view: "embedded.view_issue",
                context: {
                    issueId: "1005"
                }
            }
        }
    });
    
    


    Complete artifact passed as the close parameter when creating or editing a text artifact with an icon that opens an embedded experience (direction: app -> Container's RTE)

     

    osapi.jive.core.container.closeApp({
        data: {
            display: {
                type: "text",
                label: "open this issue",
                icon: "images/icon-16x16.png"
            },
            target: {
                type: "embed",
                view: "embedded.view_issue",
                context: {
                    issueId: "1005"
                }
            }
        }
    });
    
    


    Complete artifact passed as context when viewing an embedded experience within a document (direction: container -> app)

     

    context = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 1234,
                type: "osapi.jive.corev3.contents.Document"
            }
        }
    };
    
    

     

    Complete artifact passed as context when viewing an embedded experience within a root reply to a document (direction: container -> app)

     

    context = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 5678,
                type: "osapi.jive.corev3.contents.Comment",
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            }
        }
    };
    
    

     

    Complete artifact passed as context when viewing an embedded experience within a secondary reply to a document (direction: container -> app)

     

    context = {
        display: {
            type: "image",
            previewImage: "images/preview-128x128.png",
            label: "This is a tooltip."
        },
        target: {
            type: "embed",
            view: "embedded.view_issue",
            context: {
                issueId: "1005"
            }
        },
        jive: {
            content: {
                id: 9012,
                type: "osapi.jive.corev3.contents.Comment",
                inReplyTo: {
                    id: 5678,
                    type: "osapi.jive.corev3.contents.Comment"
                },
                parent: {
                    id: 1234,
                    type: "osapi.jive.corev3.contents.Document"
                }
            }
        }
    };