Skip to content

Commit b0befda

Browse files
NathanWalkerNathanWalker
committed
feat: cloudinary
1 parent b4d5b51 commit b0befda

4 files changed

Lines changed: 268 additions & 0 deletions

File tree

‎.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ export default defineConfig({
6464
{ text: 'CardView', link: '/plugins/cardview' },
6565
{ text: 'Carousel', link: '/plugins/carousel' },
6666
{ text: 'Blur', link: '/plugins/blur' },
67+
{ text: 'Cloudinary', link: '/plugins/cloudinary' },
6768
{ text: 'Variable Blur View', link: '/plugins/variable-blur-view' },
6869
{ text: 'Loading Indicator', link: '/plugins/loading-indicator' },
6970
{ text: 'Shimmer', link: '/plugins/shimmer' },

‎.vitepress/theme/PluginsHome.vue‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,15 @@ const plugins = [
106106
href: '/plugins/blur',
107107
featured: false,
108108
},
109+
{
110+
name: '@nstudio/nativescript-cloudinary',
111+
title: 'Cloudinary',
112+
description: 'Cloudinary-hosted images with native URL generation and transformation APIs.',
113+
icon: '☁️',
114+
gradient: 'from-sky-500 to-teal-500',
115+
href: '/plugins/cloudinary',
116+
featured: false,
117+
},
109118
{
110119
name: '@nstudio/nativescript-exoplayer',
111120
title: 'ExoPlayer',

‎content/plugins/cloudinary.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# Cloudinary
2+
3+
Native Cloudinary image delivery for NativeScript.
4+
5+
The plugin supports:
6+
7+
- A declarative `ImageCloudinary` component with an `options` property
8+
- Native Cloudinary SDK URL generation on both platforms
9+
- Top-level shorthand transformations, chained transformations, or raw transformation strings
10+
- Programmatic URL generation via `generateUrl`
11+
- Compatible with Angular, React, Solid, Svelte, and Vue
12+
13+
## Installation
14+
15+
```bash
16+
npm install @nstudio/nativescript-cloudinary
17+
```
18+
19+
## Setup
20+
21+
Initialize Cloudinary once before using the component or calling `generateUrl`.
22+
23+
```typescript
24+
import { init } from '@nstudio/nativescript-cloudinary';
25+
26+
init('your_cloud_name', 'your_api_key', 'your_api_secret');
27+
```
28+
29+
`init` accepts an optional fourth `secure` argument which defaults to `true`.
30+
31+
> `init` requires your Cloudinary API secret. If your app should not embed signing credentials on-device, generate signed URLs on your server and pass the resulting URL into your app instead.
32+
33+
## Usage
34+
35+
### NativeScript Core
36+
37+
```xml
38+
<Page xmlns="http://schemas.nativescript.org/tns.xsd"
39+
xmlns:cl="@nstudio/nativescript-cloudinary"
40+
navigatingTo="navigatingTo">
41+
<GridLayout class="p-24">
42+
<cl:ImageCloudinary
43+
stretch="aspectFill"
44+
options="{{ heroImage }}"
45+
/>
46+
</GridLayout>
47+
</Page>
48+
```
49+
50+
```typescript
51+
import { EventData, Page } from '@nativescript/core';
52+
import { ImageCloudinaryOptions } from '@nstudio/nativescript-cloudinary';
53+
54+
export function navigatingTo(args: EventData) {
55+
const page = args.object as Page;
56+
page.bindingContext = new DemoModel();
57+
}
58+
59+
class DemoModel {
60+
heroImage: ImageCloudinaryOptions = {
61+
src: 'cld-sample',
62+
width: 900,
63+
height: 900,
64+
crop: 'fill',
65+
gravity: 'face',
66+
format: 'auto',
67+
quality: 'auto',
68+
};
69+
}
70+
```
71+
72+
### Transformation Modes
73+
74+
`ImageCloudinaryOptions` supports three transformation styles.
75+
76+
Top-level shorthand:
77+
78+
```typescript
79+
const options: ImageCloudinaryOptions = {
80+
src: 'cld-sample',
81+
width: 900,
82+
height: 900,
83+
crop: 'fill',
84+
gravity: 'face',
85+
};
86+
```
87+
88+
Chained transformations:
89+
90+
```typescript
91+
const options: ImageCloudinaryOptions = {
92+
src: 'cld-sample',
93+
transformations: [
94+
{ width: 900, height: 900, crop: 'fill', gravity: 'auto' },
95+
{ effect: 'sepia' },
96+
{ radius: 'max' },
97+
{ format: 'auto', quality: 'auto' },
98+
],
99+
};
100+
```
101+
102+
Raw transformation string:
103+
104+
```typescript
105+
const options: ImageCloudinaryOptions = {
106+
src: 'cld-sample',
107+
rawTransformation: 'c_thumb,g_face,h_300,w_300/r_max/f_auto/q_auto',
108+
};
109+
```
110+
111+
Priority order: `rawTransformation` > `transformations` > top-level shorthand properties.
112+
113+
## Framework Registration
114+
115+
### Angular
116+
117+
```typescript
118+
import { registerElement } from '@nativescript/angular';
119+
import { ImageCloudinary } from '@nstudio/nativescript-cloudinary';
120+
121+
registerElement('ImageCloudinary', () => ImageCloudinary);
122+
```
123+
124+
### Other Flavors
125+
126+
```typescript
127+
import { ImageCloudinary } from '@nstudio/nativescript-cloudinary';
128+
129+
// React
130+
registerElement('imageCloudinary', () => ImageCloudinary);
131+
132+
// Solid
133+
registerElement('imageCloudinary', ImageCloudinary);
134+
135+
// Svelte
136+
registerNativeViewElement('imageCloudinary', () => ImageCloudinary);
137+
138+
// Vue
139+
registerElement('ImageCloudinary', () => ImageCloudinary);
140+
```
141+
142+
## Programmatic URL Generation
143+
144+
Generate a Cloudinary URL without rendering the component:
145+
146+
```typescript
147+
import { generateUrl } from '@nstudio/nativescript-cloudinary';
148+
149+
const url = generateUrl({
150+
src: 'cld-sample',
151+
width: 600,
152+
crop: 'scale',
153+
format: 'auto',
154+
quality: 'auto',
155+
});
156+
```
157+
158+
## API Reference
159+
160+
### Functions
161+
162+
| Function | Signature | Description |
163+
| --- | --- | --- |
164+
| `init` | `(cloudName: string, apiKey: string, apiSecret: string, secure?: boolean) => void` | Initializes the native Cloudinary SDK. Call once before using the plugin. |
165+
| `generateUrl` | `(options: ImageCloudinaryOptions) => string \| null` | Builds a Cloudinary delivery URL from the provided options. Returns `null` when input is missing or initialization has not happened yet. |
166+
167+
### Properties
168+
169+
| Property | Type | Description |
170+
| --- | --- | --- |
171+
| `options` | `ImageCloudinaryOptions` | Registered NativeScript property on `ImageCloudinary` that builds the Cloudinary URL and assigns it to the underlying `Image.src`. |
172+
173+
### Classes
174+
175+
| Class | Description |
176+
| --- | --- |
177+
| `ImageCloudinary` | A drop-in `Image` subclass that renders Cloudinary-hosted assets from `options`. |
178+
179+
`ImageCloudinary` also exposes a static `debug` flag:
180+
181+
```typescript
182+
import { ImageCloudinary } from '@nstudio/nativescript-cloudinary';
183+
184+
ImageCloudinary.debug = true;
185+
```
186+
187+
### Events
188+
189+
The plugin does not add custom events. Use the standard NativeScript `Image` events and lifecycle behavior when needed.
190+
191+
### Types
192+
193+
| Type | Description |
194+
| --- | --- |
195+
| `ImageCloudinaryOptions` | Top-level configuration for the component or `generateUrl`. |
196+
| `CloudinaryTransformation` | A single transformation step in a chained transformation pipeline. |
197+
| `CropMode` | Supported Cloudinary crop modes such as `fill`, `fit`, `scale`, and `thumb`. |
198+
| `Gravity` | Supported gravity modes such as `auto`, `face`, `faces`, and positional values. |
199+
| `ImageFormat` | Supported delivery formats such as `auto`, `jpg`, `png`, `webp`, and `avif`. |
200+
201+
## CloudinaryTransformation
202+
203+
Each `CloudinaryTransformation` entry supports the following fields:
204+
205+
| Property | Type | Description |
206+
| --- | --- | --- |
207+
| `width` | `number \| string` | Width |
208+
| `height` | `number \| string` | Height |
209+
| `crop` | `CropMode` | Crop mode such as `fill`, `fit`, `scale`, `thumb`, or `pad` |
210+
| `gravity` | `Gravity` | Gravity such as `auto`, `face`, `faces`, or `center` |
211+
| `aspectRatio` | `string \| number` | Aspect ratio |
212+
| `x` | `number \| string` | Horizontal offset |
213+
| `y` | `number \| string` | Vertical offset |
214+
| `zoom` | `number \| string` | Zoom level |
215+
| `format` | `ImageFormat` | Delivery format such as `auto`, `webp`, or `avif` |
216+
| `fetchFormat` | `string` | Fetch format override |
217+
| `quality` | `string \| number` | Delivery quality such as `auto` or `80` |
218+
| `dpr` | `string \| number` | Device pixel ratio |
219+
| `effect` | `string` | Effect such as `sepia`, `grayscale`, or `blur:800` |
220+
| `radius` | `number \| string` | Corner radius, including `max` for circular crops |
221+
| `border` | `string` | Border string such as `5px_solid_rgb:0066ff` |
222+
| `background` | `string` | Background color or special values such as `auto:border` |
223+
| `color` | `string` | Foreground color |
224+
| `colorSpace` | `string` | Color space |
225+
| `angle` | `number \| string` | Rotation angle or flip values |
226+
| `flags` | `string \| string[]` | Cloudinary transformation flags |
227+
| `overlay` | `string` | Overlay public ID or text spec |
228+
| `underlay` | `string` | Underlay public ID |
229+
| `opacity` | `number \| string` | Opacity from `0` to `100` |
230+
| `page` | `number \| string` | Page or frame number |
231+
| `density` | `number \| string` | DPI density |
232+
| `defaultImage` | `string` | Fallback public ID |
233+
| `named` | `string` | Named transformation |
234+
| `variables` | `Record<string, string \| number>` | User-defined Cloudinary variables |
235+
| `rawTransformation` | `string` | Raw transformation segment appended as-is |
236+
237+
## ImageCloudinaryOptions
238+
239+
`ImageCloudinaryOptions` adds delivery metadata on top of transformation settings:
240+
241+
| Property | Type | Description |
242+
| --- | --- | --- |
243+
| `src` | `string` | Required Cloudinary public ID |
244+
| `resourceType` | `'image' \| 'video' \| 'raw' \| 'auto'` | Resource type, defaults to `image` |
245+
| `type` | `'upload' \| 'fetch' \| 'private' \| 'authenticated'` | Delivery type, defaults to `upload` |
246+
| `version` | `string` | Version string such as `v1685472103` |
247+
| `extension` | `string` | File extension override |
248+
| `transformations` | `CloudinaryTransformation[]` | Ordered chain of transformation components |
249+
| `rawTransformation` | `string` | Full raw transformation string |
250+
251+
Top-level shorthand on `ImageCloudinaryOptions` also supports commonly used transformation fields such as `width`, `height`, `crop`, `gravity`, `effect`, `radius`, `format`, `quality`, `dpr`, `background`, `border`, `color`, `angle`, `opacity`, `overlay`, `underlay`, `flags`, `aspectRatio`, `defaultImage`, `fetchFormat`, `zoom`, `x`, `y`, `page`, `density`, and `named`.
252+
253+
For `colorSpace` or `variables`, use the `transformations` array.
254+
255+
## License
256+
257+
Apache License Version 2.0

‎content/plugins/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ A collection of high-quality NativeScript plugins from nStudio. Native performan
1111
- [CardView](/plugins/cardview) - Material Design CardView component
1212
- [Carousel](/plugins/carousel) - Smooth carousel with page indicators
1313
- [Blur](/plugins/blur) - Apply blur effects to any view
14+
- [Cloudinary](/plugins/cloudinary) - Cloudinary-hosted images with native URL generation and transformation APIs
1415
- [Loading Indicator](/plugins/loading-indicator) - Native loading indicators
1516
- [Fancy Alert](/plugins/fancyalert) - Beautiful alert dialogs with animations
1617
- [Filterable Listpicker](/plugins/filterable-listpicker) - Modal listpicker with search filtering

0 commit comments

Comments
 (0)