diff --git a/docs/_config.yml b/docs/_config.yml index a9a9e24ea..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: Tutorials - children: - - title: Creating a Basic Plugin - url: /building-basic-plugin/ - - title: Customizing Plugins with Coral UI - url: /customizing-plugins-coral-ui/ - - title: When You've Installed Talk - url: /when-youve-installed-talk/ - 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/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_ diff --git a/docs/source/api/client.md b/docs/source/api/client.md new file mode 100644 index 000000000..fd0ec42fc --- /dev/null +++ b/docs/source/api/client.md @@ -0,0 +1,301 @@ +--- +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`. + +## Actions +#### Admin +* `viewUserDetail` + +#### Auth +* `setAuthToken` +* `handleSuccessfulLogin` +* `logout` + +#### Notification +* `notify` + +#### Stream +* `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'; +``` + +### Usage +```js +const slotPassthrough = { + clearHeightCache, + root, + asset, + comment, +}; + + +``` + +* `IfSlotIsEmpty` + +### Import +``` +import {IfSlotIsEmpty} 'plugin-api/beta/components'; +``` + +### Usage +```js + +``` + +* `IfSlotIsNotEmpty` + +### Import +``` +import {IfSlotIsNotEmpty} 'plugin-api/beta/components'; +``` + +### Usage +```js + +``` + +* `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` +* `CommentContent` +* `ConfigureCard` +* `StreamConfiguration` +* `Recaptcha` + +## HOCS - Higher Order Components +*`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 } from 'plugin-api/beta/hoc'; +``` + +### Usage +```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. + +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` +* `withFragments` +* `withMutation` +* `withForgotPassword` +* `withSignIn` +* `withSignUp` +* `withResendEmailConfirmation` +* `withSetUsername` +* `withEnumValues` +* `withVariables` +* `withFetchMore` +* `withSubscribeToMore` +* `withRefetch` +* `withIgnoreUser` +* `withBanUser` +* `withUnbanUser` +* `withStopIgnoringUser` +* `withSetCommentStatus` +* `compose` + +## 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'; +``` + +### 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` 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.