Skip to content

Commit

Permalink
Fix sample README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@nirmaoz
nirmaoz committed Jan 25, 2022
1 parent 488d700 commit 8fe5a9e
Show file tree
Hide file tree
Showing 2 changed files with 163 additions and 225 deletions.
217 changes: 93 additions & 124 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,132 +1,101 @@

# Cloudinary React Library

Cloudinary is a cloud service that offers a solution to a web application's entire image management pipeline.

Easily upload images to the cloud. Automatically perform smart image resizing, cropping and conversion without installing any complex software. Integrate Facebook or Twitter profile image extraction in a snap, in any dimension and style to match your website’s graphics requirements. Images are seamlessly delivered through a fast CDN, and much much more.

Cloudinary offers comprehensive APIs and administration capabilities and is easy to integrate with any web application, existing or new.

Cloudinary provides URL and HTTP based APIs that can be easily integrated with any Web development framework.
Cloudinary React SDK
=========================
## About
The Cloudinary React SDK allows you to quickly and easily integrate your application with Cloudinary.
Effortlessly optimize and transform your cloud's assets.

#### Note
This Readme provides basic installation and usage information.
For the complete documentation, see the [React SDK Guide](https://cloudinary.com/documentation/react1_integration).


## Table of Contents
- [Key Features](#key-features)
- [Version Support](#Version-Support)
- [Installation](#installation)
- [Usage](#usage)
- [Setup](#Setup)
- [Transform and Optimize Assets](#Transform-and-Optimize-Assets)
- [Generate Image and HTML Tags](#Generate-Image-and-Video-HTML-Tags)

## Key Features
- [Transform](https://cloudinary.com/documentation/react1_video_manipulation#video_transformation_examples) and [optimize](https://cloudinary.com/documentation/react1_image_manipulation#image_optimizations) assets.
- Generate [image](https://cloudinary.com/documentation/react1_image_manipulation#deliver_and_transform_images) and [video](https://cloudinary.com/documentation/react1_video_manipulation#video_element) tags.

## Version Support
| SDK Version | React 15.3 | React 16.2 | React 16.3 | React 17 |
|---------------|------------|------------|------------|----------|
| 1.6.8 & up | X | X | V | V |
| 1.2.0 - 1.6.7 | X | X | V | X |
| 1.0.5 - 1.1.4 | X | V | X | X |
| 1.0.0 - 1.0.4 | V | X | X | X |

## Installation


### NPM

1. Install the files using the following command. Use the optional `--save` parameter if you wish to save the dependency in your `bower.json` file.

```shell
npm install cloudinary-react --save
```

1. Include the javascript files in your code. For Example:

```js
import {Image} from 'cloudinary-react';
```


## Setup

In order to properly use this library you have to provide it with a few configuration parameters. All configuration parameters can be applied directly to the element or using a CloudinaryContext element.


```js
ReactDOM.render(
<div>
<h1>Hello, world!</h1>
<Image cloudName="demo" publicId="sample" width="300" crop="scale"/>
// Or for more advanced usage:
// import {CloudinaryContext, Transformation} from 'cloudinary-react';
<CloudinaryContext cloudName="demo">
<Image publicId="sample">
<Transformation width="200" crop="scale" angle="10"/>
</Image>
</CloudinaryContext>
</div>,
document.getElementById('example')
);
### Install using your favorite package manager (yarn, npm)
```bash
npm install cloudinary-react
```
Or
```bash
yarn add cloudinary-react
```

Required:

* `cloudName` - The cloudinary cloud name associated with your Cloudinary account.

Optional:

* `privateCdn`, `secureDistribution`, `cname`, `cdnSubdomain` - Please refer to [Cloudinary Documentation](https://cloudinary.com/documentation/react_integration#3_set_cloudinary_configuration_parameters) for information on these parameters.


## Usage

The library includes 6 Components:

* CloudinaryContext
* Image
* Audio
* Video
* Transformation
* Placeholder - can only be used as child of an Image component

## Components Demo
Storybook for the components is available [here](https://cloudinary.github.io/cloudinary-react/)

### CloudinaryContext
CloudinaryContext allows you to define shared parameters that are applied to all children elements.

### Image
The Image element defines a Cloudinary Image tag.

### Video
The Video element defines a Cloudinary Video tag.

### Transformation
The Transformation element allows you to defined additional transformations on the parent element.

For example:

```
<Image cloudName="demo" publicId="sample">
<Transformation angle="-45"/>
<Transformation effect="trim" angle="45" crop="scale" width="600">
<Transformation overlay="text:Arial_100:Hello" />
</Transformation>
</Image>
### Setup
```javascript
import React from 'react';
import {Image, Video, Transformation} from 'cloudinary-react';
```


The Cloudinary Documentation can be found at:
https://cloudinary.com/documentation/react_integration

## Additional resources

Additional resources are available at:

* [Website](http://cloudinary.com)
* [Documentation](http://cloudinary.com/documentation)
* [Knowledge Base](http://support.cloudinary.com/forums)
* [Image transformations documentation](http://cloudinary.com/documentation/image_transformations)

## Support

You can [open an issue through GitHub](https://github.com/cloudinary/cloudinary_js/issues).

Contact us at [http://cloudinary.com/contact](http://cloudinary.com/contact).

Stay tuned for updates, tips and tutorials: [Blog](http://cloudinary.com/blog), [Twitter](https://twitter.com/cloudinary), [Facebook](http://www.facebook.com/Cloudinary).

## Join the Community ##########################################################

Impact the product, hear updates, test drive new features and more! Join [here](https://www.facebook.com/groups/CloudinaryCommunity).

## Updating github pages
The github pages source is the "gh-pages" branch. To generate updated storybook:
1. Switch to "gh-pages" branch
2. pull from master
3. rebuild storybook by running "npm run build-storybook"
4. commit and push

## License

### Transform and Optimize Assets
- [See full documentation](https://cloudinary.com/documentation/react1_image_manipulation)

```jsx
// Apply a single transformation
<Image cloudName="demo" publicId="sample">
<Transformation crop="scale" width="200" angle="10" />
</Image>
```

```jsx
// Chain (compose) multiple transformations
<Image cloudName="demo" publicId="sample">
<Transformation angle="-45" />
<Transformation effect="trim" angle="45" crop="scale" width="600" />
<Transformation overlay="text:Arial_100:Hello" />
</Image>
```
### Generate Image and Video HTML Tags
- Use <Image> to generate image tags
- Use <Video> to generate video tags

### File upload
This SDK does not provide file upload functionality, however there are [several methods of uploading from the client side](https://cloudinary.com/documentation/react1_image_and_video_upload).

## Contributions
- Ensure tests run locally (```npm run test```)
- Open a PR and ensure Travis tests pass

## Get Help
If you run into an issue or have a question, you can either:
- [Open a Github issue](https://github.com/CloudinaryLtd/cloudinary-react/issues) (for issues related to the SDK)
- [Open a support ticket](https://cloudinary.com/contact) (for issues related to your account)

## About Cloudinary
Cloudinary is a powerful media API for websites and mobile apps alike, Cloudinary enables developers to efficiently manage, transform, optimize, and deliver images and videos through multiple CDNs. Ultimately, viewers enjoy responsive and personalized visual-media experiences—irrespective of the viewing device.


## Additional Resources
- [Cloudinary Transformation and REST API References](https://cloudinary.com/documentation/cloudinary_references): Comprehensive references, including syntax and examples for all SDKs.
- [MediaJams.dev](https://mediajams.dev/): Bite-size use-case tutorials written by and for Cloudinary Developers
- [DevJams](https://www.youtube.com/playlist?list=PL8dVGjLA2oMr09amgERARsZyrOz_sPvqw): Cloudinary developer podcasts on YouTube.
- [Cloudinary Academy](https://training.cloudinary.com/): Free self-paced courses, instructor-led virtual courses, and on-site courses.
- [Code Explorers and Feature Demos](https://cloudinary.com/documentation/code_explorers_demos_index): A one-stop shop for all code explorers, Postman collections, and feature demos found in the docs.
- [Cloudinary Roadmap](https://cloudinary.com/roadmap): Your chance to follow, vote, or suggest what Cloudinary should develop next.
- [Cloudinary Facebook Community](https://www.facebook.com/groups/CloudinaryCommunity): Learn from and offer help to other Cloudinary developers.
- [Cloudinary Account Registration](https://cloudinary.com/users/register/free): Free Cloudinary account registration.
- [Cloudinary Website](https://cloudinary.com): Learn about Cloudinary's products, partners, customers, pricing, and more.


## Licence
Released under the MIT license.
171 changes: 70 additions & 101 deletions samples/photo_album/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,101 +1,70 @@
Cloudinary React SDK
=========================
## About
The Cloudinary React SDK allows you to quickly and easily integrate your application with Cloudinary.
Effortlessly optimize and transform your cloud's assets.

#### Note
This Readme provides basic installation and usage information.
For the complete documentation, see the [React SDK Guide](https://cloudinary.com/documentation/react1_integration).


## Table of Contents
- [Key Features](#key-features)
- [Version Support](#Version-Support)
- [Installation](#installation)
- [Usage](#usage)
- [Setup](#Setup)
- [Transform and Optimize Assets](#Transform-and-Optimize-Assets)
- [Generate Image and HTML Tags](#Generate-Image-and-Video-HTML-Tags)

## Key Features
- [Transform](https://cloudinary.com/documentation/react1_video_manipulation#video_transformation_examples) and [optimize](https://cloudinary.com/documentation/react1_image_manipulation#image_optimizations) assets.
- Generate [image](https://cloudinary.com/documentation/react1_image_manipulation#deliver_and_transform_images) and [video](https://cloudinary.com/documentation/react1_video_manipulation#video_element) tags.

## Version Support
| SDK Version | React 15.3 | React 16.2 | React 16.3 | React 17 |
|---------------|------------|------------|------------|----------|
| 1.6.8 & up | X | X | V | V |
| 1.2.0 - 1.6.7 | X | X | V | X |
| 1.0.5 - 1.1.4 | X | V | X | X |
| 1.0.0 - 1.0.4 | V | X | X | X |

## Installation
### Install using your favorite package manager (yarn, npm)
```bash
npm install cloudinary-react
```
Or
```bash
yarn add cloudinary-react
```

## Usage
### Setup
```javascript
import React from 'react';
import {Image, Video, Transformation} from 'cloudinary-react';
```

### Transform and Optimize Assets
- [See full documentation](https://cloudinary.com/documentation/react1_image_manipulation)

```jsx
// Apply a single transformation
<Image cloudName="demo" publicId="sample">
<Transformation crop="scale" width="200" angle="10" />
</Image>
```

```jsx
// Chain (compose) multiple transformations
<Image cloudName="demo" publicId="sample">
<Transformation angle="-45" />
<Transformation effect="trim" angle="45" crop="scale" width="600" />
<Transformation overlay="text:Arial_100:Hello" />
</Image>
```
### Generate Image and Video HTML Tags
- Use <Image> to generate image tags
- Use <Video> to generate video tags

### File upload
This SDK does not provide file upload functionality, however there are [several methods of uploading from the client side](https://cloudinary.com/documentation/react1_image_and_video_upload).

## Contributions
- Ensure tests run locally (```npm run test```)
- Open a PR and ensure Travis tests pass

## Get Help
If you run into an issue or have a question, you can either:
- [Open a Github issue](https://github.com/CloudinaryLtd/cloudinary-react/issues) (for issues related to the SDK)
- [Open a support ticket](https://cloudinary.com/contact) (for issues related to your account)

## About Cloudinary
Cloudinary is a powerful media API for websites and mobile apps alike, Cloudinary enables developers to efficiently manage, transform, optimize, and deliver images and videos through multiple CDNs. Ultimately, viewers enjoy responsive and personalized visual-media experiences—irrespective of the viewing device.


## Additional Resources
- [Cloudinary Transformation and REST API References](https://cloudinary.com/documentation/cloudinary_references): Comprehensive references, including syntax and examples for all SDKs.
- [MediaJams.dev](https://mediajams.dev/): Bite-size use-case tutorials written by and for Cloudinary Developers
- [DevJams](https://www.youtube.com/playlist?list=PL8dVGjLA2oMr09amgERARsZyrOz_sPvqw): Cloudinary developer podcasts on YouTube.
- [Cloudinary Academy](https://training.cloudinary.com/): Free self-paced courses, instructor-led virtual courses, and on-site courses.
- [Code Explorers and Feature Demos](https://cloudinary.com/documentation/code_explorers_demos_index): A one-stop shop for all code explorers, Postman collections, and feature demos found in the docs.
- [Cloudinary Roadmap](https://cloudinary.com/roadmap): Your chance to follow, vote, or suggest what Cloudinary should develop next.
- [Cloudinary Facebook Community](https://www.facebook.com/groups/CloudinaryCommunity): Learn from and offer help to other Cloudinary developers.
- [Cloudinary Account Registration](https://cloudinary.com/users/register/free): Free Cloudinary account registration.
- [Cloudinary Website](https://cloudinary.com): Learn about Cloudinary's products, partners, customers, pricing, and more.


## Licence
Released under the MIT license.
Cloudinary React Photo Album Sample
=======================================

This sample project shows:

1. How to use the Cloudinary React components.
2. How to upload files to Cloudinary in an unsigned manner, using an upload preset.
3. How to use the dynamic list resource in order to maintain a short list of resources aggregated by tags.
4. How to delete an image uploaded from the browser with an unsigned upload. You can find additional details in this [knowledge base article](https://support.cloudinary.com/hc/en-us/articles/202521132-How-to-delete-an-image-from-the-client-side-). Don't forget to set the `Return delete token` setting of your unsigned upload preset to `true`.

## Configuration ##

There are 2 settings you need to change for this demo to work. Copy or rename `src/config/config.js.sample` to `src/config/config.js` and edit the following:

1. **cloud_name** - Should be change to the cloud name you received when you registered for a Cloudinary account.
2. **upload_preset** - You should first "Enable unsigned uploads" in the ["Upload Settings"](https://cloudinary.com/console/settings/upload) of your Cloudinary console and assign the resulting preset name to that field. Note, you may want to tweak and modify the upload preset's parameters.
3. Additionally, in your Cloudinary console in the ["Security Settings"](https://cloudinary.com/console/settings/security) section you should uncheck the "list" item.

## Setup ##

Run `yarn` to install the required dependencies for this module.

## Running ##

Run `yarn start` to build the app and serve it using a local server.

The application is deployed at http://localhost:5000/

## Internals ##
This sample was created using [CRA](https://github.com/facebook/create-react-app).

### Sample main components ###

#### Routing ####

The application has 2 routes:

* **/photos** - Presents a list of images tagged by `myphotoalbum`
* **/photos/new** - Presents an upload control that allows uploading multiple files by a file input or drag-and-grop.
Uploads have a dynamic progress bar. In addition it displays the details of successful uploads.

The default route is set to `/photos`.

#### Main Components ####
> Photo list
* [App.js](src/components/App.js) the application root component. Fetches the displayed list of images.
* [PhotoList.js](src/components/PhotoList.js) displays the list of photos that was set to the state.
* [Photo.js](src/components/Photo.js) displays a single image.
* [PhotoThumbnail.js](src/components/PhotoThumbnails.js) displays the image transformations.

> Photo Upload
* [PhotosUploader.js](src/components/PhotosUploader.js) displays the upload control and lists the properties of the uploaded images once upload completes successfully.

**Important observations**:
* This implementation shows usage of both cloudinary file upload and a react upload control.
* Changes to the title field are sent in the upload request. This is meant to illustrate the possibility of attaching extra meta-data to each upload image.
* The upload control uses the `upload_preset` we configured in Configuration step. This uses the settings defined on Cloudinary side to process the uploaded file.

### Unsigned Upload ###

In order to add images to our photo album that would later be retrievable from the Cloudinary service we must select a tag which will serve as our source for the list. In this case `myphotoalbum`.
While this tag can be set in the upload preset and remain hidden from the client side, in this sample we included it in the request itself to make this sample work without further configuration steps.

### List Resource ###

Cloudinary supports a JSON list resource.
This list represents all resources marked with a specific tag during upload (or later through other APIs).
Whenever a new resource is uploaded with a tag, or an existing resource already tagged is deleted then the list is recalculated.
This enables you to group a list of resources which can be retrieved by a single query. The size of the list is currently limited to 100 entires.
[Learn more](http://cloudinary.com/documentation/image_transformations#client_side_resource_lists)

0 comments on commit 8fe5a9e

Please sign in to comment.