ionic-image-loader-v5
v1.0.2TypeScript
ionic-image-loader to Ionic 5
54/weekUpdated 3 years agoUnpacked: 902.0 KB
Published by alexowson
npm install ionic-image-loader-v5ionic-image-loader for ionic v5
Installation
#### 1. Install the NPM Package
``
npm i --save ionic-image-loader-v5
#### 2. Install Required Plugins
`
npm i --save @ionic-native/ionic-webview
npm i --save @ionic-native/file
ionic cordova plugin add cordova-plugin-file
#### 3. Import IonicImageLoader module
Add IonicImageLoaderModule and WebView in your app's root module
`typescript
import { IonicImageLoader } from 'ionic-image-loader-v5';
import { WebView } from '@ionic-native/ionic-webview/ngx';
// import the module
@NgModule({
...
imports: [
IonicImageLoaderModule
],
providers: [
WebView
]
})
export class AppModule {}
`
Then add IonicImageLoader in your child/shared module(s)
`typescript
import { IonicImageLoaderModule } from 'ionic-image-loader-v5';
@NgModule({
...
imports: [
IonicImageLoaderModule
]
})
export class SharedModule {}
`
Usage
Basic Usage
This HTML code demonstrates basic usage of this module:
`
html
`By default, the module sets the image as the background of the
element. If you want the module to use the image as an tag inside the element, just add useImg attribute as shown below:
`html
`You can also listen to the load event to be notified when the image has been loaded:
html
`typescript
import { ImgLoaderComponent } from 'ionic-image-loader';...
onImageLoad(imgLoader: ImgLoaderComponent) {
// do something with the loader
}
`Advanced Usage
The component takes many attributes that allows you to customize the image. You can use the following table as a reference:| Attribute Name | Type | Description | Default Value |
| --- | --- | --- | --- |
| src | string | The image URL | N/A |
| fallbackUrl | string | Fallback image url to load in case the original image fails to load | N/A |
| spinner | boolean | Show a spinner while the image loads | true |
| useImg | boolean | Use
tag to display the image in | false |
| width | string | The width of the image. This is ignored if useImg is set to true. | 100% |
| height | string | The height of the image. This is ignored if useImg is set to true. | 100% |
| display | string | Sets the display CSS property of the element. This is ignored if useImg is set to true. | block |
| backgroundSize | string | Sets the background-size CSS property of the element. This is ignored if useImg is set to true. | contain |
| backgroundRepeat | string | Sets the background-repeat CSS property of the element. This is ignored if useImg is set to true. | no-repeat |
| fallbackAsPlaceholder | boolean | Use fallback as a placeholder until the image loads. | false |
| imgAttributes | ImageAttribute[] | An array of ImageAttribute objects (element, value). If useImg == true, this array will be iterated and each object added as an attribute to the generated HTML element. | []] |
Note: The default values can be changed using the global configuration feature.
Quirks
In some cases, images won't load on the first time, the culprit seems to be @ionic-native/file or cordova-plugin-file in its writeFile function not calling resolve or reject.In the meantime we find a solution, here's a quick workaround:
In ./src/index.html move your
polyfill.jsinclude above cordova.js
Global Configuration
This is optional but it is helpful if you wish to set the global configuration for all of your instances. To configure the module, inject the ImageLoaderConfigService provider in your app's main component.
`typescript
import { ImageLoaderConfigService } from 'ionic-image-loader';
@Component({
...
})
export class MyMainAppComponent {
constructor(
private imageLoaderConfig: ImageLoaderConfigService // optional, if you wish to configure the service
){
// disable spinners by default, you can add [spinner]="true" to a specific component instance later on to override this
imageLoaderConfig.enableSpinner(false);
// set the maximum concurrent connections to 10
imageLoaderConfig.setConcurrency(10);
}
}
`Below are all the methods that the config provider has:
#### enableDebugMode()
Enables debug mode to receive console logs, errors, warnings.
Example:
typescript
// enable debug mode to get console errors/warnings/logs
// this could be useful while trying to debug issues with the component
this.imageLoaderConfig.enableDebugMode();
`
---
#### enableSpinner(enable: boolean)
Sets the cache directory name. Defaults to 'image-loader-cache'. Defaults to .Example:
`typescript
this.imageLoaderConfig.enableSpinner(false); // disable spinner by default
`---
#### setHeight(height: string)
Set default height for images that are not using ![]()
tag. Defaults to
.---
#### setWidth(width: string)
Set default width for images that are not using ![]()
tag. Defaults to
100%.Example:
`typescript
this.imageLoaderConfig.setWidth('500px'); // set default width to 500px
`---
#### setDisplay(display: string)
Enable display mode for images that are not using ![]()
tag. Defaults to
.Example:
`typescript
this.imageLoaderConfig.setDisplay('inline-block');
`
---
#### useImageTag(use: boolean)
Use ![]()
tag by default.Example:
typescript
this.imageLoaderConfig.useImageTag(true); // use tag by default
`---
#### setBackgroundSize(backgroundSize: string)
Set default background size for images that are not using ![]()
tag. Defaults to
.Example:
`typescript
this.imageLoaderConfig.setBackgroundSize('cover');
`
---
#### setBackgroundRepeat(backgroundRepeat: string)
Set background repeat for images that are not using ![]()
tag. Defaults to .Example:
`typescript
this.imageLoaderConfig.setBackgroundRepeat('repeat-x');
`
---#### setFallbackUrl(fallbackUrl: string)
Set fallback URL to use when image src is undefined or did not resolve.
This image will not be cached. This should ideally be a locally saved image.
Example:
typescript
this.imageLoaderConfig.setFallbackUrl('assets/fallback.png'); // if images fail to load, display this image instead
`---
#### setCacheDirectoryName(directoryName: string)
Set a custom directory name to store the cached images in. The cache directory by default is named
.Example:
`typescript
this.imageLoaderConfig.setCacheDirectoryName('my-custom-cache-directory-name');
`
---#### setConcurrency(concurrency: number)
Set the maximum number of concurrent connections. Cached images will be loaded instantly, this limit is only for new images.
Example:
typescript
this.imageLoaderConfig.setConcurrency(5); // 5 concurrent connections
`
---
#### setMaximumCacheSize(cacheSize: number)
Sets the maximum cache size in bytes.Example:
typescript
this.imageLoaderConfig.setMaximumCacheSize(20 1024 1024); // set max size to 20MB
`
---
#### setMaximumCacheAge(cacheAge: number)
Sets the maximum allowed cache age in millisecondsExample:
typescript
this.imageLoaderConfig.setMaximumCacheAge(7 24 60 60 1000); // 7 days
`
---
#### setImageReturnType(imageReturnType: string)
Set the return type of cached images. By default this option is set to 'uri', which will return the native file URL. If you want to get a base64-encoded representation of the file set the return type to 'base64'.Example:
typescript
this.imageLoaderConfig.setImageReturnType('base64');
`
---
#### enableFallbackAsPlaceholder(enable: boolean)
Enable/Disable the fallback image as placeholder instead of the spinner. Defaults to false.Example:
ts
this.imageLoaderConfig.enableFallbackAsPlaceholder(true);
`
---
#### setHttpHeaders(headers: HttpHeaders)
Set headers for HttpClient to use.Example:
ts
const headers = new HttpHeaders()
.set("Authorization", "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==");
this.imageLoaderConfig.setHttpHeaders(headers);
`
---
#### setFileNameCachedWithExtension(enable: boolean)
Enable/Disable the save filename of cached images with extension. Defaults to false.Example:
ts
this.imageLoaderConfig.setFileNameCachedWithExtension(true);
`
---
#### setFallbackFileNameCachedExtension(extension: string)
Sometime url missing extension, in this case you can set fallback as default extension. Defaults to '.jpg'Example:
ts
this.imageLoaderConfig.setFallbackFileNameCachedExtension('.png');
`
---Preloading images
typescript
import { ImageLoaderService } from 'ionic-image-loader';class MyComponent {
constructor(imageLoader: ImageLoaderService) {
imageLoader.preload('http://path.to/image.jpg');
}
}
`Clearing the cache
typescriptimport { ImageLoaderService } from 'ionic-image-loader';
@Component(...)
class MyComponent {
constructor(imageLoader: ImageLoaderService) {
imageLoader.clearCache();
}
}
`Clearing single image cache
typescriptimport { ImageLoaderService } from 'ionic-image-loader';
@Component(...)
class MyComponent {
constructor(imageLoader: ImageLoaderService) {
imageLoader.clearImageCache('http://path.to/image.jpeg');
}
}
`Passing HTML / CSS Attributes to a generated image
When using ImageLoader to generate an
element it may be desirable for the generated element to include additional attributes to provide styling or interaction qualities. The optional imgAttributes value can be used to provide such additional attributes which will be included in the generated element in the DOM.Usage:
1. Include the ImageAttribute model in your .ts
`typescript
import { ImageAttribute } from 'ionic-image-loader'
`2. Generate an array of ImageAttribute objects
typescript
const imageAttributes: ImageAttribute[] = [];
imageAttributes.push({
element: 'class',
value: 'circle-photo'
})
`3. Include the
element in the img-loader element of your HTML
`html
`4. The generated
tag will be rendered with the specified attributes
`html
``Contribution
- Having an issue? or looking for support? Open an issue and we will get you the help you need.
- Got a new feature or a bug fix? Fork the repo, make your changes, and submit a pull request.
Support this project
If you find this project useful, please star the repo to let people know that it's reliable. Also, share it with friends and colleagues that might find this useful as well. Thank you :smile: