From 95934b87a4895a69e44b407938f46c38c433048f Mon Sep 17 00:00:00 2001 From: okbel Date: Wed, 21 Mar 2018 15:43:40 -0300 Subject: [PATCH 1/6] Adding docs for plugins api --- docs/source/05-03-Plugins-API.md | 185 +++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 docs/source/05-03-Plugins-API.md diff --git a/docs/source/05-03-Plugins-API.md b/docs/source/05-03-Plugins-API.md new file mode 100644 index 000000000..22d44c004 --- /dev/null +++ b/docs/source/05-03-Plugins-API.md @@ -0,0 +1,185 @@ +# Plugins API +This is a set of utilities that we expose to create or add functionality to the Plugins. Feel free to check all the utilities here at `talk/plugin-api`. + +## Actions +### Import +``` +import {notify} 'plugin-api/beta/actions'; +``` + +#### Admin +* `viewUserDetail` + +#### Auth +* `setAuthToken` +* `handleSuccessfulLogin` +* `logout` + +#### Notification +* `notify` + +#### Stream +* `setSort` +* `showSignInDialog`` + +## Components +### Import +``` +import {Slot} 'plugin-api/beta/components'; +``` + + +* `Slot` +You probably won’t need to use the `` component in your plugin. But there’s a chance you might want to add a Slot so another plugin gets injected in your plugin. + +```js +const slotPassthrough = { + clearHeightCache, + root, + asset, + comment, +}; + + +``` + +* `IfSlotIsEmpty` + +```js + +``` + +* `IfSlotIsNotEmpty` +* `ClickOutside` +* `CommentAuthorName` +* `CommentTimestamp` +* `CommentDetail` +* `CommentContent` +* `ConfigureCard` +* `StreamConfiguration` +* `Recaptcha` + +## HOCS - Higher Order Components +### Import +``` +import {withReaction} 'plugin-api/beta/hoc'; +``` + +### Hocs +*`withGraphQLExtension`* + +This HOC allows components to register GraphQLExtensions for the framework. IMPORTANT: The extensions are only picked up when the component is used in a slot. + +```js +import {withGraphQLExtension} 'plugin-api/beta/hoc'; + +// MyComponent.js +withGraphQLExtension({ + mutations: { + UpdateNotificationSettings: () => ({ + update: proxy => {...} + }) + }, + fragments: {...}, + query: {...}, +})(MyComponent); +``` + +And then update your `my-plugin/client/index.js` + +```js +export default { + mySlot: [MyComponent], +} +``` + +* `withReaction` +Provides you utilities to create components that interact with Reactions. + +* `withTags` +Provides you utilities to create components that interact with Tags. + +* `withSortOption` +* `withEmit` +* `excludeIf` +* `withFragments` +* `withMutation` +* `withForgotPassword` +* `withSignIn` +* `withSignUp` +* `withResendEmailConfirmation` +* `withSetUsername` +* `withEnumValues` +* `withVariables` +* `withFetchMore` +* `withSubscribeToMore` +* `withRefetch` +* `withIgnoreUser` +* `withBanUser` +* `withUnbanUser` +* `withStopIgnoringUser` +* `withSetCommentStatus` +* `compose` + +## Coral UI +### Import +``` +import {Button} 'plugin-api/beta/components/ui'; +``` + +### Components +* `Alert` +* `Dialog` +* `CoralLogo` +* `FabButton` +* `TabBar` +* `Tab` +* `TabCount` +* `TabContent` +* `TabPane` +* `Button` +* `Spinner` +* `Tooltip` +* `PopupMenu` +* `Checkbox` +* `Icon` +* `List` +* `Item` +* `Card` +* `TextField` +* `Success` +* `Paginate` +* `Wizard` +* `WizardNav` +* `SnackBar` +* `TextArea` +* `Drawer` +* `Label` +* `FlagLabel` +* `Dropdown` +* `Option` +* `BareButton` + +## Services +### Import +``` +import {t, timeago, can} 'plugin-api/beta/services'; +``` + +* `t` +To manage translations. + +* `timeago` +Handle time with [timeago](https://github.com/hustcc/timeago.js) + +* `can` +A permissions utility. From 24f9afd531d3fbb477cc7c0cc4bf83a0f390fcbc Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Wed, 21 Mar 2018 15:06:20 -0400 Subject: [PATCH 2/6] Update sidebar and add title info --- docs/_config.yml | 2 ++ docs/source/{05-03-Plugins-API.md => 04-07-plugins-api.md} | 6 +++++- 2 files changed, 7 insertions(+), 1 deletion(-) rename docs/source/{05-03-Plugins-API.md => 04-07-plugins-api.md} (98%) diff --git a/docs/_config.yml b/docs/_config.yml index f524fed0a..027e25921 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -138,6 +138,8 @@ sidebar: url: /plugin-recipes/ - title: Slots and Plugins url: /slots-and-plugins/ + - title: Plugins API + url: /plugins-api/ - title: Tutorials children: - title: Creating a Basic Plugin diff --git a/docs/source/05-03-Plugins-API.md b/docs/source/04-07-plugins-api.md similarity index 98% rename from docs/source/05-03-Plugins-API.md rename to docs/source/04-07-plugins-api.md index 22d44c004..aea655cb5 100644 --- a/docs/source/05-03-Plugins-API.md +++ b/docs/source/04-07-plugins-api.md @@ -1,4 +1,8 @@ -# Plugins API +--- +title: Plugins API +permalink: /plugins-api/ +--- + This is a set of utilities that we expose to create or add functionality to the Plugins. Feel free to check all the utilities here at `talk/plugin-api`. ## Actions From 773c8438341bcaeee375ff90b76bc87659b934ef Mon Sep 17 00:00:00 2001 From: okbel Date: Thu, 22 Mar 2018 11:59:33 -0300 Subject: [PATCH 3/6] Click Outside --- docs/source/05-03-Plugins-API.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/source/05-03-Plugins-API.md b/docs/source/05-03-Plugins-API.md index 22d44c004..4c90a0aa2 100644 --- a/docs/source/05-03-Plugins-API.md +++ b/docs/source/05-03-Plugins-API.md @@ -1,7 +1,10 @@ # Plugins API -This is a set of utilities that we expose to create or add functionality to the Plugins. Feel free to check all the utilities here at `talk/plugin-api`. +We created a set of utilities to make it easier to create and add functionality to plugins. + +Feel free to check all the utilities here: `talk/plugin-api`. ## Actions + ### Import ``` import {notify} 'plugin-api/beta/actions'; @@ -59,7 +62,26 @@ const slotPassthrough = { ``` * `IfSlotIsNotEmpty` + * `ClickOutside` +This utility handle click events outside the component. + +### Props +* `onClickOutside` : Takes handler function + +#### Import +```js +import { ClickOutside } from 'plugin-api/beta/client/components'; +``` + +#### Usage +```js + + // Your component + +``` + + * `CommentAuthorName` * `CommentTimestamp` * `CommentDetail` From 1fc750083742023224b0acfac85ba9f2a7223d31 Mon Sep 17 00:00:00 2001 From: okbel Date: Thu, 22 Mar 2018 12:36:46 -0300 Subject: [PATCH 4/6] More --- docs/source/05-03-Plugins-API.md | 162 ++++++++++++++++++++++++------- 1 file changed, 125 insertions(+), 37 deletions(-) diff --git a/docs/source/05-03-Plugins-API.md b/docs/source/05-03-Plugins-API.md index 4c90a0aa2..c15b040cd 100644 --- a/docs/source/05-03-Plugins-API.md +++ b/docs/source/05-03-Plugins-API.md @@ -1,15 +1,8 @@ # Plugins API We created a set of utilities to make it easier to create and add functionality to plugins. - Feel free to check all the utilities here: `talk/plugin-api`. ## Actions - -### Import -``` -import {notify} 'plugin-api/beta/actions'; -``` - #### Admin * `viewUserDetail` @@ -25,16 +18,46 @@ import {notify} 'plugin-api/beta/actions'; * `setSort` * `showSignInDialog`` +### Import +``` +import {notify} 'plugin-api/beta/actions'; +``` + +### Usage +```js +// Trigger a notification +notify('success', t('suspenduser.notify_suspend_until', username, timeago(until)) + +// mapDispatchToProps +const mapDispatchToProps = dispatch => ({ + ...bindActionCreators( + { + notify, + }, + dispatch + ), +}); + +``` + + ## Components +* `Slot` +You probably won’t need to use the `` component in your plugin. But there’s a chance you might want to add a Slot so another plugin gets injected in your plugin. + +### Props +* `fill ` : Name of the slot +* `defaultComponent` : The default component if no plugin component is provided to the Slot +* `size` : - How many components this Slot should show - Slot size or an Array of slot size +* `passthrough`: - The properties that you want to pass to the Slot, therefore to the plugins. +* `className` : - Slot’s class name + ### Import ``` import {Slot} 'plugin-api/beta/components'; ``` - -* `Slot` -You probably won’t need to use the `` component in your plugin. But there’s a chance you might want to add a Slot so another plugin gets injected in your plugin. - +### Usage ```js const slotPassthrough = { clearHeightCache, @@ -54,6 +77,12 @@ const slotPassthrough = { * `IfSlotIsEmpty` +### Import +``` +import {IfSlotIsEmpty} 'plugin-api/beta/components'; +``` + +### Usage ```js +``` + * `ClickOutside` This utility handle click events outside the component. @@ -81,7 +123,6 @@ import { ClickOutside } from 'plugin-api/beta/client/components'; ``` - * `CommentAuthorName` * `CommentTimestamp` * `CommentDetail` @@ -91,20 +132,17 @@ import { ClickOutside } from 'plugin-api/beta/client/components'; * `Recaptcha` ## HOCS - Higher Order Components -### Import -``` -import {withReaction} 'plugin-api/beta/hoc'; -``` - -### Hocs *`withGraphQLExtension`* This HOC allows components to register GraphQLExtensions for the framework. IMPORTANT: The extensions are only picked up when the component is used in a slot. +### Import ```js -import {withGraphQLExtension} 'plugin-api/beta/hoc'; +import { withGraphQLExtension } from 'plugin-api/beta/hoc'; +``` -// MyComponent.js +### Usage +```js withGraphQLExtension({ mutations: { UpdateNotificationSettings: () => ({ @@ -127,9 +165,33 @@ export default { * `withReaction` Provides you utilities to create components that interact with Reactions. +Check this tutorial to know more about the usage of `withReaction` [Creating a Basic Pride Reaction Plugin | Talk Documentation](https://docs.coralproject.net/talk/building-basic-plugin/) + +### Import +```js +import { withReaction } from 'plugin-api/beta/hoc'; +``` + +### Usage +```js +export default withReaction('pride')(PrideButton); +``` + + * `withTags` Provides you utilities to create components that interact with Tags. +### Import +```js +import { withTags } from 'plugin-api/beta/hoc'; +``` + +### Usage +```js +export default withTags('featured')(FeaturedButton); +``` + + * `withSortOption` * `withEmit` * `excludeIf` @@ -152,9 +214,50 @@ Provides you utilities to create components that interact with Tags. * `withSetCommentStatus` * `compose` -## Coral UI -### Import +## Services + +* `t` +To manage translations. + +### Import +```js +import { t } from 'coral-framework/services/perms'; ``` + +* `timeago` +Handle time with [timeago](https://github.com/hustcc/timeago.js) + +### Import +```js +import { timeago } from 'coral-framework/services/perms'; +``` + +* `can` +A permissions utility. + +### Import +```js +import { can } from 'coral-framework/services/perms'; +``` + +### Usage +```js +{can(currentUser, 'UPDATE_CONFIG') && ( + + {t('configure.configure')} + +)} +``` + +## Coral UI +Coral UI is a set of components to help you build your UI. This powers our core. + +### Import +```js import {Button} 'plugin-api/beta/components/ui'; ``` @@ -190,18 +293,3 @@ import {Button} 'plugin-api/beta/components/ui'; * `Dropdown` * `Option` * `BareButton` - -## Services -### Import -``` -import {t, timeago, can} 'plugin-api/beta/services'; -``` - -* `t` -To manage translations. - -* `timeago` -Handle time with [timeago](https://github.com/hustcc/timeago.js) - -* `can` -A permissions utility. From 752c16f513135187bfb5a997d50086b228b4168e Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Thu, 22 Mar 2018 18:35:14 -0400 Subject: [PATCH 5/6] Move Plugin Client and Slots docs to API section --- docs/_config.yml | 20 +++++++++---------- .../{04-07-plugins-api.md => api/client.md} | 7 +++++-- docs/source/api/server.md | 2 +- .../slots.md} | 6 ++++-- 4 files changed, 20 insertions(+), 15 deletions(-) rename docs/source/{04-07-plugins-api.md => api/client.md} (98%) rename docs/source/{04-06-slots-and-plugins.md => api/slots.md} (98%) diff --git a/docs/_config.yml b/docs/_config.yml index 506bd2542..f269d8695 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -136,16 +136,6 @@ sidebar: url: /plugins-directory/ - title: Plugin Recipes url: /plugin-recipes/ - - title: Slots and Plugins - url: /slots-and-plugins/ - - title: Plugins API - url: /plugins-api/ - - title: Tutorials - children: - - title: Creating a Basic Plugin - url: /building-basic-plugin/ - - title: Customizing Plugins with Coral UI - url: /customizing-plugins-coral-ui/ - title: API children: - title: GraphQL Overview @@ -154,6 +144,16 @@ sidebar: url: /api/graphql/ - title: Server Plugin API url: /api/server/ + - title: Client Plugin API + url: /api/client/ + - title: Plugin Slots API + url: /api/slots/ + - title: Tutorials + children: + - title: Creating a Basic Plugin + url: /building-basic-plugin/ + - title: Customizing Plugins with Coral UI + url: /customizing-plugins-coral-ui/ - title: Migrating children: - title: Migrating to v4.0.0 diff --git a/docs/source/04-07-plugins-api.md b/docs/source/api/client.md similarity index 98% rename from docs/source/04-07-plugins-api.md rename to docs/source/api/client.md index 2f12fccf5..fd0ec42fc 100644 --- a/docs/source/04-07-plugins-api.md +++ b/docs/source/api/client.md @@ -1,7 +1,10 @@ --- -title: Plugins API -permalink: /plugins-api/ +title: Client Plugin API +permalink: /api/client/ +toc: true +class: configuration --- + We created a set of utilities to make it easier to create and add functionality to plugins. Feel free to check all the utilities here: `talk/plugin-api`. diff --git a/docs/source/api/server.md b/docs/source/api/server.md index 614c7b2ed..821b4b24f 100644 --- a/docs/source/api/server.md +++ b/docs/source/api/server.md @@ -524,4 +524,4 @@ module.exports = { } }; -``` \ No newline at end of file +``` diff --git a/docs/source/04-06-slots-and-plugins.md b/docs/source/api/slots.md similarity index 98% rename from docs/source/04-06-slots-and-plugins.md rename to docs/source/api/slots.md index 907c85862..4ac47a516 100644 --- a/docs/source/04-06-slots-and-plugins.md +++ b/docs/source/api/slots.md @@ -1,6 +1,8 @@ --- -title: Slots and Plugins -permalink: /slots-and-plugins/ +title: Plugin Slots API +permalink: /api/slots/ +toc: true +class: configuration --- Plugins make use of **"slots"** in order to change Talk's interface. From 7a505ac5fcfca9c4284d2420320e2eaf40b5483a Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Fri, 23 Mar 2018 17:08:41 -0400 Subject: [PATCH 6/6] Tweak on tutorial --- docs/source/05-03-when-youve-installed-talk.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/05-03-when-youve-installed-talk.md b/docs/source/05-03-when-youve-installed-talk.md index aff0de83c..7bd775469 100644 --- a/docs/source/05-03-when-youve-installed-talk.md +++ b/docs/source/05-03-when-youve-installed-talk.md @@ -140,5 +140,3 @@ For the first month or so, we recommend including a link to the launch article m A regular space for conversation about the conversation is always welcome in any successful community, and is a great source of ideas for improvement.   **_We hope you enjoy using Talk, and that it helps your communities to thrive. If you have any questions or suggestions for this piece, or would like to try Talk on your site, please [contact us.](https://coralproject.net/contact.html)_**   - -[_Red button image by włodi_](https://www.flickr.com/photos/wlodi/3085157011/)_, CC-BY-SA 2.0_