Custom card API
Adding JSX to page template cards
Unlike global custom cards, custom cards that are defined in a page template will have their HTML automatically added to the page on render.If you wish to add JSX to the rendered container instead use the replaceView method. This method is defined in the scope of the cards executing JavaScript code. Its first parameter can be a string of HTML, a DOM Node, or a ReactJS component. It takes a second optional parameter, where you can define the classNames, afterAdded, and beforeRemove options. See ctx.customPortlets.add for more information about these options.
Example usage:
replaceView("A new view", {classNames: 'my-awesome-portlet'})Note: replaceView is not available to global cards.
Dynamically adding cards to a page
All global cards run on every page. It is possible to add custom cards to a page template dynamically using the following API. This is helpful for cases when you want to add custom cards under specific conditions. For example, add a custom card to all calendar events on the "HR Calendar".
var page = ctx.customPortlets.getPage(); var currentParentId = page.treePath[page.treePath.length - 1]; if(hrCalendarId === currentParentId){ ctx.customPortlets.add(<TimeOffRequestForm />, { placement: tf.portlets.Placement.LaneCenter, position: tf.portlets.Position.Top, css: portletCss }); }
It is also possible to use this method to create page template cards that comprise of multiple cards in various locations.
ctx.customPortlets.add(view, options)
ctx.customPortlets.add('some <b>html</b> to show');
ctx.customPortlets.add('<blink>An important message!</blink>', { placement: tf.portlets.Placement.LaneCenter, position: tf.portlets.Position.Top, });
Note: SiteHeader is a new addition available in TF 9.1+
Parameters: It receives a single parameter, which DOM node the view was added to.
Parameters: It receives a single parameter, which DOM node the view will be removed from.
Global parameters
- portletId: The unique id of the portlet.
- portletConfig: The value from the custom portlet editor config field.
- portletConfigurationId: A unique Id for this portlet instance. Can be used for storing data.
- portletCss: The value from the custom portlet editor CSS field. For page template custom portlets, this is automatically added to the page on render.
- portletHtml: The result the server (C#) code defined on this portlet. For page template custom portlets, this value is automatically rendered to the page. Global portlets will need to manually add it using the API methods below.
JavaScript API
The following are other methods available for use that will assist in the development of custom cards. For advanced usage please also see Integrating with ThoughtFarmer's Flux actions and Communicating between custom cards with events.
ctx.customPortlets.remove(key)
Note: The same key value must have been passed to add on the options object. You do not need to call this unless you want to remove the view before the page changes. All portlets are automatically removed when the page changes.
ctx.customPortlets.addCss(key, css)
Adds the provided string of CSS globally to the site.
ctx.customPortlets.removeCss(key)
Remove the CSS added through ctx.customPortlet.addCss API method from the site.
ctx.customPortlets.hasRightLane()
ctx.customPortlets.getUser()
{ userId: 1, name: 'Bort Simpson', firstname: 'Bort', culture: 'en', profileImageUrl: '/profileimage/34679100000/2217/44x44/True/0,0,0,0/profileimage.jpg', isGuest: false, inAdminMode: false, allowedInAdminMode: true, archivedContentEnabled: true, securityTokens: [1, 3, 567, 567567], }
ctx.customPortlets.getPage()
{ contentId: 1, pageType: 1, treePath: [1, 2, 3], title: 'I am a page', tags: [{tagId: 1, name: 'some-tag'}, ...], updateDate: '2015-12-23T16:44:50Z', publishedDate: '2015-12-23T16:44:50Z' }
ctx.customPortlets.getUserState(key, callback)
Retrieves data for the currently logged in user previously stored under the given key. The callback receives two props, key and value. Value is always a string.
ctx.customPortlets.setUserState(key, value)
Stores some data server side for the currently logged in user under the given key. Values will be converted to a string when saving.
Note: This does not auto serialize objects into JSON. If you want to store an object, you must serialize it first.
ctx.customPortlets.getData(portletId, key, callback)
Retrieves data previously stored under the given key. The callback receives two parameters, the key and the value.
ctx.customPortlets.setData(portletId, key, value, callback)
Note: This does not auto serialize objects into JSON. If you want to store an object, you must serialize it first.
ctx.customPortlets.findCard(cardTypeId)
Finds the first card in the current page of the specified type. Returns its location in the page structure. The returned data structure looks like:
{placement: 1, position: 4}
Is useful for cases where you want to add a new card relative to the position of another card.
ctx.customPortlets.findAllCards(cardTypeId)
Finds all cards in the current page of the specified type. Returns their location in the page structure. The returned data structure looks like:
[{placement: 1, position: 4}, {placement: 2, position: 1}, ...]
ctx.customPortlets.triggerWebhook(webhookToken, options, callback)
Explicitly triggers a webhook to be sent. WebhookToken is available on the webhooks edit page. It is only available for webhooks using the trigger type "Activity." Options can contain the following values:
- contentId: The contentId of the page the webhook is being triggered for. This is required.
- eventName: The event that the event is being triggered for. This can be any string value. If it matches an ActivityType, the webhook message is generated as if the activity has just occurred. Example: PublishPage, EditPage. If not specified, this value is defaulted to custom. This value is passed along to the webhook destination and can be used to uniquely identify the message.
- commentId: An optional commentId to associate with the webhook. If eventName equals AddedComment, or is a custom value, the comment body is included in the webhook message.
- message: An additional text value to be included with the webhook body. If the webhook is send Slack messages, this is displayed as the message text.
Comments
0 comments
Please sign in to leave a comment.