Skip to content

Update cloudinary-jquery readme #287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
3 commits merged into from
Jan 25, 2022
Merged

Update cloudinary-jquery readme #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f366425
Update cloudinary-jquery readme
nirmaoz Jan 25, 2022
b839244
Fix cloudinary-jquery-file-upload link
nirmaoz Jan 25, 2022
ddcb3ce
Fix issues link
nirmaoz Jan 25, 2022
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Effortlessly optimize, transform, and upload your cloud's assets.

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

## About Cloudinary
Expand Down
2 changes: 1 addition & 1 deletion pkg/cloudinary-core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ See [cloudinary-jquery-file-upload](https://github.com/cloudinary/cloudinary_js/

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

## About Cloudinary
Expand Down
310 changes: 85 additions & 225 deletions pkg/cloudinary-jquery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,85 +1,55 @@
[![Build Status](https://travis-ci.org/cloudinary/cloudinary_js.svg?branch=master)](https://travis-ci.org/cloudinary/cloudinary_js) [![npm](https://img.shields.io/npm/v/cloudinary-jquery.svg?maxAge=2592000)]() [![Bower](https://img.shields.io/bower/v/cloudinary-jquery.svg?maxAge=2592000)]() [![license](https://img.shields.io/github/license/cloudinary/pkg-cloudinary-jquery.svg?maxAge=2592000)]()

# Cloudinary Client Side JavaScript Library - jQuery Plugin<br>`bower` and `npm` repository

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.

For Javascript, Cloudinary provides a jQuery plugin for simplifying the integration even further.

## Getting started guide

![](http://res.cloudinary.com/cloudinary/image/upload/see_more_bullet.png) **Take a look at our [Getting started guide for jQuery](http://cloudinary.com/documentation/jquery_integration#getting_started_guide)**.
Cloudinary jQuery Plugin
=======================================

## About
The Cloudinary JQuery Plugin 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 [Javascript SDK Guide](https://cloudinary.com/documentation/jquery_integration).


## Table of Contents
- [Key Features](#key-features)
- [Browser Support](#Browser-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)
- [File upload](#File-upload)
- [Contributions](#Contributions)
- [About Cloudinary](#About-Cloudinary)
- [Additional Resources](#Additional-Resources)
- [Licence](#Licence)

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

## Browser Support
Chrome, Safari, Firefox, IE 11

## Installation
#### Install the package using:
```bash
npm install cloudinary-jquery
```
Or
```bash
yarn add cloudinary-jquery
```

### bower

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
bower install cloudinary-jquery
```

1. Include the javascript file in your HTML. For Example:

```html
<script src="bower_components/jquery/dist/jquery.js" type="text/javascript"></script>
<script src="bower_components/cloudinary-jquery/cloudinary-jquery.js" type="text/javascript"></script>
```

### NPM

1. Install the files using:

```shell
npm install cloudinary-jquery
```
1. Include the javascript file in your HTML. For Example:

## Usage
### Setup
Include the javascript file in your HTML. For Example:
```html
<script src="node_modules/jquery/dist/jquery.js" type="text/javascript"></script>
<script src="node_modules/cloudinary-jquery/cloudinary-jquery.js" type="text/javascript"></script>
```

For the server side NPM library, please refer to https://github.com/cloudinary/cloudinary_npm.

## Setup

In order to properly use this library you have to provide it with a few configuration parameters:

Required:

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

Optional:

* `private_cdn`, `secure_distribution`, `cname`, `cdn_subdomain` - Please refer to [Cloudinary Documentation](http://cloudinary.com/documentation/rails_additional_topics#configuration_options) for information on these parameters.

To set these configuration parameters use the `Cloudinary::config` function (see below).

## Usage

The following blog post details the process of setting up a jQuery based file upload.
http://cloudinary.com/blog/direct_image_uploads_from_the_browser_to_the_cloud_with_jquery

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

### Cloudinary JavaScript library

The Cloudinary JavaScript library API reference can be found at: [https://cloudinary.github.io/pkg-cloudinary-jquery](https://cloudinary.github.io/pkg-cloudinary-jquery)

The Cloudinary JavaScript library provides several classes, defined under the "`cloudinary`" domain.

#### Configuration

Start by instantiating a new Cloudinary class:
### There are several ways to configure cloudinary-jquery:

##### As jQuery plugin

Expand All @@ -90,22 +60,19 @@ $.cloudinary.config({ cloud_name: "demo"});
```

##### Explicitly

```javascript
var cl = cloudinary.CloudinaryJQuery.new( { cloud_name: "demo"});
var cl = cloudinary.Cloudinary.new( { cloud_name: "demo"});
```

##### Using the config function

```javascript

// Using the config function
var cl = cloudinary.CloudinaryJQuery.new();
var cl = cloudinary.Cloudinary.new();
cl.config( "cloud_name", "demo");
```

##### From meta tags in the current HTML document

When using the library in a browser environment, you can use meta tags to define the configuration options.

The `init()` function is a convenience function that invokes both `fromDocument()` and `fromEnvironment()`.
Expand Down Expand Up @@ -138,164 +105,57 @@ var cl = cloudinary.Cloudinary.new();
cl.fromEnvironment();
// or
cl.init();

```

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

```javascript
cl.url("sample")
// "http://res.cloudinary.com/demo/image/upload/sample"
cl.url( "sample", { width: 100, crop: "fit"})
// "http://res.cloudinary.com/demo/image/upload/c_fit,w_100/sample"

```

#### HTML tag generation

You can generate HTML tags in several ways:

`Cloudinary::image()` generates a DOM tag, and prepares it for responsive functionality. This is the same functionality as `$.cloudinary.image()`. (When using the jQuery plugin, the `src-cache` data attribute is stored using jQuery's `data()` method and so is not visible.)

```javascript
cl.image("sample")
```
produces:
```html
<img src=​"http:​/​/​res.cloudinary.com/​demo/​image/​upload/​sample">​
```

You can generate an image Tag using the `imageTag` function:

```javascript
var tag = cl.imageTag("sample");
tag.toHtml();
```
which produces:
```html
<img src="http://res.cloudinary.com/demo/image/upload/sample">
```
and:
```javascript
tag.transformation().crop("fit").width(100).toHtml();
```
which produces:
```html
<img src="http://res.cloudinary.com/demo/image/upload/c_fit,w_100/sample">
```

You can also use `ImageTag` independently:

```javascript
var tag = cloudinary.ImageTag.new( "sample", { cloud_name: "some_other_cloud" });
tag.toHtml();
```
which produces:
```html
<img src="http://res.cloudinary.com/some_other_cloud/image/upload/sample">
```


#### Transformation

In addition to using a plain object to define transformations or using the builder methods (both described above), you can define transformations by using the Transformation class:

```javascript
var tr = cloudinary.Transformation.new();
tr.crop("fit").width(100);
tr.serialize()
// "c_fit,w_100"
```

You can also chain transformations together:

```javascript
var tr = cloudinary.Transformation.new();
tr.width(10).crop('fit').chain().angle(15).serialize()
// "c_fit,w_10/a_15"
```

### jQuery plugin

This Cloudinary jQuery plugin is backward compatible with the previous [cloudinary_js](https://github.com/cloudinary/cloudinary_js) version - except that it does not contain the jquery-file-upload dependency and functionality. For a fully compatible version, including the Blueimp jquery file upload functionality, refer to [cloudinary-jquery-file-upload](https://www.github.com/cloudinary/pkg-cloudinary-jquery-file-upload)

When loaded, the new JavaScript library instantiates a CloudinaryJQuery object and attaches it to jQuery.

The following list includes a sample of the API provided by this library:

* `$.cloudinary.config(parameter_name, parameter_value)` - Sets parameter\_name's value to parameter\_value.
* `$.cloudinary.url(public_id, options)` - Returns a cloudinary URL based on your configuration and the given options.
* `$.cloudinary.image(public_id, options)` - Returns an HTML image tag for the photo specified by public\_id
* `$.cloudinary.facebook_profile_image`, `$.cloudinary.twitter_profile_image`, `$.cloudinary.twitter_name_profile_image`, `$.cloudinary.gravatar_image` , `$.cloudinary.fetch_image` - Same as `image` but returns a specific type of image.

* `$(jquery_selector).cloudinary(options)` - Goes over the elements specified by the jQuery selector and changes all the images to be fetched using Cloudinary's CDN. Using options, you can also specify transformations to the images.
The `options` parameters are similar across all cloudinary frameworks. Please refer to [jQuery image manipulation](http://cloudinary.com/documentation/jquery_image_manipulation) for a more complete reference regarding the options.

![](http://res.cloudinary.com/cloudinary/image/upload/see_more_bullet.png) **See [our documentation](http://cloudinary.com/documentation/jquery_image_manipulation) for more information about displaying and transforming images using jQuery**.

### Other Cloudinary JavaScript libraries

#### Core Javascript library
The Core Cloudinary JavaScript library does not depend on jQuery: [https://github.com/cloudinary/pkg-cloudinary-core](https://github.com/cloudinary/pkg-cloudinary-core).

#### jQuery File upload
The Cloudinary jQuery File Upload library extends the Cloudinary jQuery plugin with support for the [Blueimp jQuery File Upload library](https://blueimp.github.io/jQuery-File-Upload/).
The library can be found at [https://github.com/cloudinary/pkg-cloudinary-jquery-file-upload](https://github.com/cloudinary/pkg-cloudinary-jquery-file-upload).

## Client side image resizing before upload

See the File Processing Options in https://github.com/blueimp/jQuery-File-Upload/wiki/Options.
Modify your script tags based on the the following example (order is important!):

```
<script src="node_modules/jquery/dist/jquery.js" type="text/javascript"></script>
<script src="node_modules/jquery.ui/ui/widget.js" type="text/javascript"></script>
<script src="node_modules/blueimp-load-image/js/load-image.all.min.js"></script>
<script src="node_modules/blueimp-canvas-to-blob/js/canvas-to-blob.min.js"></script>
<script src="node_modules/blueimp-file-upload/js/jquery.iframe-transport.js" type="text/javascript"></script>
<script src="node_modules/blueimp-file-upload/js/jquery.fileupload.js" type="text/javascript"></script>
<script src="node_modules/blueimp-file-upload/js/jquery.fileupload-process.js"></script>
<script src="node_modules/blueimp-file-upload/js/jquery.fileupload-image.js" type="text/javascript"></script>
<script src="node_modules/blueimp-file-upload/js/jquery.fileupload-validate.js"></script>
<script src="node_modules/cloudinary-jquery-file-upload/cloudinary-jquery-file-upload.js" type="text/javascript"></script>
```

Also, add the following javascript:

```javascript
$(document).ready(function() {
$('.cloudinary-fileupload').cloudinary_fileupload({
disableImageResize: false,
imageMaxWidth: 800, // 800 is an example value
imageMaxHeight: 600, // 600 is an example value
maxFileSize: 20000000, // 20MB is an example value
loadImageMaxFileSize: 20000000, // default is 10MB
acceptFileTypes: /(\.|\/)(gif|jpe?g|png|bmp|ico)$/i
});
// Apply a single transformation
cl.url( "sample", { crop: "scale", width: "200", angle: "10" })

// Chain (compose) multiple transformations
cl.url( "sample", {
transformation: [
{ angle: -45 },
{ effect: "trim", angle: "45", crop: "scale", width: "600" },
{ overlay: "text:Arial_100:Hello" }
]
});
```

## Additional resources

Additional resources are available at:

* [Website](http://cloudinary.com)
* [Documentation](http://cloudinary.com/documentation)
* [Knowledge Base](http://support.cloudinary.com/forums)
* [Documentation for jQuery integration](http://cloudinary.com/documentation/jquery_integration)
* [jQuery image upload documentation](http://cloudinary.com/documentation/jquery_image_upload)
* [jQuery image manipulation documentation](http://cloudinary.com/documentation/jquery_image_manipulation)
* [Image transformations documentation](http://cloudinary.com/documentation/image_transformations)
### Generate Image and Video HTML Tags
- Use the ```image()``` function to generate an HTMLImageElement
- Use the ```imageTag()``` function to generate an ImageTag instance
- Use the ```video()``` function to generate an HTMLVideoElement
- Use the ```videoTag()``` function to generate a VideoTag instance

## Support
### File upload
See [cloudinary-jquery-file-upload](https://github.com/cloudinary/cloudinary_js/tree/master/pkg/cloudinary-jquery-file-upload).

You can [open an issue through GitHub](https://github.com/cloudinary/cloudinary_js/issues).
## Contributions
- Ensure tests run locally (```npm run test```)
- Open a PR and ensure Travis tests pass

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

Stay tuned for updates, tips and tutorials: [Blog](http://cloudinary.com/blog), [Twitter](https://twitter.com/cloudinary), [Facebook](http://www.facebook.com/Cloudinary).
## 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.

## License

## Licence
Released under the MIT license.