DEVELOPER GUIDE · JUPYTEREXCEL 0.1.0

ribbon_function

Build notebook actions with inputs, previews, and explicit worksheet writes.

Before you begin

Install JupyterExcel in your Jupyter server and Python kernel environments, configure the asset directory and URLs, and load the generated manifest in Excel. Follow the setup guide.
Put the examples in a notebook visible to the Jupyter server and save it to regenerate the add-in metadata.
If the managed JupyterExcel kernel is already running, restart it to load saved code changes, or use the JupyterExcel save-and-reload toolbar command. Saving alone updates metadata, not the running definitions.
Reload the add-in to pick up new functions or actions and enter your access token through the Token command.

The managed kernel executes code cells in discovered export notebooks when it initializes. Use trusted notebooks and avoid unintended top-level side effects.

Your first action

@ribbon_function defines an action available through the Excel ribbon’s Actions command. Each action appears in the task pane’s dropdown; it does not create its own ribbon button or worksheet formula.

from jupyterexcel import ribbon_function

@ribbon_function(
    name="Multiply",
    label="Multiply two numbers",
    description="Multiply the entered numbers and preview the result.",
    button_text="Calculate",
    inputs={
        "a": {"source": "value", "type": "number", "label": "First number"},
        "b": {"source": "value", "type": "number", "default": 2},
    },
    output={"type": "number", "destinations": ["taskpane", "range"]},
)
def multiply(a, b):
    return {"result": a * b}

Open Actions in Excel and select Multiply two numbers.
Enter 5 for the first number and leave the second number at 2.
Click Calculate. The preview shows 10.
Click Starting Cell, select one output cell, and click Write to cells. Confirm replacement if the destination is occupied.

Decorator options

Option	Usage
`name`	Required action ID. Currently accepts ASCII letters, numbers, and periods and is normalized to uppercase. It must not conflict with a worksheet function or another action. Use `label` for display text.
`label / description`	The dropdown label and explanatory text. The label defaults to the action name.
`button_text`	Text on the run button. Default: `Run`.
`inputs`	A literal dictionary whose keys match the Python positional parameters in the same order. Use `{}` for an action with no arguments.
`output`	Declares `type`, allowed `destinations`, and an optional `default` destination. Destinations are `taskpane`, `range`, and `popup`.

Input sources are value, cell, or range. Value input types are number, string/text, boolean, choice, and matrix. A choice field also needs a choices list. Range inputs require type: "matrix".

All inputs are required. Use a field’s default to prefill its control; Python parameter defaults do not prefill controls. For multiple entries, set repeatable: True: the action receives a list as one argument, not Python *args. Each repeatable field supports 1–50 entries.

Read a selected range

from jupyterexcel import ribbon_function

@ribbon_function(
    name="SumRange",
    label="Sum selected numbers",
    inputs={
        "data": {"source": "range", "type": "matrix",
                 "label": "Data range", "read": ["values"], "max_cells": 5000},
    },
    output={"type": "number", "destinations": ["taskpane", "range", "popup"]},
)
def sum_range(data):
    total = sum(value for row in data["values"] for value in row
                if type(value) in (int, float))
    return {"result": total}

Click Data range and select a contiguous range in Excel, then click Run. For cells containing 2, 3, and text, the result is 5; this example ignores text, blanks, and booleans.

Cell and range inputs arrive as blocks, for example {"values": [[2, 3]]}. Even a single cell uses a two-dimensional list. Selections are limited to 5,000 cells, or a lower max_cells value.

Read colors and return formatted cells

from jupyterexcel import ribbon_function

@ribbon_function(
    name="CopyWithColors",
    label="Preview values and colors",
    inputs={
        "data": {"source": "range", "type": "matrix",
                 "read": ["values", "format.fillColors"]},
    },
    output={"type": "matrix", "destinations": ["taskpane", "range"]},
)
def copy_with_colors(data):
    return {"result": {
        "values": data["values"],
        "format": {"fillColors": data["format"]["fillColors"]},
    }}

Select a small range with manual solid fills. Run the action to preview its values and colors, then choose an output cell outside the input range and write the result.

Reading fills requires ExcelApi 1.9. Conditional formatting, patterned fills, and Excel error cells are rejected.
On output, "#FFFF00" applies yellow, "" clears the fill, and Python None preserves the destination fill. Omit format to write only values.
The color matrix must match the dimensions of values. Returned tables must be rectangular and contain at most 5,000 scalar cells.

Results, writes, and updates

Return a dictionary containing result, not a bare value. The result can be a scalar, a rectangular list of rows, or a values/format block as shown above. Include column headings as the first row when needed.

A range default requests a write after calculation when a Starting Cell is selected; occupied destinations require confirmation. A popup default opens a preview dialog inside the pane. Cancelling a write keeps the result available. Relevant input changes make it stale; run again before writing.

Advanced actions can return an updates dictionary alongside result, keyed by a non-repeating cell/range input name. Each update must match that input’s selected dimensions and requires confirmation before applying. Ordinary result output must be outside the input ranges.

Use synchronous functions and JSON-compatible values. Writes are not atomic and are not automatically retried; a failure can leave a partial write. The legacy ribbon_function(name, return_value, **mappings) form is for older clients and is not executable in the current Actions pane.

Explore the other interface

Read the jupyter_function guide →

Client setup · Source and server setup