Widget Developer Documentation

Images & Files

This document continues the discussion begun in the Mechanics section.

From a widget developer’s perspective, images can be retrieved from one of two locations. If you have images that are bundled with your widget, use the techniques described in the section on Bundled image assets. For images that require user interaction, see User-selected images below.

Other file types (such as PDFs) are discussed at the end of this document.

Basics

Every image you load should be run through Moboom::createImageUrl(). This API call ensures two things:

  1. That your images are loaded from the CDN for optimal transfer speed, and
  2. That your images are sized adaptively for the client device.

This API works for images that are stored in your widget as well as user-entered widgets. It also works for images loaded from an off-site URL.

Just to repeat: Moboom::createImageUrl() automatically resizes your images to fit the client device.

Bundled image assets

As discussed previously (see Mechanics), images can be bundled directly into your widget, and loaded from there. Use this technique if, for example, you are building a widget around a third-party library that includes images. Images loaded this way are typically those that are not user-configurable.

To load an image this way, you’ll need to use the Moboom::getBaseUrl() API, which creates a reference to a widget asset that can be loaded client-side.

$imgURL = Moboom::getBaseUrl() . 'test.jpg';
$img = Moboom::createImageUrl( $imgURL);
echo "<img src='$img' />";

User-selectable images

When you let a user select or upload an image using the widget settings, the code needed to retrieve and display that image is almost identical. We don’t need to use the Moboom::getBaseUrl() API.

The first example retrieves the image that the user has entered. As mentioned above, the image is automatically resized by Moboom::createImageUrl(), as needed for the client device.

$imgID = Moboom::getWidgetSetting( 'featured_image');
$img = Moboom::createImageUrl( $imgID);
echo "<img src='$img' />";

Keep in mind that for images, the value returned by Moboom::getWidgetSetting() is an object ID. This ID is useless except as an input to Moboom::createImageUrl().

The Moboom::createImageUrl() API takes an optional second parameter which indicates the maximum width of the image to be returned. In most cases, you should leave the second parameter blank, and let Moboom resize images for you. However, if you use this parameter properly, you can send specifically-sized images to your clients. This is one of the cornerstones of adaptive web design. The image will be scaled at the server, thus minimizing unnecessary bandwidth.

$img = Moboom::getWidgetSetting( 'featured_image');
if ( Moboom::deviceHasProfile( 'Mobile'))
    $url = Moboom::createImageUrl( $img, 700);
elseif ( Moboom::deviceHasProfile( 'Tablet'))
    $url = Moboom::createImageUrl( $img, 1200);
else
    $url = Moboom::createImageUrl( $img);
echo "<img src='$url' />";

The problem with the above code is that it mistakes device profile for device size. There is a time and place for profile checking, but image resizing is not one of them. This code is just presented as an example of one way to manually resize images.

Of course, you can combine profile-checking with size-checking. Consider a situation in which you wanted not only to resize images, but to do art direction as well. Perhaps you want to send the client one of three images — a laptop, a tablet, or a smartphone — based on the type of device, not its size. In this case, you should use device checks. Once you pick the correct image, you can scale it appropriately with the API.

Using images in CSS

You don’t have access to Moboom::createImageUrl() inside CSS. So you have to hard-code your image path into CSS, unfortunately. The following examples assume that you need to use an image as the background of a div.

Offsite images

If the image is stored offsite, there is nothing special to do. Simply reference your image normally:

.myImage {
    background:url(http://lorempixel.com/g/400/200);
}
Library images

If your image is stored in the library of your site, there are two important steps needed in order to use your image in CSS.

First, go to the library and find your image. When you click the image, you will see a popup window with some detailed information about how the image is stored in Moboom’s library. At the bottom of the window is the image’s File ID, which may be broken onto two lines. Copy this ID.

Next, use the following code in your CSS:

.myImage {
    background:url(/_img/FILEID);
}

The _img path is available from all Moboom sites. It loads the specified image and runs it through the same processing engine that is used by Moboom::createImageUrl(), which means you have access to the CDN as well as image scaling.

The image processor applies intelligent scaling to the image. If you want to override its behavior, you can do so, just as with the Moboom::createImgeUrl() API call. (See the docs on that API for notes.) When you use the _img processor, you can enforce a maximum width by suffixing your file ID with an underscore and the desired width.

For example, to use the image shown here with a maximum width of 100 pixels:

.myImage {
    background:url(/_img/2d703e9a-2fb0-b5d6-49a6-5307f00a3554_100);
}
Bundled images

If your CSS is also stored as an asset file in your widget and loaded using Moboom::registerCssFile(), then the path from the CSS file to the bundled image is relative. There’s no need to do anything other than what you would do to load an image in any other CSS file. Simply refer to the image directly, accounting for any subfolders that you may have created inside your widget. Do not use the _img processor prefix.

.myImage {
    background:url(../images/icon.png);
}

If you are using the default widget styles (see Settings), you cannot use bundled images. The image must be stored in the site library, and the file ID used in the _img processor, as described above.

Uploading images from a web page

You can build a widget that allows a site visitor to upload images, even without having access to the site studio.

For details, see Storing Data into Content Sets.

Other file types

You can let the user upload files other than images by using a File type widget setting. For example, the Favicon widget allows the user to upload an icon file (which is not a normal image that can be stored in the library). You can also use feature this to store PDFs or other documents.

To display, or otherwise link to, an uploaded file, use a similar technique to what was described above. In this case, there is a special processor located at /_file which will load your file properly. 

Here is a portion of the code from the Favicon widget:

$favicon_id   = Moboom::getWidgetSetting('favicon');
$favicon_file = "/_file/$favicon_id";

Images, as discussed above, can be uploaded either into a widget setting or directly into your library. Files, on the other hand, can only be uploaded into widget settings. Moboom does not currently allow you to upload non-image files into the library.