Embedded confluence public - Api references

API References

navigationPolicy

navigationPolicy description

Both ViewPage and EditPage components accept navigationPolicy prop. This is the prop 3rd parties can provide their implementation of handling a navigation request based on URL.

navigationPolicy definition

The navigation policy includes an optional shimUrl, domainNamesToReplace and a navigate function.

{
  shimUrl?: string;
  navigate?: (url, modifiers, defaultNavigate) => void
  domainNamesToReplace?: string[];
}

  • navigate: (Optional) Function that 3rd parties provides. This allow 3rd parties to customize the navigation for URL. Through the navigate, 3rd parties will have access to:

    • url: The URL that navigation is targeting on.

    • modifiers: An object contains modifiers that 3rd parties may be interested.

      • target: '_self' | '_blank' - specify if the navigation should stay within the same window: _self, or should open a new tab: _blank.

      • contentId: string | undefined - the id of content from Confluence perspective parsed from the url.

      • spaceKey: string | undefined - the key of space the content belongs to from Confluence perspective parsed from the url.

      • routeName: string | undefined - the Embedded Confluence route name derived from the url. Currently only the following routes are supported:

        RouteNameDescription
        EDIT_PAGE_EMBEDThis route name specifies that the URL is for Embedded Editor. This editor uses Native Collab Service (NCS).
        VIEW_PAGEThis route name specifies that the URL is for the View Page.

    • defaultNavigate: A function that 3rd parties can optionally choose to proceed with as default navigation behaviors. This gives 3rd parties an option to opt in to handle the navigation of url, or choose to opt out and fallback to default navigation behaviors.

  • shimUrl: (Optional) If provided, any URL that navigates to Confluence app will be converted to the URL of the 3rd party. <br>

    • Example: If 3rd party tenant is https://domain1.com/ and it is linked to Confluence Cloud, here is a table explains how this link https://domain1.com/wiki/a/b/c would be converted based on different shimUrl values:

      Provided shimUrl by 3rd partyURL in Embedded Confluence
      "" or undefinedhttps://domain1.com/wiki/a/b/c
      /xyzhttps://domain1.com/xyz/a/b/c
      xyzhttps://domain1.com/xyz/a/b/c
      https://domain1.com/xyzhttps://domain1.com/xyz/a/b/c
      https://domain1.comhttps://domain1.com/a/b/c
      domain1.com/xyzhttps://domain1.com/domain1.com/xyz/a/b/c
      domain1.comhttps://domain1.com/domain1.com/a/b/c

  • domainNamesToReplace: (Optional) A list of domain names that should be replaced with the current base URL for EP before applying any URL shimming. <br>

  • spaceKeyFilter: (Optional) A list of connected space keys for which URLs should be should be shimmed. <br>

    • Example: If 3rd party tenant is https://domain1.com/, the shimUrl value is https://domain1.com/xyz, and the spaceKeyFilter list contained XXX as a connected space key, here is what would happen two different URLs in Embedded Confluence:

      URL in Embedded ConfluencespaceKeyFilter is [ 'XXX' ]
      https://domain1.com/wiki/a/b/chttps://domain1.com/wiki/a/b/c
      https://domain1.com/wiki/spaces/XXX/a/b/chttps://domain1.com/xyz/spaces/XXX/a/b/c
      https://domain1.com/wiki/spaces/YYY/a/b/chttps://domain1.com/wiki/spaces/YYY/a/b/c

navigationPolicy examples

  1. Parent product chooses not to proceed with the default navigation under some conditions.
import { EditPage } from '@atlaskit/embedded-confluence';

const MyComponent = props => {
  const navigationPolicy = {
    navigate(url, modifiers, defaultNavigate) {
      if (/* some conditions*/) {
        // Do something without calling `defaultNavigate`
        return doSomethingElse(url, modifiers)
      }

      return defaultNavigate(url, modifiers);
    },
  };

  return (
    <EditPage
      navigationPolicy={navigationPolicy}
      {...otherProps}
    />
  );
};
  1. Parent product chooses to proceed with default navigation after making customization to the inputs under some conditions.
import { EditPage } from '@atlaskit/embedded-confluence';

const MyComponent = props => {
  const navigationPolicy = {
    navigate(url, modifiers, defaultNavigate) {
      let targetUrl = url;

      if (/*some conditions*/) {
        // Customize url and let this customized url be the input to default navigation implementation.
        targetUrl = 'something-else';
      }

      return defaultNavigate(targetUrl, modifiers);
    },
  };

  return (
    <EditPage
      navigationPolicy={navigationPolicy}
      {...otherProps}
    />
  );
};
  1. Parent product handling navigation for different routeName example
import { EditPage } from '@atlaskit/embedded-confluence';

const MyComponent = (props) => {
	const navigationPolicy = {
		navigate(url, modifiers, defaultNavigate) {
			if (modifiers.contentId === props.contentId) {
				switch (modifiers.routeName) {
					case EDIT_PAGE_EMBED:
						// Navigate to the "edit page" experience for contentId supported by embedded-confluence
						break;

					case VIEW_PAGE:
						// Navigate to the "view page" experience of contentId supported by embedded-confluence
						break;
				}
			}
			return defaultNavigate(url, modifiers);
		},
	};

	return <EditPage navigationPolicy={navigationPolicy} {...otherProps} />;
};

allowedFeatures

allowedFeatures description

There are two different types of allowedFeatures depending on the components.

allowedFeatures for View/Edit page

allowedFeatures provides a list of names of all EP features for 3rd parties. If provided, only features included in the list will be enabled, features not in the list will be disabled. [] will disable all features. 'all' will enable all features. If not provided, default features will be enabled.

A list of features for ViewPage:

NameDescription
byline-contributors(ON BY DEFAULT) To show/hide the contributors information, this includes contributor name and avatars.
byline-extensions(ON BY DEFAULT) To show/hide the byline extension.
page-comments(ON BY DEFAULT) To show/hide the page comments block.
page-reactions(ON BY DEFAULT) To show/hide the page emoji reactions.
inline-comments(ON BY DEFAULT) To show/hide inline comments and highlight button to create inline comments and Jira issues.
deleteTo show/hide the "Delete" menu item within the "Ellipsis" icon. If set to true, the "Delete" menu item will only show if user has delete permission.
editTo show/hide the "Edit" pencil icon. If set to true, the edit icon will show if user has edit permission. To handle navigation when user clicks on the edit icon, please use navigationPolicy.
sticky-headerTo show/hide sticky header.
disable-shareTo hide the share button. Providing [] will not hide the share button, 'disable-share' will need to be explicitly passed in to hide the share button.

A list of features for EditPage:

NameDescription
inline-comments(ON BY DEFAULT) To show/hide inline comments and highlight button to create them.
delete-draftTo show/hide the "Delete unpublished draft" or "Revert to last published version" menu item within the "Ellipsis" icon depending on if a document has already been published or not. To handle navigation after a user deletes/reverts a page, please listen for the experience tracker event: "taskSuccess"of "edit-page/revert-draft". If no navigation is defined by 3rd party, by default no navigation will occur and will remain on the same page after a page has been deleted/reverted. Thus please make sure some navigation is defined.
template-browserTo show/hide template browser in the edit page. If included, an empty edit page will show a template browser sidebar, and the ellipsis menu will include a dropdown option "Templates" to toggle the sidebar. To hide the space selector while still showing the templates browser, pass an object with the format {"template-browser": {"space-picker-disabled": true}} instead.

allowedFeatures example

This following example will provide all the features for the ViewPage component:

import { ViewPage } from '@atlaskit/embedded-confluence';

const MyComponent = (props) => {
	return (
		<ArticleWrapper>
			<ViewPage
				contentId={props.contentId}
				parentProductContentContainerId={props.parentProductContentContainerId}
				parentProduct={props.parentProduct}
				spaceKey={props.spaceKey}
				allowedFeatures={'all'}
			/>
		</ArticleWrapper>
	);
};

This following example will provide none of the features for the ViewPage component:

import { ViewPage } from '@atlaskit/embedded-confluence';

const MyComponent = (props) => {
	return (
		<ArticleWrapper>
			<ViewPage
				contentId={props.contentId}
				parentProductContentContainerId={props.parentProductContentContainerId}
				parentProduct={props.parentProduct}
				spaceKey={props.spaceKey}
				allowedFeatures={[]}
			/>
		</ArticleWrapper>
	);
};

This following example will provide the Edit and Delete Buttons for the ViewPage component. The other features: 'inline-comments','sticky-header', 'byline-contributors','byline-extensions','page-comments','page-reactions' will be disabled.

import { ViewPage } from '@atlaskit/embedded-confluence';

const MyComponent = (props) => {
	return (
		<ArticleWrapper>
			<ViewPage
				contentId={props.contentId}
				parentProductContentContainerId={props.parentProductContentContainerId}
				parentProduct={props.parentProduct}
				spaceKey={props.spaceKey}
				allowedFeatures={['edit', 'delete']}
			/>
		</ArticleWrapper>
	);
};

The following example will provide all the features for the view mode and no features for the edit mode within the Page component:

import { Page } from '@atlaskit/embedded-confluence';

const MyComponent = (props) => {
	return (
		<ArticleWrapper>
			<Page
				contentId={props.contentId}
				parentProductContentContainerId={props.parentProductContentContainerId}
				parentProduct={props.parentProduct}
				spaceKey={props.spaceKey}
				allowedFeatures={{ view: 'all', edit: [] }}
			/>
		</ArticleWrapper>
	);
};

locale

@atlaskit/embedded-confluence package currently can accept locale from parent products in two options:

  1. Pass locale using <IntlProvider> by react-intl.

    Please make sure <IntlProvider> exists in the React DOM and wraps @atlaskit/embedded-confluence components.

    @atlaskit/embedded-confluence use react-intl@5.21.2.

import { IntlProvider } from 'react-intl';

import { ViewPage } from '@atlaskit/embedded-confluence';

const App = (props) => {
	return (
		<IntlProvider locale="en-US">
			<ViewPage
				contentId={props.contentId}
				parentProductContentContainerId={props.parentProductContentContainerId}
				parentProduct={props.parentProduct}
				spaceKey={props.spaceKey}
			/>
		</IntlProvider>
	);
};
  1. Pass locale as React prop
import { ViewPage } from '@atlaskit/embedded-confluence';

const App = (props) => {
	return (
		<ViewPage
			contentId={props.contentId}
			locale={'en-US'}
			parentProductContentContainerId={props.parentProductContentContainerId}
			parentProduct={props.parentProduct}
			spaceKey={props.spaceKey}
		/>
	);
};

Here are the supported locales for @atlaskit/embedded-confluence

LanguageCode
Chinese (Simplified)"zh" or "zh-CN"
Chinese (Traditional)"zh-TW"
Czech"cs" or "cs-CZ"
Danish"da" or "da-DK"
Dutch"nl" or "nl-NL"
English (United Kingdom)"en-GB"
English (US)"en" or "en-US"
Finnish"fi" or "fi-FI"
French"fr" or "fr-FR"
German"de" or "de-DE"
Hungarian"hu" or "hu-HU"
Italian"it" or "it-IT"
Japanese"ja" or "ja-JP"
Korean"ko" or "ko-KR"
Norwegian"no" or "no-NO" (Norwegian) or "nb-NO" (Norwegian Bokmål)
Polish"pl" or "pl-PL"
Portuguese (Brazilian)"pt-BR"
Russian"ru" or "ru-RU"
Spanish"es" or "es-ES"
Swedish"sv" or "sv-SE"
Turkish"tr" or "tr-TR"
Thai"th" or "th-TH"
Ukrainian"uk" or "uk-UA"
Vietnamese"vi" or "vi-VN"

themeState

themeState description

Both ViewPage and EditPage components accept themeState prop. This is the prop that the embedding parent can use to apply a user’s Atlassian theme preference to the Embedded component.

You can learn more about theme preferences at the Atlassian Design Systems documentation here

themeState definition

  • themeState : (Optional) ThemeState that represents the theme preference provided by the embedding parent as a React prop.
// https://atlassian.design/components/tokens/code#setglobalthemethemestate-themeloader
To get the latest version of `ThemeState` object please check-out the[`Atlassian Design System documentation`](https://atlassian.design/components/tokens/code#setglobalthemethemestate-themeloader)
type ThemeState = {
  light: Extract<ThemeIds, 'light' | 'dark' | 'legacy-dark' | 'legacy-light'>;
  dark: Extract<ThemeIds, 'light' | 'dark' | 'legacy-dark' | 'legacy-light'>;
  colorMode: ThemeColorModes;
  shape?: Extract<ThemeIds, 'shape'>;
  spacing?: Extract<ThemeIds, 'spacing'>;
  typography?: Extract<ThemeIds, 'typography'>;
  UNSAFE_themeOptions?: CustomBrandSchema;
}
{
  themeState?: Partial<ThemeState>
}

themeState examples

Applying a theme to the View Page Component:

import { ViewPage } from '@atlaskit/embedded-confluence';
import { useThemeObserver } from '@atlaskit/tokens';

const MyComponent = (props) => {
	const themeState = useThemeObserver();

	return (
		<ViewPage
			contentId={props.contentId}
			locale={'en-US'}
			parentProductContentContainerId={props.parentProductContentContainerId}
			parentProduct={props.parentProduct}
			spaceKey={props.spaceKey}
			themeState={themeState}
		/>
	);
};

If you are using Page component you can get the themeState object from useThemeObserver, then append the encoded version of themeState to the value of url prop. You can use themeStateObjectToQueryString utility to convert themeState Object to encoded string :

import { useThemeObserver } from '@atlaskit/tokens';
import { themeStateObjectToQueryString } from '@atlassian/embedded-confluence-common';

const exampleViewPageUrl = "https://hello.atlassian.net/wiki/spaces/ABC/pages/123?parentProduct=TestProduct";
const exampleEditPageUrl = "https://hello.atlassian.net/wiki/spaces/ABC/pages/edit-embedded/123?parentProduct=TestProduct";

const MyComponent = props => (
  // Get theme from design tokens hook or fetch the user theme preference if it is stored elsewhere
  const themeState = useThemeObserver();
  const encodedString = themeStateObjectToQueryString(themeStateObject); // ex: encodedString = "light%3Alight%20dark%3Alegacy-dark%20colorMode%3Aauto%20spacing%3Aspacing%20typography%3Atypography"
  const url = exampleViewPageUrl || exampleEditPageUrl // depending on if you wish to display an Embedded View Page or Embedded Edit Page

  <ArticleWrapper>
      <Page
        url={`${url}&themeState=${encodedString}`}
      />
  </ArticleWrapper>
);