Common ADF Widgets

ADF TextArea Widget - Handles Atlassian Document Format conversion and rendering.

ADFMarkdownTextAreaWidget

class ADFMarkdownTextAreaWidget(mode: jiratui.widgets.commons.FieldMode, jira_field_key: str, field_id: str, title: str | None = None, required: bool = False, original_value: dict | None = None, field_supports_update: bool = True)

Bases: textual.widgets.TextArea, jiratui.widgets.commons.BaseFieldWidget, jiratui.widgets.commons.BaseUpdateFieldWidget

Unified Markdown-based textarea widget for fields that support ADF and that supports CREATE and UPDATE modes.

Features:

  • Multi-line text input for fields with textarea custom type.

  • ADF-to-Markdown and Markdown-toADF conversion.

  • Mode-aware behavior (CREATE vs UPDATE)

  • Change tracking for UPDATE mode

  • Required field support

Usage in CREATE mode:

1widget = ADFMarkdownTextAreaWidget(
2    mode=FieldMode.CREATE,
3    jira_field_key='customfield_12345',
4    field_id='customfield_12345',
5    title='Description',
6    required=False,
7)
8# Get value:
9widget.text

Usage in UPDATE mode:

 1widget = ADFMarkdownTextAreaWidget(
 2    mode=FieldMode.UPDATE,
 3    jira_field_key='customfield_12345',
 4    field_id='customfield_12345',
 5    title='Custom Field A',
 6    original_value='Original text',
 7    field_supports_update=True,
 8)
 9# Check changes:
10widget.value_has_changed
11# Get value for API updates:
12widget.get_value_for_update()
13# Get value for API creation operations:
14widget.get_value_for_create()

Initialization

Initializes a ADFMarkdownTextAreaWidget.

Parameters:

  • mode – the field mode (CREATE or UPDATE)

  • jira_field_key – the key of the field that it is used for updating the field value in the API.

  • field_id – field identifier.

  • title – display title.

  • required – whether the field is required (mainly for CREATE mode)

  • original_value – original ADF value from Jira (UPDATE mode only)

  • field_supports_update – whether field can be updated (UPDATE mode only)

class EditContent

Bases: textual.message.Message

A message sent when the content of the field is edited.

Initialization

get_value_for_update() → dict | None

Returns the value formatted for Jira API updates (UPDATE mode).

Returns:

An ADF dict or None if the MD-to-ADF conversion fails.

get_value_for_create() → dict | None

Returns the value formatted for Jira API creation (CREATE mode).

Returns:

An ADF dict or None if the MD-to-ADF conversion fails.

property original_value: dict

Get the original description from Jira.

property value_has_changed: bool

Determines if the current value differs from the original value (UPDATE mode).

The current value is a Markdown text but the original value is an ADF dict. We need to convert the ADF to Markdown and compare the strings.

Returns:

True if value has changed, False otherwise.

set_original_value(value: dict) → None

Sets the original value for change tracking (UPDATE mode).

Parameters:

value – The original description text from Jira

ReadOnlyADFMarkdownTextAreaWidget

class ReadOnlyADFMarkdownTextAreaWidget(field_id: str, jira_field_key: str, title: str | None = None, required: bool = False, original_value: dict | None = None)

Bases: textual.widgets.Markdown

Read-only Markdown widget that handles Atlassian Document Format (ADF) conversion.

This widget automatically converts ADF JSON to Markdown and renders it with formatting. It is read-only and displays rich text content with proper rendering (bold, italics, links, etc.).

The widget can be used when we want to display fields that support ADF. Jira Cloud Platform API v3 uses such fields.

Use it in the Info tab or to display comment’s content or to display fields in the read-only work item details screen.

Features:

  • Automatic ADF to Markdown conversion on initialization

  • Rich text rendering (not editable Markdown)

  • Read-only display

Usage:

1widget = ReadOnlyADFTextAreaWidget(
2    field_id='customfield_10745',
3    jira_field_key='customfield_10745',
4    title='HL Solution',
5    required=True,
6    original_value={'type': 'doc', 'content': [...]},  # ADF dict
7)

Initialization

Initializes a ReadOnlyADFMarkdownTextAreaWidget.

Parameters:

  • field_id – field identifier, e.g., ‘customfield_10745’.

  • jira_field_key – the key of the field that it is used for updating the field value in the API; e.g., ‘customfield_10745’.

  • title – display title for the field.

  • required – whether the field is required.

  • original_value – the original value from Jira. It expects an ADF dict.

property required: bool

Checks if this field is required.

mark_required() → None

Marks this field as required by adding subtitle and CSS class.

property text_content: str

Retrieves the Markdown representation of this ADF value being displayed in this widget.