JarCastingCloudinary
The official Cloudinary SDK for Angular.
Cloudinary's AngularJS (AKA Angular1) SDK can be found here
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 Angular, Cloudinary provides an SDK for simplifying the integration even further. The SDK serves as a layer on top of one of Cloudinary's Javascript libraries:
| Github Repository | Package name | Description |
|---|---|---|
| pkg-cloudinary-core | cloudinary-core | Core Cloudinary Library. Use this if you do not intend to use jQuery |
| pkg-cloudinary-jquery | cloudinary-jquery | Core Library + jQuery plugin |
| pkg-cloudinary-jquery-file-upload | cloudinary-jquery-file-upload | Core Library + jQuery plugin + Blueimp File Upload adapter |
Live examples
Start experimenting right away with one of these live examples:
Installation
Install the SDK version that supports the Angular version you are using:
- For Angular 2, use
2.x - For Angular 4, use
4.x - For Angular 5-10, use
5.x
For example:
npm install @cloudinary/angular-5.x --save
Setup
Follow the setup procedure described in the Cloudinary jQuery plugin setup procedure. Refer to the sample projects in this repository for usage examples.
Usage
The module provides three types of directives:
- A Cloudinary image component with child transformation directives for creating
<image>tags and controlling its underlying chained transformations - A Cloudinary video component with child transformation directives for creating
<video>tags with multiple video sources and settings and controlling its underlying chained transformations - Attribute directives for enhancing native HTML elements with Cloudinary image management capabilities
Further image manipulation options are listed in this reference.
Further video manipulation and delivery capabilities see listed in this reference.
Note that the attribute names in the docs are using snake_case, however this SDK supports both snake_case and kebab-case for attribute names, e.g. both fetch_format: 'auto' and 'fetch-format': 'auto' are eventually translated to f_auto.
Cloudinary module configuration
This SDK is based on the Cloudinary JS module, however the two are decoupled, i.e. this module's Cloudinary is a configurable service to which you provide your choice of our JS module.
Example Coudinary configuration in your application's module definition:
import { NgModule } from '@angular/core';
// ...
import { CloudinaryModule, CloudinaryConfiguration } from '@cloudinary/angular-5.x';
import { Cloudinary } from 'cloudinary-core';
@NgModule({
imports: [
CloudinaryModule.forRoot({Cloudinary}, { cloud_name: 'your_cloud_name' } as CloudinaryConfiguration),
],
bootstrap: [/* ... */]
})
export class AppModule { }
See samples folder for a complete reference project.
Creating new image tags with cl-image & cl-transformation
The cl-image component generates an <image> tag with requested transformation, type, and format. The image tag can contain optional <cl-transformation> tags that will be used as chained transformations:
<cl-image public-id="readme" class="thumbnail inline" angle="20" format="jpg">
<cl-transformation height="150" width="150" crop="fill" effect="sepia" radius="20"></cl-transformation>
<cl-transformation overlay="text:arial_60:readme" gravity="north" y="20"></cl-transformation>
</cl-image>
Will be compiled by Angular to:
<cl-image _ngcontent-ywn-2="" public-id="readme" class="thumbnail inline" format="jpg" angle="20" ng-reflect-public-id="readme">
<img src="http://res.cloudinary.com/{your_cloud_name}/image/upload/c_fill,e_sepia,h_150,r_20,w_150/g_north,l_text:arial_60:readme,y_20/a_20/readme.jpg">
</cl-image>
Creating new video tags with cl-video & cl-transformation
The cl-video component generates a <video> tag with requested transformation, type, and format.
The generated <video> is created with configurable child <source> elements for all relevant formats supported by web browsers (webm, mp4 and ogv), as well as a poster thumbnail image.
The video tag can contain optional <cl-transformation> tags that will be used as chained transformations:
<cl-video cloud-name="my_other_cloud" public-id="watchme" secure="true" class="my-videos">
<cl-transformation overlay="text:arial_60:watchme" gravity="north" y="20"></cl-transformation>
</cl-video>
Will be compiled by Angular to:
<video class="my-videos" public-id="watchme" ng-reflect-public-id="watchme"
poster="https://res.cloudinary.com/my_other_cloud/video/upload/g_north,l_text:arial_60:watchme,y_20/watchme.jpg">
<source src="https://res.cloudinary.com/my_other_cloud/video/upload/g_north,l_text:arial_60:watchme,y_20/watchme.webm" type="video/webm">
<source src="https://res.cloudinary.com/my_other_cloud/video/upload/g_north,l_text:arial_60:watchme,y_20/watchme.mp4" type="video/mp4">
<source src="https://res.cloudinary.com/my_other_cloud/video/upload/g_north,l_text:arial_60:watchme,y_20/watchme.ogv" type="video/ogg">
</video>
Updating images and videos dynamically
You can update attributes dynamically for <cl-image> and <cl-video> elements to reload the underlying native elements with new transformations.
The following example from the sample projects demonstrates setting the opacity to 50% when hovering on top of an element:
<cl-image
public-id={{photo.public_id}}
(mouseenter)="photo.isMouseOver = true"
(mouseleave)="photo.isMouseOver = false"
[attr.opacity]="photo.isMouseOver ? '50' : null"
>
Attribute directives for enhancing HTML elements - clSrc, clHref, clSrcset
These directives transform the given URI to a cloudinary URL. For example:
<img clSrc="https://cloudinary.com/images/logo.png" type="fetch" fetch-format="auto" quality="auto">
Will be compiled by Angular to:
<img clSrc="https://cloudinary.com/images/logo.png" fetch-format="auto" quality="auto" type="fetch" ng-reflect-clSrc="https://cloudinary.com/images/logo.png"
src="http://res.cloudinary.com/{your_cloud_name}/image/fetch/f_auto,q_auto/https://cloudinary.com/images/logo.png">
See additional usage examples here and in the sample projects.
Samples
You can find our sample projects, along with documentation in the samples folder.
config.ts.sample in the sample of your choice and replace the placeholders with your credentials.
What's in the box
Both sample applications demonstrate a basic photo gallery showcasing basic image transformations and upload of new images either by a file input dialog or by drag-and-drop.
The samples differ by their bundling solution and upload implementation:
- Photo album sample app
- Uses ng2-file-upload for uploading files using an opensource file uploader
- Uses Webpack for bundling and serving the application
- Photo album sample app with jQuery
- Uses Cloudinary's jQuery plugin for uploading files using jQuery and blueimp.
- Uses SystemJS for bundling the application and lite-server for serving the application.
- Photo Album AOT compilation
- Demonstrates usage of Cloudinary SDK in an Angular AOT application
- Uses Rollup for bundling the application and lite-server for serving the application.
Please consult with the respective README file of each sample for usage and additional information.
Development
- lint - Runs tslint on **/*.ts
- test - Compiles TypeScript and runs unit tests on the generated JS files, re-running tests automatically on chages
- test-once - Compiles TypeSCript and executes unit tests once, closing the browser once it's done
- pree2e - Updates WebDriver binary
- start-sample - Starts the photo album sample, without automatically opening the browser and navingating to the started app
- start-sample:jquery - Same as start-sample for the jQuery sample
- install-sample-from-source - Compiles TypeScript, packs this module and installs it into samples/photo_album
- install-sample-from-source:jquery - Same as install-sample-from-source for the jQuery sample
- e2e - Runs install-sample-from-source, starts the app and runs protractor tests on the started app
- e2e:jquery - Same as e2e for the jQuery sample
- tsc - Runs the tsc compiler
- tsc:w - Runs the tsc compiler and watches for changes
- webdriver:update - Updates WebDriver binary
Additional resources
Additional resources are available at:
- Website
- Interactive demo
- Documentation
- Knowledge Base
- Documentation for Angular integration
- Image upload documentation
- Image transformations documentation
Support
You can open an issue through GitHub.
Contact us https://cloudinary.com/contact
Stay tuned for updates, tips and tutorials: Blog, Twitter, Facebook.
Join the Community
Impact the product, hear updates, test drive new features and more! Join here.
License
Released under the MIT license.
