Data URI Creator

The Data URI Creator is a lightweight standalone module that implements a utility page for manual generation of Data URIs (see RFC 2397: The data URL scheme). The tool can be particularly useful when you craft HTML pages, CSS or JSON data by hand and want to embed images directly in the content, as opposed to indirectly through a link to a separate image file.

The module also provides a lean API that can be used programmatically to detect, encode and decode Data URIs (through the DataUriCreator class). Therefore, other modules that work with Data URIs can reference the Data URI Creator module as a common API to perform encoding and decoding of such URIs.

Evaluation

To evaluate this Drupal project online, go to the simplytest.me website. Once there, with this project selected, click on Launch sandbox and wait a few seconds for setup to complete. Then, click on the new Drupal website's Log in button, and from the Navigation menu select Data URI Creator. This will get you to the main Data URI Creator page from where you can create a Data URI manually by following the instructions that are documented in the Operation section below.

Prerequisites

This module has no extra requirements, except for a functional Drupal website. However, one may optionally choose to enable Drupal's built-in Testing module (a.k.a. simpletest) to be able to run the tests provided by this module.

Installation

The module's installation procedure is the standard one. Refer to the Drupal Installation Guide about Installing Contributed Modules.

In summary, one simply needs to:

1. Download the module to the Drupal server,
2. Extract the module's files into a folder for contributed modules, and
3. Enable the Data URI Creator module through the administrator interface.

Configuration

No further configuration is required after the module is installed and enabled, unless the utility page should be made available also to anonymous or other specific users.

To achieve this, one may optionally tweak the default settings through the Configuration » Data URI Creator settings page:

• Specify the maximum allowed byte-size for data uploads, and
• Decide whether to make the Data URI Creator page publicly available to all users or privately only to administrators. For more granular access control, use the Data URI Creator permissions on the regular permissions page.

Note: Also refer to the module's built-in help.

Operation

The Data URI Creator page is used to create a Data URI from an uploaded file, such as from a small PNG image. From the utility page, select the Data File to be converted to a Data URI. Then, click on the Create Data URI button. Upon success, the Data URI will be displayed in a text box. One can now Select All text from the box, and then Copy and Paste the data where needed. Repeat the process, if desired.

Note: Also refer to the module's built-in help.

Application Programming Interface

As an introduction to the Data URI API provided by the module, a couple of simple code examples are presented in this section. The API is implemented by the DataUriCreator class that has static methods to detect, validate, encode and decode Data URIs.

Encoding

To create a Data URI for some data, provide the MIME type of the data, as well as the data itself (specified as a string of bytes). For example, to create a Data URI for regular text, such as "Hello World", the following code can be used:

<?php
  $data_uri = DataUriCreator::encode(
    "Hello World", "text/plain;charset=utf-8");
?>

When encoding text, it is generally a good idea to specify the character encoding of the data explicitly as part of the media type, as shown above. This is due to the fact that the Data URI specification defines US-ASCII as the default encoding for plain text, while Drupal uses UTF-8 encoding for text.

To create a Data URI for data stored in a file, specify the name of the file to be encoded, as shown below:

<?php
  $data_uri = DataUriCreator::encodeFile("image.png");
?>

Although the MIME type of the file's content can be specified explicitly through an optional second parameter, the method generally does a good job of figuring out the type automatically.

Decoding

To extract the data content from a Data URI, use code similar to the following:

<?php
  $data_uri = "data:;charset=utf-8;base64,SGVsbG8gV29ybGQ=";
  $data_content = DataUriCreator::decode($data_uri);
?>

An optional second argument can be used to specify an output variable that will contain the MIME type of the data when the function returns. For example, to obtain both the data content and its MIME type, use code such as:

<?php
  $data_uri = "data:application/octet-stream,%2A";
  $mime_type = NULL;
  $data_content = DataUriCreator::decode($data_uri, $mime_type);
?>

Further reading

For additional documentation on the API, refer to the detailed comments found in the DataUriCreator class (see the data_uri_creator_class.inc file), which include information about optional parameters, output parameters, return values, additional methods and more.

Related modules

Several modules work with Data URIs within a limited context specifically tailored to their unique needs, but they do so in isolation. These modules do not provide a complete and general mechanism to handle Data URI coding. Ideally, the various modules that work with Data URIs would all make use of a common API that performs encoding and decoding of Data URIs, which is functionality that the Data URI Creator module aims for.

Other modules that make use of Data URIs include the following.

• CSS Embedded Images (css_emimage 7.x-1.3) "is only concerned with images referenced in CSS", apparently by automatic preprocessing of CSS only "when Drupal's CSS optimization feature is enabled". Encoding is done internally and formatted specifically for embedding within CSS (base64-encoding only).
• Storage API (storage_api 7.x-1.5) is a much larger module that appears to have preliminary internal support for Data URIs in the context of managed files (its main focus).
• Sasson (7.x-2.10) is a tool-kit for theming. It is quite a large module (or rather, a base theme) that includes an encoding mechanism involving Data URIs to support "inline data", which seems to be related to CSS (see SassExtentionsCompassFunctionsInlineData).
• The imagetobase64calc (7.x-1.x-dev) module provides a similar user-interface tool, although rather rudimentary (a development release without support). Only base64-encoding is implemented, done so internally and for common image-types only.
• Image Base64 Formatter (image_base64 7.x-1.0-beta1) implements a formatter for image fields, which inlines an encoded version of images (base64-encoding only).
• Development on Data URI Sprites Generator (data_uri_sprites, obsolete) stopped in favor of using the CSS Embedded Images module. The module used Data URIs in the context of aggregated CSS files but it is no longer available.
• Faster Images (fasterimages 7.x-1.x) "is a work-in-progress, a proof-of-concept for an idea. [...] It is not ready for production websites." The module also encodes Data URIs internally and with one encoding strategy only.
• CSS Sprite Generator (sprites 5.x-1.x-dev) is an old Drupal 5 development-only module that seems to be abandoned. Although the module does not support Data URI schemes, it could have benefitted from a common Data URI API.

To summarize, other modules focus mainly on images, generally only implement the encoding of Data URIs and furthermore only a subset thereof. Implementations are usually specifically customized and internal to these modules.

The Data URI Creator module includes a public and lightweight API that fully supports encoding and decoding of Data URIs in general, along with a user interface that can be used to manually create such Data URIs. Module developers are encouraged to use the Data URI Creator module as a common API when Data URI support is needed.