From 3bdaadc279a777305f87624882ed0c88e1119ed1 Mon Sep 17 00:00:00 2001 From: Alexandre Stanislawski Date: Wed, 26 Oct 2016 18:01:14 +0200 Subject: [PATCH 1/2] doc(orga): Add intro pages to connector, component and guides Also: - auto generate the example page - fix some styling - moved guides into a folder Fix #1468 --- docgen/layouts/common/header.pug | 6 +- docgen/layouts/main-entry.pug | 9 ++ docgen/layouts/mixins/nav-main.pug | 12 ++ docgen/plugins/navigation.js | 7 +- docgen/src/InstantSearch.md | 110 ------------------ docgen/src/component.md | 18 +++ docgen/src/connector.md | 16 +++ docgen/src/examples.md | 11 +- docgen/src/examples/e-commerce/index.html | 3 +- docgen/src/examples/material-ui/index.html | 3 +- docgen/src/examples/media/index.html | 3 +- docgen/src/examples/tourism/index.html | 3 +- docgen/src/guides.md | 11 ++ .../src/{ => guides}/3rd-party-librairies.md | 0 docgen/src/{ => guides}/Customization.md | 0 .../src/{ => guides}/Internationalization.md | 0 docgen/src/{ => guides}/Styling.md | 0 .../src/{ => guides}/conditional-display.md | 0 .../components/_documentation.scss | 10 +- 19 files changed, 90 insertions(+), 132 deletions(-) create mode 100644 docgen/layouts/main-entry.pug create mode 100644 docgen/layouts/mixins/nav-main.pug delete mode 100644 docgen/src/InstantSearch.md create mode 100644 docgen/src/component.md create mode 100644 docgen/src/connector.md create mode 100644 docgen/src/guides.md rename docgen/src/{ => guides}/3rd-party-librairies.md (100%) rename docgen/src/{ => guides}/Customization.md (100%) rename docgen/src/{ => guides}/Internationalization.md (100%) rename docgen/src/{ => guides}/Styling.md (100%) rename docgen/src/{ => guides}/conditional-display.md (100%) diff --git a/docgen/layouts/common/header.pug b/docgen/layouts/common/header.pug index 28736e73b9..c8e0588f64 100644 --- a/docgen/layouts/common/header.pug +++ b/docgen/layouts/common/header.pug @@ -57,14 +57,14 @@ li.cm-menu__list__item a(href=h.publicPath('gettingstarted.html')) Getting started li.cm-menu__list__item - a(href=h.publicPath('Styling.html')) Guide + a(href=h.publicPath('guides.html')) Guide li.cm-menu__list__item a(aria-controls='dropdown-2', aria-expanded='false', data-toggle-dropdown='dropdown-2') API ▼ ul#dropdown-2.simple-dropdown(role='tree', tabindex='-1') li - a(href=h.publicPath('component/InstantSearch.html'), role='treeitem') Components + a(href=h.publicPath('component.html'), role='treeitem') Components li - a(href=h.publicPath('HOC/Hits.html'), role='treeitem') Connector + a(href=h.publicPath('connector.html'), role='treeitem') Connector li.cm-menu__list__item diff --git a/docgen/layouts/main-entry.pug b/docgen/layouts/main-entry.pug new file mode 100644 index 0000000000..18cf48a227 --- /dev/null +++ b/docgen/layouts/main-entry.pug @@ -0,0 +1,9 @@ +extends archetypes/single-column-formatted.pug +include mixins/nav-main.pug + +block content + .content + .documentation-section + div!=contents + h2 Table of content + +nav(navPath, navigation, title, headings) diff --git a/docgen/layouts/mixins/nav-main.pug b/docgen/layouts/mixins/nav-main.pug new file mode 100644 index 0000000000..c942316086 --- /dev/null +++ b/docgen/layouts/mixins/nav-main.pug @@ -0,0 +1,12 @@ +mixin nav(currentPath, navItems, title, headings) + ul.category-content + if navItems + +navRec(currentPath, navItems, title, 2) + +mixin navRec(currentPath, navItems, title, depth) + for navItem in navItems + - var isCurrentFile = navItem.path === currentPath; + - var className = ['sidebar-element', ('level-h' + depth), (isCurrentFile ? 'navItem-active' : 'navItem')]; + - var activeClass = isCurrentFile ? 'navItem-active' : ''; + li(class=className) + a(href=h.publicPath(navItem.path) class=activeClass)=navItem.title diff --git a/docgen/plugins/navigation.js b/docgen/plugins/navigation.js index 9c6d244d89..f73134aee7 100644 --- a/docgen/plugins/navigation.js +++ b/docgen/plugins/navigation.js @@ -7,7 +7,7 @@ export default function() { // First we scann all the HTML files to retrieve all the related documents based // on the category attribute in the metadata forEach(files, (data, path) => { - if (!path.match(/\.html$/)) return; + if (!path.match(/\.html$/) || data.tocVisibility === false) return; const category = data.category || 'other'; categories[category] = categories[category] || []; categories[category].push({ @@ -26,7 +26,10 @@ export default function() { // than one without. // Then navigation is sorted by title. data.navigation = categories[category].sort((a, b) => { - if (a.navWeight === b.navWeight || a.navWeight === undefined || b.navWeight === undefined) { + if (a.title && b.title && + (a.navWeight === b.navWeight || + a.navWeight === undefined || + b.navWeight === undefined)) { return a.title.localeCompare(b.title); } else { return b.navWeight - a.navWeight; diff --git a/docgen/src/InstantSearch.md b/docgen/src/InstantSearch.md deleted file mode 100644 index e9ccd67a9e..0000000000 --- a/docgen/src/InstantSearch.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: InstantSearch -layout: widget.pug -category: guide ---- - -Connects to your Algolia index and provides data to all children widgets. - -```js -import {InstantSearch, SearchBox, Hits} from 'react-instantsearch/dom'; - -export default function Search() { - return ( - -
- - -
- - ); -} -``` - -## Props - -Name | Type | Default |Description -:- | :- | :- | :- -`appId` | `string` | | The Algolia application id. -`apiKey` | `string` | | Your Algolia Search-Only API key. -`indexName` | `string` | | The index in which to search. -`urlSync` | `?bool` | `true` | Enables automatic synchronization of widgets state to the URL. See [URL Synchronization](#url-synchronization). -`history` | `?object` | | A custom [history](https://github.com/ReactTraining/history) to push location to. Useful for quick integration with [React Router](https://github.com/reactjs/react-router). Takes precedence over `urlSync`. See [Custom History](#custom-history). -`threshold` | `?number` | `700` | Threshold in milliseconds above which new locations will be pushed to the history, instead of replacing the previous one. See [Location Debouncing](#location-debouncing). -`onStateChange` | `?func` | | See [Controlled State](#controlled-state). -`state` | `?object` | | See [Controlled State](#controlled-state). -`createURL` | `?func` | | See [Controlled State](#controlled-state). - -## URL Synchronization - -The `InstantSearch` component features a complete URL synchronization solution. Whenever a widget's state changes, the URL will be updated to reflect the new state of the search UI. This has two main benefits: - -* the user can use the browser's back and forward buttons to navigate back and forth between the different states of the search. -* the user can bookmark, copy and share a custom search URL. - -### Location Debouncing - -Since UI updates can happen in quick succession, for instance when the user types in a query, the new locations are debounced. The `treshold` prop controls how long the component should wait between state changes before pushing a new location instead of replacing the old one. - -### Custom History - -If you're using [React Router](https://github.com/reactjs/react-router) and/or the [history](https://github.com/ReactTraining/history) library, you can pass a custom history object for the component to push locations to. - -#### With React Router - -```js -import {withRouter} from 'react-router'; -import {InstantSearch} from 'react-instantsearch/dom'; - -function Search(props) { - return ( - - {/* ... */} - - ); -} - -export default withRouter(Search); -``` - -#### With a custom history - -```js -import {InstantSearch, SearchBox, Hits} from 'react-instantsearch/dom'; - -import myHistory from './path-to-my-history'; - -function Search(props) { - return ( - - {/* ... */} - - ); -} - -export default Search; -``` - -## Controlled State - -The `InstantSearch` component defaults to an uncontrolled behavior, which means that the widgets state is kept and updated internally. This behavior allows for [URL Synchronization](#url-synchronization). However, in some cases, you might want to control this state from outside of this component. For instance, if you implement your own routing solution, or if you wish to customize your URLs. - -As such, this component behaves just like a React `input`. By providing `state` and `onStateChange(nextState)` props, you can store and update the widgets state from outside the component. For instance, in a parent component's state or in a Redux store. - -Note that controlling the state from outside of the component disables [URL Synchronization](#url-synchronization). If you need this feature, you will need to reimplement it yourself. In this case, as there is no way for widgets that contain hyperlinks to guess how a state change will affect the URL, you should provide a `createURL` prop to the component. - -The `createURL` function takes in a widgets `state` object and returns a `string` to be used as a `href` attribute. diff --git a/docgen/src/component.md b/docgen/src/component.md new file mode 100644 index 0000000000..f00dca35f5 --- /dev/null +++ b/docgen/src/component.md @@ -0,0 +1,18 @@ +--- +title: Components +layout: main-entry.pug +category: component +tocVisibility: false +--- + + +react-instantsearch provides a root component and widgets. The root component +will provide the children a context to let them interact with Algolia. The +widgets are the components who have the ability to interact with the context. + +## Widgets + +The widgets are plain components that are connected to the instantsearch context. +To make this connection, they are wrapped using our collection of Higher Order +Components that we call connectors. + diff --git a/docgen/src/connector.md b/docgen/src/connector.md new file mode 100644 index 0000000000..b10c8e35c8 --- /dev/null +++ b/docgen/src/connector.md @@ -0,0 +1,16 @@ +--- +title: Connectors +layout: main-entry.pug +category: HOC +tocVisibility: false +--- + +Connectors are higher order components. They encapsulate the logic for +a specific kind of widget and they provide a way to interact with +the instantsearch context. + +As higher order components, they have an outer component API that we call +**exposed props** and they will provide some other props to the wrapped +components which are called the **provided props**. + +Connectors are exposed so that you can create your own widgets very easily. diff --git a/docgen/src/examples.md b/docgen/src/examples.md index fd644daf7a..e38a93b873 100644 --- a/docgen/src/examples.md +++ b/docgen/src/examples.md @@ -1,11 +1,10 @@ --- title: Examples -layout: examples.pug +layout: main-entry.pug category: examples +tocVisibility: false --- -# Examples -* e-commerce: [live demo](examples/e-commerce/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/e-commerce) -* tourism: [live demo](examples/tourism/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/tourism) -* media: [live demo](examples/media/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/media) -* Material-UI: [live demo](examples/material-ui/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/material-ui) +To demonstrate the flexibility of react-instantsearch we have created some demos. +If you think that there is a missing use-case don't hesitate to create an issue +on [our github page](https://github.com/algolia/instantsearch.js/issues). diff --git a/docgen/src/examples/e-commerce/index.html b/docgen/src/examples/e-commerce/index.html index 69bd43d530..ff1cfc3d23 100644 --- a/docgen/src/examples/e-commerce/index.html +++ b/docgen/src/examples/e-commerce/index.html @@ -2,8 +2,7 @@ title: E-commerce layout: example.pug name: e-commerce -nav_groups: - - examples +category: examples stylesheets: - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css diff --git a/docgen/src/examples/material-ui/index.html b/docgen/src/examples/material-ui/index.html index 2ec3ecd69b..90b361d399 100644 --- a/docgen/src/examples/material-ui/index.html +++ b/docgen/src/examples/material-ui/index.html @@ -2,8 +2,7 @@ title: Material-UI layout: example.pug name: material-ui -nav_groups: - - examples +category: examples stylesheets: - https://fonts.googleapis.com/icon?family=Material+Icons --- diff --git a/docgen/src/examples/media/index.html b/docgen/src/examples/media/index.html index 552d20aafb..e28c03428a 100644 --- a/docgen/src/examples/media/index.html +++ b/docgen/src/examples/media/index.html @@ -2,8 +2,7 @@ title: Media layout: example.pug name: media -nav_groups: - - examples +category: examples stylesheets: - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css diff --git a/docgen/src/examples/tourism/index.html b/docgen/src/examples/tourism/index.html index 40c602bc96..56ea4049b8 100644 --- a/docgen/src/examples/tourism/index.html +++ b/docgen/src/examples/tourism/index.html @@ -2,8 +2,7 @@ title: Tourism layout: example.pug name: tourism -nav_groups: - - examples +category: examples stylesheets: - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css diff --git a/docgen/src/guides.md b/docgen/src/guides.md new file mode 100644 index 0000000000..8aaccf5434 --- /dev/null +++ b/docgen/src/guides.md @@ -0,0 +1,11 @@ +--- +title: Guides +layout: main-entry.pug +category: guide +tocVisibility: false +--- + +In order to complete your knowledge of react-instantsearch, we wrote a series +of guides. Each guide covers a specific subject from a pratical point of view. + +If you think that a subject is not covered [drop us an issue on github](https://github.com/algolia/instantsearch.js/issues). diff --git a/docgen/src/3rd-party-librairies.md b/docgen/src/guides/3rd-party-librairies.md similarity index 100% rename from docgen/src/3rd-party-librairies.md rename to docgen/src/guides/3rd-party-librairies.md diff --git a/docgen/src/Customization.md b/docgen/src/guides/Customization.md similarity index 100% rename from docgen/src/Customization.md rename to docgen/src/guides/Customization.md diff --git a/docgen/src/Internationalization.md b/docgen/src/guides/Internationalization.md similarity index 100% rename from docgen/src/Internationalization.md rename to docgen/src/guides/Internationalization.md diff --git a/docgen/src/Styling.md b/docgen/src/guides/Styling.md similarity index 100% rename from docgen/src/Styling.md rename to docgen/src/guides/Styling.md diff --git a/docgen/src/conditional-display.md b/docgen/src/guides/conditional-display.md similarity index 100% rename from docgen/src/conditional-display.md rename to docgen/src/guides/conditional-display.md diff --git a/docgen/src/stylesheets/components/_documentation.scss b/docgen/src/stylesheets/components/_documentation.scss index 127b1ad16c..e806c54922 100644 --- a/docgen/src/stylesheets/components/_documentation.scss +++ b/docgen/src/stylesheets/components/_documentation.scss @@ -1,8 +1,5 @@ .documentation-section { - padding-bottom: 200px; - .container { - article { width: 100%; position: relative; @@ -10,6 +7,12 @@ } } + p, + ul, + ol { + font-size: 16px; + line-height: 22px; + } h2 { color: $charcoal-grey; @@ -76,6 +79,7 @@ width: calc(100% - #{$sidebar-width}); padding-left: 30px; padding-top: 120px; + padding-bottom: 200px; p, ul, From 9818a4110531eb8af7dda34ef2448d6285b8f994 Mon Sep 17 00:00:00 2001 From: Alexandre Stanislawski Date: Thu, 27 Oct 2016 11:40:23 +0200 Subject: [PATCH 2/2] doc(examples): add source metadata --- docgen/layouts/mixins/nav-main.pug | 4 ++++ docgen/plugins/navigation.js | 1 + docgen/src/examples/e-commerce/index.html | 1 + docgen/src/examples/material-ui/index.html | 1 + docgen/src/examples/media/index.html | 1 + docgen/src/examples/tourism/index.html | 1 + 6 files changed, 9 insertions(+) diff --git a/docgen/layouts/mixins/nav-main.pug b/docgen/layouts/mixins/nav-main.pug index c942316086..cdd754bfe6 100644 --- a/docgen/layouts/mixins/nav-main.pug +++ b/docgen/layouts/mixins/nav-main.pug @@ -10,3 +10,7 @@ mixin navRec(currentPath, navItems, title, depth) - var activeClass = isCurrentFile ? 'navItem-active' : ''; li(class=className) a(href=h.publicPath(navItem.path) class=activeClass)=navItem.title + if navItem.metadata.source + span + | - + a(href=navItem.metadata.source) source code diff --git a/docgen/plugins/navigation.js b/docgen/plugins/navigation.js index f73134aee7..01650cf125 100644 --- a/docgen/plugins/navigation.js +++ b/docgen/plugins/navigation.js @@ -14,6 +14,7 @@ export default function() { path, title: data.title, navWeight: data.navWeight, + metadata: data, }); }); diff --git a/docgen/src/examples/e-commerce/index.html b/docgen/src/examples/e-commerce/index.html index ff1cfc3d23..1c90fccf1b 100644 --- a/docgen/src/examples/e-commerce/index.html +++ b/docgen/src/examples/e-commerce/index.html @@ -3,6 +3,7 @@ layout: example.pug name: e-commerce category: examples +source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/e-commerce stylesheets: - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css diff --git a/docgen/src/examples/material-ui/index.html b/docgen/src/examples/material-ui/index.html index 90b361d399..4b3d2a7554 100644 --- a/docgen/src/examples/material-ui/index.html +++ b/docgen/src/examples/material-ui/index.html @@ -3,6 +3,7 @@ layout: example.pug name: material-ui category: examples +source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/material-ui stylesheets: - https://fonts.googleapis.com/icon?family=Material+Icons --- diff --git a/docgen/src/examples/media/index.html b/docgen/src/examples/media/index.html index e28c03428a..497001a3e0 100644 --- a/docgen/src/examples/media/index.html +++ b/docgen/src/examples/media/index.html @@ -3,6 +3,7 @@ layout: example.pug name: media category: examples +source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/media stylesheets: - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css diff --git a/docgen/src/examples/tourism/index.html b/docgen/src/examples/tourism/index.html index 56ea4049b8..1143f3c959 100644 --- a/docgen/src/examples/tourism/index.html +++ b/docgen/src/examples/tourism/index.html @@ -3,6 +3,7 @@ layout: example.pug name: tourism category: examples +source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/tourism stylesheets: - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css