diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7f73f1e..97e7a36 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,76 +7,120 @@ First of all, thank you so much for being interested in contributing to filestac
- Creating new examples
## Issues
+
Feel free to open new issues or participating in the discussion of the existing ones on
[this repository](https://github.com/filestack/filestack-react/issues), but before doing so, please make sure that the issue is not duplicated and/or the discussion is related to the topic of the issue.
## Pull requests
+
Code contributions are welcome following a process which guarantees the long-term maintainability of the project.
You can contribute either with bugfixes or new features. Before submitting a new feature, we highly encourage you to first open a new issue describing its motivation and details and discuss it with one of the project mantainers. This will ensure that the feature fits well in the project.
### Step 1: Open a new issue (if not opened yet)
+
Before starting to code, it is desirable to first open an issue describing the bug or the new feature. Please be sure the issue is not duplicated.
### Step 2: Fork the repository
+
Fork the project https://github.com/filestack/filestack-react into your account. Then, check out your copy of the project locally.
+
+### Step 3: Create a new feature branch `contrib/issue-[number]`
+
+Put your code in a new feature branch. The name of the new branch should start with `contrib/issue-`. This convention will help us to keep track of future changes from pull requests.
+
```
-git clone git@github.com:user/react-filestack.git
-cd react-filestack
-git remote add upstream https://github.com/filestack/filestack-react.git
+git checkout -b contrib/issue-[number] tags/[tag-name]
```
-### Step 3: Create a new feature branch `contrib/issue-number`
-Put your code in a new feature branch. The name of the new branch should start with `contrib/`. This convention will help us to keep track of future changes from pull requests.
+Note that `tags/[tag-name]` would correspond with one of the existing tags in the project. List all the tags with `git tag`, or look on the project home page. For example, suppose that the latest version of the project is `v1.2.3` (note the 'v' is part of the tag name), and you want to fix a new bug that you discovered in this version. If the new reported issue has an id of #186, then you would create your feature branch in this way:
+
```
-git checkout -b contrib/issue-number tags/tag-number
+git checkout -b contrib/issue-186 tags/v1.2.3
```
-Note that tags/tag-number would correspond with any of the tags (for example 1.0.X). For example, suppose that the latest version of the project is v1.0.0 and you want to fix a new bug that you discovered in this version. If the new reported issue has an id, say, #186, then you would create your feature branch in this way:
+
+### Step 4: Create your feature or bugfix
+
+The whole component is located inside src/ReactFilestack.jsx.
+
+#### Install dependencies
+
```
-git checkout -b contrib/issue-186 tags/1.0.X
+npm install
```
-### Step 4: Committing your changes
-First of all, make sure that git is configured with your complete name and email address. It is desirable to use the same email of your Github account, this will help to identify the contributions:
+#### Re-build after making changes
+
```
-git config --global user.name "Your Name"
-git config --global user.email "your@email.com"
+npm run build
```
-Write a good commit message. It should describe the changes you made and its motivation. Be sure to reference the issue you are working in the commit that finishes your contribution using one the [keywords to close issues in Github](https://help.github.com/articles/closing-issues-via-commit-messages/).
-If your commit message is too long, try to summarize the changes in the header of the message, like this:
+
+#### Run unit tests
+
+Verify that your changes are actually working by adding the required unit tests. It is desirable to include unit tests covering all new features you implement. Also, if you find a bug which is not currently detected by the unit tests you might consider to implement a new one or modify the current implementation. After this, you can verify that everything works fine after your changes with:
+
```
-fix #xx : summarize your commit in one line
+npm test
+```
+
+#### Lint the code
-If needed, explain more in detail the changes introduced in your
-commit and the motivation. You could introduce some background
-about the issue you worked in.
+Ensure that your code meets the project's style, enforced by eslint.
-This message can contain several paragraphs and be as long as
-you need, but try to do a good indentation: the columns should
-be shorter than 72 characters and with a proper word-wrap.
-The command `git log` will print this complete text in a nice
-way if you format it properly.
```
-The header and the body of the commit message must be separated by a line in blank. The header is the message shown when running the command `git shortlog`.
+npm run lint
+```
+
+#### Link to an existing project (optional)
+
+You may want to test how the filestack-react works with an existing project, or a new demo project. Use [NPM link](https://docs.npmjs.com/cli/link) to tell your existing project to use your local development version of filestack-react instead of the one from NPM.
-#### Test your code
-Verify that your changes are actually working by adding the required unit tests. It is desirable to include unit test covering all new features you implement. Also, if you find a bug which is not currently detected by the unit tests you might consider to implement a new one or modify the current implementation. After this, you can verify that everything works fine after your changes with:
+In the filestack-react development folder:
```
-nosetests
+npm link
```
-### Step 5: Push your changes
+If your existing/demo project is already using filestack-react from NPM, uninstall it.
+
+```
+npm uninstall filestack-react
+```
+
+Then link to the local version of filestack-react. In your existing/demo folder:
+
+```
+npm link ../somepath/to/filestack-react
+```
+
+### Step 5: Committing your changes
+
+#### Git congif
+
+Make sure your git client is configured with your complete name and email address. It is desirable to use the same email of your Github account, this will help to identify the contributions:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "your@email.com"
+```
+
+#### Commit message
+
+We follow the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/) to ensure consistent commit messages and changelog formatting. Be sure to reference the issue you are working on in the commit that finishes your contribution using one the [keywords to close issues in Github](https://help.github.com/articles/closing-issues-via-commit-messages/).
+
+### Step 6: Push your changes
Push your changes to your forked project with:
+
```
git push origin contrib/issue-186
```
-### Step 6: Create and submit a pull request
-Go to your forked project on GitHub, select your feature branch and click the “Compare, review, create a pull request button”.
+### Step 7: Create and submit a pull request
+Go to your forked project on GitHub, select your feature branch and click the “Compare, review, create a pull request button”.
### License Agreement
+
By contributing your code, you agree to license your contribution under the terms of the [Apache 2.0 license](https://raw.githubusercontent.com/citiususc/hipster/4ca93e681ad7335acbd0bea9e49fe678d56f3519/LICENSE).
Also, remember to add this header to each new file that you’ve created:
diff --git a/README.md b/README.md
index 6fbf140..c26bad3 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@
**Table of Contents**
+
- [Overview](#overview)
- [Usage](#usage)
- [Props](#props)
@@ -33,58 +34,65 @@
- [Future](#future)
## Overview
+
filestack-react is a wrapper on [filestack-js](https://github.com/filestack/filestack-js) sdk which allow you to integrate with Filestack service in just a few lines of code. Almost all you can do with [filestack-js](https://filestack.github.io/filestack-js/index.html) you can do with this component.
## Usage
+
Install it through NPM
+
```bash
npm install filestack-react
```
+
then just insert into your app
+
```jsx
import ReactFilestack from 'filestack-react';
- console.log(res)}
-/>
+ console.log(res)} />;
```
+
### Props
-| Key | Type | Required | Default | Description |
-|----------------------------------|---------------|----------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| apikey | String | true | | Filestack api key |
-| action | String | false | 'pick' | A method from [Client](https://filestack.github.io/filestack-js/classes/client.html) class. One of 'transform','retrieve','metadata','storeUrl','upload','remove','pick','removeMetadata','preview','logout' |
-| actionOptions | Object | false | | An action (client method) specific options object eg. PickerOptions, TransformOptions etc. |
-| componentDisplayMode | Object | | | Determines how will be wrapper component displayed |
-| componentDisplayMode.type | String | false | 'button' | It can be 'button', 'link' or 'immediate' |
-| componentDisplayMode.customText | String | false | 'Pick file' | If type is 'button' or 'link' you can set text for it |
-| componentDisplayMode.customClass | String | false | 'filestack-react' | If type is 'button' or 'link' you can set class for it |
-| onSuccess | Function | false | result => console.log(result) | A function to be called after successful completed action |
-| onError | Function | false | error => console.error(error) | A function to be called when error occurs |
-| clientOptions | Object | | | Filestack client options used for an every action |
-| clientOptions.cname | String | false | | Check [cname](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#cname) |
+
+| Key | Type | Required | Default | Description |
+| -------------------------------- | ----------------------------------------------------------------------------- | -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| apikey | String | true | | Filestack api key |
+| action | String | false | 'pick' | A method from [Client](https://filestack.github.io/filestack-js/classes/client.html) class. One of 'transform','retrieve','metadata','storeUrl','upload','remove','pick','removeMetadata','preview','logout' |
+| actionOptions | Object | false | | An action (client method) specific options object eg. PickerOptions, TransformOptions etc. |
+| componentDisplayMode | Object | | | Determines how will be wrapper component displayed |
+| componentDisplayMode.type | String | false | 'button' | It can be 'button', 'link' or 'immediate' |
+| componentDisplayMode.customText | String | false | 'Pick file' | If type is 'button' or 'link' you can set text for it |
+| componentDisplayMode.customClass | String | false | 'filestack-react' | If type is 'button' or 'link' you can set class for it |
+| onSuccess | Function | false | result => console.log(result) | A function to be called after successful completed action |
+| onError | Function | false | error => console.error(error) | A function to be called when error occurs |
+| clientOptions | Object | | | Filestack client options used for an every action |
+| clientOptions.cname | String | false | | Check [cname](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#cname) |
| clientOptions.security | [Security](https://filestack.github.io/filestack-js/interfaces/security.html) | false | | Check [security](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#security) |
-| clientOptions.sessionCache | Boolean | false | | Check [sessionCache](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#sessioncache) |
-| file | Object | false | | Use it to insert a file object for 'upload' action |
-| source | String | false | | Use it to pass for some actions handle or external url |
-| customRender | Function | false | | Use it if you need custom html structure |
+| clientOptions.sessionCache | Boolean | false | | Check [sessionCache](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#sessioncache) |
+| file | Object | false | | Use it to insert a file object for 'upload' action |
+| source | String | false | | Use it to pass for some actions handle or external url |
+| customRender | Function | false | | Use it if you need custom html structure |
### Examples
+
**Picker with custom designed button**
+
```jsx
```
**Picker with custom wrapper**
+
```jsx
+ type: 'immediate',
+ }}
+/>
```
**Show picker directly and embed it inside specific container**
+
```jsx
+ displayMode: 'inline',
+ container: 'embedded',
+ }}
+/>
```
**Transformation of external url with security**
+
```jsx
console.log(res)}/>
+ source="https://upload.wikimedia.org/wikipedia/commons/c/cf/Pears.jpg"
+ onSuccess={(res) => console.log(res)}
+/>
```
### filestack-js Client
+
If you need to use Client just try
+
```jsx
import ReactFilestack, { client } from 'filestack-react';
```
### SSR
+
If you need to use filestack-react with SSR project or site generators like Gatsby check some workarounds in this issues
[issue57](https://github.com/filestack/filestack-react/issues/57)
@@ -159,57 +176,45 @@ If you need to use filestack-react with SSR project or site generators like Gats
[issue65](https://github.com/filestack/filestack-react/issues/65)
### Migration from 1.x.x and 2.x.x
-One of the changes introduced in the new version are rethinked props that the component accepts, so that the use of the component is as straightforward as possible.
+
+One of the changes introduced in the new version are rethinked props that the component accepts, so that the use of the component is as straightforward as possible.
Below you will find information about what happened to each of the options available in 2.x.x :
-| 2.x.x | 3.0.0 | Comment |
-|----------------|----------------------------------|-------------------------------------------------------------------------------|
-| apikey | apikey | |
-| mode | action | |
-| options | actionOptions | We want to emphasize that this option is associated with 'action' |
-| preload | N/A | Now, component is at default preloading neccessary js assets, styles, images |
-| file | file | |
-| onSuccess | onSuccess | |
-| onError | onError | |
+| 2.x.x | 3.0.0 | Comment |
+| -------------- | -------------------------------- | ------------------------------------------------------------------------------ |
+| apikey | apikey | |
+| mode | action | |
+| options | actionOptions | We want to emphasize that this option is associated with 'action' |
+| preload | N/A | Now, component is at default preloading neccessary js assets, styles, images |
+| file | file | |
+| onSuccess | onSuccess | |
+| onError | onError | |
| options.handle | source | Handle or url used by specific action is now stored in separate prop |
| options.url | source | Handle or url used by specific action is now stored in separate prop |
| security | clientOptions.security | Options used to initialize filestack client are now grouped in ‘clientOptions’ |
-| buttonText | componentDisplayMode.customText | Use componentDisplayMode option (see examples) |
-| buttonClass | componentDisplayMode.customClass | Use componentDisplayMode option (see examples) |
+| buttonText | componentDisplayMode.customText | Use componentDisplayMode option (see examples) |
+| buttonClass | componentDisplayMode.customClass | Use componentDisplayMode option (see examples) |
| cname | clientOptions.cname | Options used to initialize filestack client are now grouped in ‘clientOptions’ |
| sessionCache | clientOptions.sessionCache | Options used to initialize filestack client are now grouped in ‘clientOptions’ |
-| render | customRender | |
-| children | N/A | Use customRender instead |
-
+| render | customRender | |
+| children | N/A | Use customRender instead |
## Live demo
+
Check demo at codepen
https://codepen.io/Filestack/pen/KEpVdR
-## Development
-The whole componenst is located inside src/ReactFilestack.jsx
-
-After you add some changes just type
-```
-npm run build
-```
-
-Be sure that your change doesn't break existing tests and are compatible with linter
-```
-npm run test
-
-npm run lint
-```
-
## Documentation
+
You can find info about avalaible options for actions (Client class methods) in
[https://filestack.github.io/filestack-js/](https://filestack.github.io/filestack-js/)
## Contribution
-Any your contributions or ideas are more than welcome.
-Please consider that we follow the conventional commits specification to ensure consistent commit messages and changelog formatting.
+
+Any your contributions or ideas are more than welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
## Future
Current ideas:
+
- Better support for SSR, static site generator and isomorphic apps