Mob.Share (mob v0.9.32)

Copy Markdown View Source

System share sheet. Opens the OS share dialog with text or a local file. Fire-and-forget — text/2 and file/3 always return the socket unchanged.

Usage

def handle_event("share", _params, socket) do
  {:noreply, Mob.Share.text(socket, "Check out Mob: https://github.com/genericjam/mob")}
end

def handle_info({:tap, :export}, socket) do
  path = Path.join(Mob.Storage.dir(:cache), "exports/report.pdf")
  {:noreply, Mob.Share.file(socket, path, title: "Quarterly Report")}
end

def handle_info({:mob_share, :error, reason}, socket) do
  {:noreply, Mob.Alert.toast(socket, "Share failed: #{reason}")}
end

Message contract

file/3 delivers setup failures asynchronously (or immediately from Elixir when the file is missing) to the calling process (self()) as {:mob_share, :error, reason} where reason is one of:

  • :not_found — the path does not exist, is a directory, or is unreadable
  • :no_activity — no foreground activity (Android) or active window scene presenter (iOS)
  • :no_app — no target app can handle the share intent (Android)
  • :failed — FileProvider URI or native share setup threw an error
  • :unsupported — the Android host MobBridge predates shareFile

Success, completion, and user cancellation of the share sheet are never reported.

Platform notes

  • Android shares via Intent.ACTION_SEND wrapped in Intent.createChooser, backed by androidx.core.content.FileProvider. The file MUST live under a root declared in the host's res/xml/file_provider_paths.xml. Generated mob_new apps cover the whole app cache directory (Mob.Storage.dir(:cache)), so write shared exports under the cache directory; sharing a path outside any configured root delivers {:mob_share, :error, :failed}. Older mob_new hosts without MobBridge.shareFile deliver {:mob_share, :error, :unsupported}.
  • iOS shares a file:// NSURL through UIActivityViewController (with a UIActivityItemSource item supplying the file URL, subject title, and UTI type identifier derived from :mime), presented with a centered popover anchor on iPad.

Summary

Functions

Open the share sheet with a local file. Always returns the socket unchanged.

Open the share sheet with plain text. Returns the socket unchanged.

Types

error_reason()

@type error_reason() :: :not_found | :no_activity | :no_app | :failed | :unsupported

Functions

file(socket, path, opts \\ [])

@spec file(Mob.Socket.t(), Path.t(), keyword()) :: Mob.Socket.t()

Open the share sheet with a local file. Always returns the socket unchanged.

path may be a binary or chardata and is resolved with Path.absname/1. Setup errors are sent to self() as {:mob_share, :error, reason}.

Options

  • :mime — non-empty MIME type string containing "/". Defaults to a type derived case-insensitively from the file extension, falling back to "application/octet-stream".
  • :title — non-empty share title string. Defaults to Path.basename(path). It titles the Android chooser and becomes the subject where the target has one (Mail, Gmail). It does not rename the file: what the recipient sees, and what the iOS share sheet shows, is the file's own name, so name the file for the reader before sharing it.

text(socket, content)

@spec text(Mob.Socket.t(), binary()) :: Mob.Socket.t()

Open the share sheet with plain text. Returns the socket unchanged.