Card Creation

This script interacts with the Miro API to retrieve and create items on a Miro board.

It includes functionality to: - Load environment variables for API access. - Retrieve items from a Miro board using cursor pagination and store them in a pandas DataFrame. - Create various elements (cards, sticky notes, shapes) on the Miro board with specified attributes. - Find an appropriate position for new elements on the board, avoiding collisions with existing items. - Validate color formats and send API requests to create elements.

Dependencies: - dotenv - pandas - requests - numpy - re

card_creation.adjust_card_height(title, height)

Adjusts the card height based on the title length and line breaks.

Parameters:

  • title (str) – The title of the card.

  • height (int) – The initial height of the card.

Returns:

The adjusted height of the card.

Return type:

int

card_creation.build_payload(element_type, board_id, title, description, fillColor, shape, width, height, x, y)

Builds the URL and payload based on the element type.

Parameters:

  • element_type (str) – The type of element to create (card, sticky_note, or shape).

  • board_id (str) – The ID of the board where the element will be created.

  • title (str) – The title of the element.

  • description (str) – The description of the element (only applicable for cards).

  • fillColor (str) – The fill color of the element.

  • shape (str) – The shape of the element (only applicable for shapes).

  • width (int) – The width of the element.

  • height (int) – The height of the element.

  • x (int) – The x-coordinate of the element’s position.

  • y (int) – The y-coordinate of the element’s position.

Returns:

A tuple containing the URL and payload for the API request.

Return type:

tuple

card_creation.create_miro_element(element_type='card', board_id=None, title='Titel', description=None, fillColor='red', shape='rectangle', width=300, height=300, x=0, y=0)

Creates a new Miro element (card, sticky note, or shape) at a specified position on a board.

Parameters:

  • element_type (str) – The type of element to create (card, sticky_note, or shape).

  • board_id (str) – The ID of the board where the element will be created.

  • title (str) – The title of the element.

  • description (str) – The description of the element (only applicable for cards).

  • fillColor (str) – The fill color of the element.

  • shape (str) – The shape of the element (only applicable for shapes).

  • width (int) – The width of the element.

  • height (int) – The height of the element.

  • x (int) – The x-coordinate of the element’s position.

  • y (int) – The y-coordinate of the element’s position.

Returns:

The JSON response from the API if the request was successful, None otherwise.

Return type:

Optional[Dict[str, object]]

card_creation.find_free_position(x, y, width, height, existing_items, initial_step=50, max_attempts=10000, increase_step_interval=100)

Finds a free position for an element on a board using a spiral search algorithm.

Parameters:

  • x (int) – The initial x-coordinate of the element.

  • y (int) – The initial y-coordinate of the element.

  • width (int) – The width of the element.

  • height (int) – The height of the element.

  • existing_items (list) – A list of existing items on the board.

  • initial_step (int, optional) – The initial step size for the spiral search. Defaults to 50.

  • max_attempts (int, optional) – The maximum number of attempts to find a free position. Defaults to 10000.

  • increase_step_interval (int, optional) – The interval at which to increase the step size. Defaults to 100.

Returns:

A tuple containing the x and y coordinates of the free position.

Return type:

tuple

card_creation.get_items(board_id, limit=50)

Retrieves items from a Miro board using cursor pagination and saves them into a pandas DataFrame.

Parameters:

  • board_id (str) – The ID of the Miro board to retrieve items from.

  • limit (int, optional) – The maximum number of results per request. Defaults to 50.

Returns:

A DataFrame containing the retrieved items. Each row represents an item and the columns are: ‘id’, ‘type’, ‘content’, ‘shape’, ‘fillColor’, ‘width’, ‘height’, ‘x’, ‘y’, ‘createdAt’, ‘modifiedAt’, ‘createdBy’, ‘modifiedBy’.

Return type:

pandas.DataFrame

card_creation.is_collision(new_x, new_y, new_width, new_height, existing_items)

Checks if a new item will collide with existing items, considering a 10% clear area around the new item.

Parameters:

  • new_x (float) – The x-coordinate of the new item’s center.

  • new_y (float) – The y-coordinate of the new item’s center.

  • new_width (float) – The width of the new item.

  • new_height (float) – The height of the new item.

  • existing_items (dict) – A dictionary containing the existing items’ coordinates and dimensions.

Returns:

True if a collision is detected, False otherwise.

Return type:

bool

card_creation.send_request(url, payload, element_type, x, y)

Sends the API request to create the Miro element.

Parameters:

  • url (str) – The API endpoint URL.

  • payload (Dict[str, object]) – The JSON payload for the request.

  • element_type (str) – The type of the element being created (e.g. “card”, “sticky_note”, “shape”).

  • x (float) – The x-coordinate of the element’s center.

  • y (float) – The y-coordinate of the element’s center.

Returns:

The JSON response from the API if the request was successful, None otherwise.

Return type:

Optional[Dict[str, object]]

card_creation.validate_hex_color(color: str) → str

Validates a given color string as a hexadecimal color code.

Parameters:

color (str) – The color string to be validated.

Returns:

The validated hexadecimal color code. If the input color is invalid, returns “#00C1D4” as default.

Return type:

str

card_creation.validate_sticky_note_color(fillColor)

Validates the color for sticky notes.

Parameters:

fillColor (str) – The color to be validated.

Returns:

The validated color. If the input color is not in the allowed colors list, it defaults to ‘yellow’.

Return type:

str