UmyaSpreadsheet.Hyperlink (umya_spreadsheet_ex v0.7.0)
View SourceFunctions 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.
Adds a hyperlink to a cell.
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.
Removes a hyperlink from a cell.
Updates an existing hyperlink in a cell.
Types
Functions
@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 referencesheet_name
: Name of the worksheethyperlinks
: List of hyperlink specifications as tuples or maps
Hyperlink specifications
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
)
@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 referencesheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")url
: The hyperlink URL or referencetooltip
: 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
)
@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 referencesheet_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")
@spec get_all_hyperlinks(UmyaSpreadsheet.Spreadsheet.t(), String.t()) :: {:ok, [hyperlink_info()]} | {:error, atom()}
Gets all hyperlinks from a worksheet.
Parameters
spreadsheet
: The spreadsheet referencesheet_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"}
# ]
@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 referencesheet_name
: Name of the worksheetcell_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"}
@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 referencesheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if the cell has a hyperlinkfalse
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")
@spec has_hyperlinks?(UmyaSpreadsheet.Spreadsheet.t(), String.t()) :: {:ok, boolean()} | {:error, atom()}
Checks if a worksheet contains any hyperlinks.
Parameters
spreadsheet
: The spreadsheet referencesheet_name
: Name of the worksheet
Returns
true
if the worksheet has any hyperlinksfalse
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")
@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 referencesheet_name
: Name of the worksheet
Returns
{:ok, spreadsheet}
on success{:error, reason}
on failure
Examples
{:ok, spreadsheet} = UmyaSpreadsheet.Hyperlink.remove_all_hyperlinks(spreadsheet, "Sheet1")
@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 referencesheet_name
: Name of the worksheetcell_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")
@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 referencesheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")url
: The new hyperlink URL or referencetooltip
: 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"
)