images.md

Embedding Images

Note that Image API is considered experimental and is likely to be changed in backward incompatible ways. If this happens all changes will be described in detail in the changelog to simplify upgrading.

Zefyr supports embedding images. In order to handle images in your application you need to implement ZefyrImageDelegate interface which looks like this:

abstract class ZefyrImageDelegate<S> {
  /// Unique key to identify camera source.
  S get cameraSource;

  /// Unique key to identify gallery source.
  S get gallerySource;

  /// Builds image widget for specified image [key].
  ///
  /// The [key] argument contains value which was previously returned from
  /// [pickImage].
  Widget buildImage(BuildContext context, String key);

  /// Picks an image from specified [source].
  ///
  /// Returns unique string key for the selected image. Returned key is stored
  /// in the document.
  ///
  /// Depending on your application returned key may represent a path to
  /// an image file on user's device, an HTTP link, or an identifier generated
  /// by a file hosting service like AWS S3 or Google Drive.
  Future<String> pickImage(S source);
}

There is no default implementation of this interface since resolving image sources is always application-specific.

Note that prior to 0.7.0 Zefyr did provide simple default implementation of ZefyrImageDelegate however it was removed as it introduced unnecessary dependency on image_picker plugin.

Implementing ZefyrImageDelegate

For this example we will use image_picker plugin which allows us to select images from device's camera or photo gallery.

Let's start from the pickImage method:

import 'package:image_picker/image_picker.dart';

class MyAppZefyrImageDelegate implements ZefyrImageDelegate<ImageSource> {
  @override
  Future<String> pickImage(ImageSource source) async {
    final file = await ImagePicker.pickImage(source: source);
    if (file == null) return null;
    // We simply return the absolute path to selected file.
    return file.uri.toString();
  }
}

This method is responsible for initiating image selection flow (either using camera or gallery), handling result of selection and returning a string value which essentially serves as an identifier for the image.

Returned value is stored in the document Delta and later on used to build the appropriate image widget.

It is up to the developer to define what this value represents.

In the above example we simply return a full path to the file on user's device, e.g. file:///Users/something/something/image.jpg. Some other examples may include a web link, https://myapp.com/images/some.jpg or an arbitrary string like an identifier of an image in a cloud storage like AWS S3.

For instance, if you upload files to your server you can initiate this task in pickImage as follows:

class MyAppZefyrImageDelegate implements ZefyrImageDelegate<ImageSource> {
  final MyFileStorage storage;
  MyAppZefyrImageDelegate(this.storage);

  @override
  Future<String> pickImage(ImageSource source) async {
    final file = await ImagePicker.pickImage(source: source);
    if (file == null) return null;
    // Use my storage service to upload selected file. The uploadImage method
    // returns unique ID of newly uploaded image on my server.
    final String imageId = await storage.uploadImage(file);
    return imageId;
  }
}

Next we need to implement buildImage. This method takes imageSource argument which contains that same string you returned from pickImage. Here you can use this value to create a Flutter widget which renders the image. Normally you would return the standard Image widget from this method, but it is not a requirement. You are free to create a custom widget which, for instance, shows progress of upload operation that you initiated in the pickImage call.

Assuming our first example where we returned full path to the image file on user's device, our buildImage method can be as simple as following:

class MyAppZefyrImageDelegate implements ZefyrImageDelegate<ImageSource> {
  // ...

  @override
  Widget buildImage(BuildContext context, String key) {
    final file = File.fromUri(Uri.parse(key));
    /// Create standard [FileImage] provider. If [key] was an HTTP link
    /// we could use [NetworkImage] instead.
    final image = FileImage(file);
    return Image(image: image);
  }
}

There is two more overrides we need to implement which configure source types used by Zefyr toolbar:

class MyAppZefyrImageDelegate implements ZefyrImageDelegate<ImageSource> {
  // ...
  @override
  ImageSource get cameraSource => ImageSource.camera;

  @override
  ImageSource get gallerySource => ImageSource.gallery;
}

Now our image delegate is ready to be used by Zefyr so the last step is to pass it to Zefyr editor:

import 'package:zefyr/zefyr.dart'

class MyAppPageState extends State<MyAppPage> {
  FocueNode _focusNode = FocusNode();
  ZefyrController _controller;

  // ...

  @override
  Widget build(BuildContext context) {
    final editor = new ZefyrEditor(
      focusNode: _focusNode,
      controller: _controller,
      imageDelegate: MyAppZefyrImageDelegate(),
    );

    // ... do more with this page's layout

    return ZefyrScaffold(
      child: Container(
        // ... customize
        child: editor,
      )
    );
  }
}

When imageDelegate field is set to non-null value it automatically enables image selection button in Zefyr's style toolbar.