UmyaSpreadsheet.Hyperlink (umya_spreadsheet_ex v0.7.0)

View Source

Functions for managing hyperlinks in Excel spreadsheets.

This module provides a comprehensive API for working with hyperlinks in Excel cells, including support for:

  • Web URLs (http/https)
  • File paths (local files)
  • Internal worksheet references
  • Email addresses (mailto links)
  • Custom tooltip text
  • Complete hyperlink lifecycle management (add, get, update, remove)

Examples

# Add a web URL hyperlink
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_hyperlink(
  spreadsheet,
  "Sheet1",
  "A1",
  "https://example.com",
  "Visit Example.com"
)

# Add an internal worksheet reference
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_hyperlink(
  spreadsheet,
  "Sheet1",
  "B1",
  "Sheet2!A1",
  "Go to Sheet2",
  true
)

# Get hyperlink information
{:ok, hyperlink_info} = UmyaSpreadsheet.Hyperlink.get_hyperlink(spreadsheet, "Sheet1", "A1")

# Check if cell has hyperlink
true = UmyaSpreadsheet.Hyperlink.has_hyperlink?(spreadsheet, "Sheet1", "A1")

# Get all hyperlinks in worksheet
{:ok, hyperlinks} = UmyaSpreadsheet.Hyperlink.get_all_hyperlinks(spreadsheet, "Sheet1")

# Update existing hyperlink
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.update_hyperlink(
  spreadsheet,
  "Sheet1",
  "A1",
  "https://newexample.com",
  "Updated tooltip"
)

# Remove hyperlink
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.remove_hyperlink(spreadsheet, "Sheet1", "A1")

Summary

Functions

Bulk adds multiple hyperlinks to a worksheet.

Counts the number of hyperlinks in a worksheet.

Gets all hyperlinks from a worksheet.

Gets hyperlink information from a cell.

Checks if a specific cell has a hyperlink.

Checks if a worksheet contains any hyperlinks.

Removes all hyperlinks from a worksheet.

Types

Functions

add_bulk_hyperlinks(spreadsheet, sheet_name, hyperlinks)

@spec add_bulk_hyperlinks(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  [
    {String.t(), String.t()}
    | {String.t(), String.t(), String.t() | nil}
    | {String.t(), String.t(), String.t() | nil, boolean()}
    | hyperlink_info()
  ]
) :: :ok | {:error, atom()}

Bulk adds multiple hyperlinks to a worksheet.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet
  • hyperlinks: List of hyperlink specifications as tuples or maps

Each hyperlink can be specified as:

  • {cell_address, url} - Basic hyperlink without tooltip
  • {cell_address, url, tooltip} - Hyperlink with tooltip
  • {cell_address, url, tooltip, is_internal} - Full specification
  • %{cell: cell_address, url: url, tooltip: tooltip, is_internal: is_internal} - Map format

Returns

  • {:ok, spreadsheet} on success
  • {:error, reason} on failure

Examples

hyperlinks = [
  {"A1", "https://example.com", "Website"},
  {"B1", "mailto:test@example.com", "Email"},
  {"C1", "Sheet2!A1", "Internal link", true}
]

{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_bulk_hyperlinks(
  spreadsheet,
  "Sheet1",
  hyperlinks
)

add_hyperlink(spreadsheet, sheet_name, cell_address, url, tooltip \\ nil, is_internal \\ false)

@spec add_hyperlink(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t() | nil,
  boolean()
) :: :ok | {:error, atom()}

Adds a hyperlink to a cell.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")
  • url: The hyperlink URL or reference
  • tooltip: Optional tooltip text (default: nil)
  • is_internal: Whether this is an internal worksheet reference (default: false)

Returns

  • {:ok, spreadsheet} on success
  • {:error, reason} on failure

Examples

# Web URL
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_hyperlink(
  spreadsheet,
  "Sheet1",
  "A1",
  "https://example.com",
  "Visit our website"
)

# Email link
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_hyperlink(
  spreadsheet,
  "Sheet1",
  "B1",
  "mailto:contact@example.com",
  "Send email"
)

# File path
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_hyperlink(
  spreadsheet,
  "Sheet1",
  "C1",
  "file:///path/to/document.pdf",
  "Open document"
)

# Internal reference
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.add_hyperlink(
  spreadsheet,
  "Sheet1",
  "D1",
  "Sheet2!A1",
  "Go to Sheet2",
  true
)

count_hyperlinks(spreadsheet, sheet_name)

@spec count_hyperlinks(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  {:ok, non_neg_integer()} | {:error, atom()}

Counts the number of hyperlinks in a worksheet.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet

Returns

  • {:ok, count} where count is the number of hyperlinks
  • {:error, reason} on failure

Examples

{:ok, 5} = UmyaSpreadsheet.Hyperlink.count_hyperlinks(spreadsheet, "Sheet1")

get_all_hyperlinks(spreadsheet, sheet_name)

@spec get_all_hyperlinks(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  {:ok, [hyperlink_info()]} | {:error, atom()}

Gets all hyperlinks from a worksheet.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet

Returns

  • {:ok, hyperlinks} where hyperlinks is a list of hyperlink_info maps
  • {:error, reason} on failure

Examples

{:ok, hyperlinks} = UmyaSpreadsheet.Hyperlink.get_all_hyperlinks(spreadsheet, "Sheet1")
# Returns: [
#   %{url: "https://example.com", tooltip: "Website", is_internal: false, cell: "A1"},
#   %{url: "Sheet2!A1", tooltip: "Internal link", is_internal: true, cell: "B1"}
# ]

get_hyperlink(spreadsheet, sheet_name, cell_address)

@spec get_hyperlink(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, hyperlink_info()} | {:error, atom()}

Gets hyperlink information from a cell.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • {:ok, hyperlink_info} if hyperlink exists
  • {:error, :not_found} if no hyperlink exists
  • {:error, reason} on other failures

Examples

{:ok, info} = UmyaSpreadsheet.Hyperlink.get_hyperlink(spreadsheet, "Sheet1", "A1")
# Returns: %{url: "https://example.com", tooltip: "Visit our website", is_internal: false, cell: "A1"}

has_hyperlink?(spreadsheet, sheet_name, cell_address)

@spec has_hyperlink?(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, boolean()} | {:error, atom()}

Checks if a specific cell has a hyperlink.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • true if the cell has a hyperlink
  • false if the cell doesn't have a hyperlink
  • {:error, reason} on failure

Examples

true = UmyaSpreadsheet.Hyperlink.has_hyperlink?(spreadsheet, "Sheet1", "A1")
false = UmyaSpreadsheet.Hyperlink.has_hyperlink?(spreadsheet, "Sheet1", "B1")

has_hyperlinks?(spreadsheet, sheet_name)

@spec has_hyperlinks?(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  {:ok, boolean()} | {:error, atom()}

Checks if a worksheet contains any hyperlinks.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet

Returns

  • true if the worksheet has any hyperlinks
  • false if the worksheet has no hyperlinks
  • {:error, reason} on failure

Examples

true = UmyaSpreadsheet.Hyperlink.has_hyperlinks?(spreadsheet, "Sheet1")
false = UmyaSpreadsheet.Hyperlink.has_hyperlinks?(spreadsheet, "EmptySheet")

remove_all_hyperlinks(spreadsheet, sheet_name)

@spec remove_all_hyperlinks(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  :ok | {:error, atom()}

Removes all hyperlinks from a worksheet.

Cell values and formatting are preserved, only hyperlinks are removed.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet

Returns

  • {:ok, spreadsheet} on success
  • {:error, reason} on failure

Examples

{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.remove_all_hyperlinks(spreadsheet, "Sheet1")

remove_hyperlink(spreadsheet, sheet_name, cell_address)

@spec remove_hyperlink(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  :ok | {:error, atom()}

Removes a hyperlink from a cell.

The cell value and formatting are preserved, only the hyperlink is removed.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • {:ok, spreadsheet} on success
  • {:error, reason} on failure

Examples

{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.remove_hyperlink(spreadsheet, "Sheet1", "A1")

update_hyperlink(spreadsheet, sheet_name, cell_address, url, tooltip \\ nil, is_internal \\ false)

@spec update_hyperlink(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t() | nil,
  boolean()
) :: :ok | {:error, atom()}

Updates an existing hyperlink in a cell.

If no hyperlink exists in the cell, this function will add a new one.

Parameters

  • spreadsheet: The spreadsheet reference
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")
  • url: The new hyperlink URL or reference
  • tooltip: Optional new tooltip text (default: nil)
  • is_internal: Whether this is an internal worksheet reference (default: false)

Returns

  • {:ok, spreadsheet} on success
  • {:error, reason} on failure

Examples

{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.update_hyperlink(
  spreadsheet,
  "Sheet1",
  "A1",
  "https://newexample.com",
  "Updated website link"
)