rationalise some props, update docs

Financial-Times · Nov 6, 2018 · 225be84 · 225be84
1 parent 3d5ff99
commit 225be84
Show file tree

Hide file tree

Showing 10 changed files with 67 additions and 35 deletions.
diff --git a/components/x-gift-article/readme.md b/components/x-gift-article/readme.md
@@ -10,8 +10,6 @@ This module is compatible with Node 6+ and is distributed on npm.
 npm install --save @financial-times/x-gift-article
 ```
 
-[engine]: https://github.com/Financial-Times/x-dash/tree/master/packages/x-engine
-
 ## Styling
 
 To get correct styling, Your app should have origami components below.
@@ -36,22 +34,50 @@ const b = <GiftArticle {...props} />;
 const c = React.createElement(GiftArticle, props);
 ```
 
-Your app should dispatch a custom event (`xDash.giftArticle.activate`) to activate the gift article form when your app actually displays the form.
-`document.body.dispatchEvent(new CustomEvent('xDash.giftArticle.activate'));`
+Your app should trigger the `activate` action to activate the gift article form when your app actually displays the form. For example, if your app is client-side rendered, you can use `actionsRef` to trigger this action:
+
+```jsx
+import { h, Component } from '@financial-times/x-engine';
+import { GiftArticle } from '@financial-times/x-gift-article';
+
+class Container extends Component {
+  showGiftArticle() {
+    if(this.giftArticleActions) {
+      this.setState({ showGiftArticle: true });
+
+      // trigger the action
+      this.giftArticleActions.activate();
+    }
+  }
+
+  render() {
+    return <div>
+      <button onClick={() => this.showGiftArticle()}>
+        Share
+      </button>
+
+      <div style={{display: this.state.showGiftArticle ? 'block' : 'none'}}>
+        <GiftArticle {...this.props} actionsRef={actions => this.giftArticleActions = actions} />
+      </div>
+    </div>
+  }
+}
+```
+
+For more information about triggering actions, see the [x-interaction documentation][interaction].
 
 All `x-` components are designed to be compatible with a variety of runtimes, not just React. Check out the [`x-engine`][engine] documentation for a list of recommended libraries and frameworks.
 
 [jsx-wtf]: https://jasonformat.com/wtf-is-jsx/
-
+[interaction]: /components/x-interaction#triggering-actions-externally
+[engine]: https://github.com/Financial-Times/x-dash/tree/master/packages/x-engine
 
 ### Properties
 
 Property                  | Type    | Required | Note
 --------------------------|---------|----------|----
 `isFreeArticle`           | Boolean | yes      | Only non gift form is displayed when this value is `true`.
-`articleUrl`              | String  | yes      | Canonical URL
-`articleTitle`            | String  | yes      |
-`articleId`               | String  | yes      | Content UUID
+`article`                 | Object  | yes      | Must contain `id`, `title` and `url` properties
 `showMobileShareLinks`    | Boolean | no       |
 `nativeShare`             | Boolean | no       | This is a property for App to display Native Sharing.
 `apiProtocol`             | String  | no       | The protocol to use when making requests to the gift article and URL shortening services. Ignored if `apiDomain` is not set.

diff --git a/components/x-gift-article/src/Buttons.jsx b/components/x-gift-article/src/Buttons.jsx
@@ -16,19 +16,18 @@ const ButtonWithGapClassNames = [
 	styles['button--with-gap']
 ].join(' ');
 
-
 export default ({
 	shareType,
 	isGiftUrlCreated,
 	mailtoUrl,
 	showCopyButton,
-	showNativeShareButton,
+	nativeShare,
 	actions
 }) => {
 
 	if (isGiftUrlCreated || shareType === ShareType.nonGift) {
 
-		if (showNativeShareButton) {
+		if (nativeShare) {
 			return (
 				<div className={ ButtonsClassName }>
 					<button className={ ButtonWithGapClassNames } type="button" onClick={ actions.shareByNativeShare }>Share link</button>

diff --git a/components/x-gift-article/src/GiftArticle.jsx b/components/x-gift-article/src/GiftArticle.jsx
@@ -45,7 +45,7 @@ const withGiftFormActions = withActions(
 			},
 
 			async createGiftUrl() {
-				const { redemptionUrl, redemptionLimit } = await api.getGiftUrl(initialProps.articleId);
+				const { redemptionUrl, redemptionLimit } = await api.getGiftUrl(initialProps.article.id);
 
 				if (redemptionUrl) {
 					const { url, isShortened } = await api.getShorterUrl(redemptionUrl);
@@ -134,20 +134,20 @@ const withGiftFormActions = withActions(
 			urls: {
 				dummy: 'https://on.ft.com/gift_link',
 				gift: undefined,
-				nonGift: `${props.articleUrl}?shareType=nongift`
+				nonGift: `${props.article.url}?shareType=nongift`
 			},
 
 			mailtoUrls: {
 				gift: undefined,
-				nonGift: createMailtoUrl(props.articleTitle, `${props.articleUrl}?shareType=nongift`)
+				nonGift: createMailtoUrl(props.article.title, `${props.article.url}?shareType=nongift`)
 			},
 
 			mobileShareLinks: props.showMobileShareLinks
 				? {
-					facebook: `http://www.facebook.com/sharer.php?u=${encodeURIComponent(props.articleUrl)}&t=${encodeURIComponent(props.articleTitle)}`,
-					twitter: `https://twitter.com/intent/tweet?url=${encodeURIComponent(props.articleUrl)}&text=${encodeURIComponent(props.articleTitle)}&via=financialtimes`,
-					linkedin: `http://www.linkedin.com/shareArticle?mini=true&url=${encodeURIComponent(props.articleUrl)}&title=${encodeURIComponent(props.articleTitle)}&source=Financial+Times`,
-					whatsapp: `whatsapp://send?text=${encodeURIComponent(props.articleTitle)}%20-%20${encodeURIComponent(props.articleUrl)}`
+					facebook: `http://www.facebook.com/sharer.php?u=${encodeURIComponent(props.article.url)}&t=${encodeURIComponent(props.article.title)}`,
+					twitter: `https://twitter.com/intent/tweet?url=${encodeURIComponent(props.article.url)}&text=${encodeURIComponent(props.article.title)}&via=financialtimes`,
+					linkedin: `http://www.linkedin.com/shareArticle?mini=true&url=${encodeURIComponent(props.article.url)}&title=${encodeURIComponent(props.article.title)}&source=Financial+Times`,
+					whatsapp: `whatsapp://send?text=${encodeURIComponent(props.article.title)}%20-%20${encodeURIComponent(props.article.url)}`
 				}
 				: undefined
 		};

diff --git a/components/x-gift-article/src/UrlSection.jsx b/components/x-gift-article/src/UrlSection.jsx
@@ -22,7 +22,7 @@ export default ({
 	mailtoUrl,
 	redemptionLimit,
 	showCopyButton,
-	showNativeShareButton,
+	nativeShare,
 	actions
 }) => {
 
@@ -57,7 +57,7 @@ export default ({
 				isGiftUrlCreated,
 				mailtoUrl,
 				showCopyButton,
-				showNativeShareButton,
+				nativeShare,
 				actions,
 			}} /> }
 

diff --git a/components/x-gift-article/src/lib/api.js b/components/x-gift-article/src/lib/api.js
@@ -74,4 +74,3 @@ export default class ApiClient {
 		return { url, isShortened };
 	}
 }
-
diff --git a/components/x-gift-article/src/lib/updaters.js b/components/x-gift-article/src/lib/updaters.js
@@ -20,7 +20,7 @@ export const showNonGiftUrlSection = (props) => ({
 });
 
 export const setGiftUrl = (url, redemptionLimit, isShortened) => props => {
-	const mailtoUrl = createMailtoUrl(props.articleTitle, url);
+	const mailtoUrl = createMailtoUrl(props.article.title, url);
 
 	return {
 		url,
@@ -52,7 +52,7 @@ export const setAllowance = (giftCredits, monthlyAllowance, nextRenewalDate) =>
 };
 
 export const setShortenedNonGiftUrl = (shortenedUrl) => props => {
-	const mailtoUrl = createMailtoUrl(props.articleTitle, shortenedUrl);
+	const mailtoUrl = createMailtoUrl(props.article.title, shortenedUrl);
 
 	return {
 		url: shortenedUrl,

diff --git a/components/x-gift-article/stories/free-article.js b/components/x-gift-article/stories/free-article.js
@@ -6,9 +6,11 @@ exports.title = 'Free article';
 exports.data = {
 	title: 'Share this article (free)',
 	isFreeArticle: true,
-	articleUrl,
-	articleTitle: 'Title Title Title Title',
-	id: 'base-gift-article-static-id'
+	article: {
+		title: 'Title Title Title Title',
+		id: 'base-gift-article-static-id',
+		url: articleUrl,
+	},
 };
 
 // This reference is only required for hot module loading in development

diff --git a/components/x-gift-article/stories/native-share.js b/components/x-gift-article/stories/native-share.js
@@ -8,9 +8,11 @@ exports.title = 'With native share on App';
 exports.data = {
 	title: 'Share this article (on App)',
 	isFreeArticle: false,
-	articleUrl,
-	articleTitle: 'Title Title Title Title',
-	articleId,
+	article: {
+		id: articleId,
+		url: articleUrl,
+		title: 'Title Title Title Title',
+	},
 	nativeShare: true,
 	id: 'base-gift-article-static-id'
 };

diff --git a/components/x-gift-article/stories/with-gift-credits.js b/components/x-gift-article/stories/with-gift-credits.js
@@ -8,9 +8,11 @@ exports.title = 'With gift credits';
 exports.data = {
 	title: 'Share this article (with credit)',
 	isFreeArticle: false,
-	articleUrl,
-	articleTitle: 'Title Title Title Title',
-	articleId,
+	article: {
+		id: articleId,
+		url: articleUrl,
+		title: 'Title Title Title Title',
+	},
 	showMobileShareLinks: true,
 	id: 'base-gift-article-static-id'
 };

diff --git a/components/x-gift-article/stories/without-gift-credits.js b/components/x-gift-article/stories/without-gift-credits.js
@@ -6,9 +6,11 @@ exports.title = 'Without gift credits';
 exports.data = {
 	title: 'Share this article (without credit)',
 	isFreeArticle: false,
-	articleUrl,
-	articleTitle: 'Title Title Title Title',
-	id: 'base-gift-article-static-id'
+	article: {
+		id: 'article id',
+		url: articleUrl,
+		title: 'Title Title Title Title',
+	},
 };
 
 // This reference is only required for hot module loading in development
Original file line number	Diff line number	Diff line change
Expand Up		@@ -74,4 +74,3 @@ export default class ApiClient {
		return { url, isShortened };
		}
		}