AndreaVitale / av.imageview

Titanium native ImageView module that extends the default Titanium ImageView with more capabilities and a different caching system.
MIT License
96 stars 29 forks source link
android appcelerator appcelerator-titanium images imageview ios native titanium titanium-mobile titanium-module

av.imageview

An optimized ImageView module
for Axway Appcelerator Titanium Framework


Features | Installation | API | Usage | Contributions

Features

Currently Titanium.UI.ImageView doesn't support the contentMode property so your rendered image will everytime fit your ImageView. The main feature of this module is contentMode handling that allows you to specify which behavior your ImageView must have and, in addition, the module adds some extra features like image caching and placeholder-fallback images.

Here is an example of two mainly supported content modes: CONTENT_MODE_ASPECT_FIT and CONTENT_MODE_ASPECT_FILL.

         

All other macro-features can be grouped in the following list:

Installation

Pick the latest version of the module from here and unzip it inside your application module folder or install it automatically via gitt.io

$ gittio install av.imageview

In your application's tiapp.xml the av.imageview module is declared as follows:

<modules>
    <module platform="iphone">av.imageview</module>
    <module platform="android">av.imageview</module>
</modules>

and you're ready to use it.

API

All Titanium.UI.View properties and methods are supported.

Property Description iOS Android Note
contentMode Sets the ImageView content mode Supported content modes are listed in a next section.
defaultImage Image to display when the image download is in progress Must refers to a local image ; Android must be set before assigning an image (e.g. at creation)
brokenLinkImage Image to display when the image fetch goes in error Must refers to a local image; Android must be set before assigning an image (e.g. at creation)
loadingIndicator Enable or disable the activity indicator when the download is in progress true by default
loadingIndicatorColor Changes the loading indicator color
requestHeaders An object used to define extra http request header fields
timeout Sets timeout for requests, in milliseconds
handleCookies Enables cookie handling for remote images
shouldCacheImagesInMemory Activates in-memory cache mechanism true by default
avoidDecodeImage Disable image decompression 🚫 false by default
maxCacheAge The maximum length of time to keep an image in the cache, in seconds 🚫 integer value
maxCacheSize The maximum size of the cache, in bytes 🚫 integer value
rounded Renders the image in a circle 🚫 Use with CONTENT_MODE_ASPECT_FIT for a correct rendering
animated Disables the fade-in animation 🚫
signature Sets a custom caching signature (Glide documentation) 🚫 string value

Events

Supported content modes

Here is a list of supported content modes:

Android and iOS

iOS only

Usage

You can simply use this module by declaring an ImageView in your controller.xml file as follows:

    <ImageView id="Photo" module="av.imageview" />

and style it by using the related controller.tss file:

    "#Photo": {
        width: Ti.UI.FILL,
        height: 200,
        contentMode: Alloy.Globals.CONTENT_MODE_FILL,
        loadingIndicatorColor: "red"
    }

and of course expose as a global variable your desired CONTENT_MODE inside Alloy.Globals namespace.

ListView ItemTemplate

Using the module in a ListItemTemplate is a bit difference because custom module proxies cannot be directly used inside of it.

    <ItemTemplate>
        <ImageView ns="AvImageview" />
    </ItemTemplate>

where AvImageview is a variable declared in alloy.js like as follows:

    const AvImageview = require("av.imageview");
    global.AvImageview = AvImageview;

    //and to use contentmodes constants via alloy
    Alloy.Globals.CONTENT_MODE_FIT = AvImageview.CONTENT_MODE_ASPECT_FIT;
    Alloy.Globals.CONTENT_MODE_FILL = AvImageview.CONTENT_MODE_ASPECT_FILL;

    //If you need to access to protected images you can define which request header fields the module has to use for every request
    Alloy.Globals.REQUEST_HEADERS = {
        'Authorization': 'place or assign dinamically your logged user access token',
        'Another HTTP header field': 'with its value'
    };

A complete example can be:

    <ListView id="Images" defaultItemTemplate="template">
        <Templates>
            <ItemTemplate name="template" height="160">
                <ImageView ns="AvImageview" bindId="photo" height="160" width="Ti.UI.FILL" loadingIndicator="true" contentMode="Alloy.Globals.CONTENT_MODE_FILL" requestHeader="Alloy.Globals.REQUEST_HEADERS" />
            </ItemTemplate>
        </Templates>
        <ListSection>
            <ListItem template="template" photo:image="http://www.nationalgeographic.com/content/dam/photography/photos/000/060/6018.ngsversion.1467254523217.adapt.1900.1.jpg"></ListItem>
            <ListItem template="template" photo:image="http://www.italiangoodnews.com/wp-content/uploads/2014/11/italy-04.jpg"></ListItem>
            <ListItem template="template" photo:image="https://walkingtree.org/wp-content/uploads/2015/09/Elia-Locardi-Whispers-From-The-Past-The-Colosseum-Rome-Italy-1280-WM.jpg"></ListItem>
            <ListItem template="template" photo:image="http://wp-admin.goldenbird-italy.com/wp-content/uploads/2015/07/italy_2631046a.jpg"></ListItem>
            <ListItem template="template" photo:image="http://www.travelviaitaly.com/wp-content/uploads/2015/12/Rome-Italy.jpg"></ListItem>
        </ListSection>
    </ListView>

Do you want a more complete example? Look a the sample app.js.

Contributions

If you enjoy this module, feel free to contribute with your PR or donate :-)