focalboard/docs/work-with-cards.md

# Work with cards

## What's a card?

Cards are used on a board to track individual work items. Cards are customizable and can have a number of properties added to them, which are then used as a way to tag, sort, and filter the cards.

A card consists of:

- **A set of properties**: Properties are common to all cards in a board. Board views can group cards by “Select” type properties into different columns.
- **A list of comments**: Comments are useful for noting important changes or milestones.
- **A set of content**: The content of a card can consist of Markdown text, checkboxes, and images. Use this to record detailed specs or design decisions for an item for example.

When working with cards, you can manage properties, add descriptions, attach images, assign them to team members, mention team members, add comments, and so on.

Standard board templates provide some default card properties that can be customized or removed. In the Roadmap template, there's a **Type** property, whereas in the Project Tasks template, there's an **Estimated Hours** property. These properties are not exclusive to any template and can be easily re-created in any of the templates provided.

## Add card descriptions

Card descriptions can include text with Markdown formatting, checkboxes, and visual elements such as images or GIFs, and can be separated into blocks of content. To add a description, open a card, select **Add a description** below the **Comments** section, and start typing in your content.

To add a new content block in the description section, hover over the section and select **Add content**. Then choose from any of the following options:

- **Text**: Adds a new text block that can be formatted with Markdown.
- **Image**: Select and embed an image file into the content block. The following image formats are currently supported: GIF, JPEG, and PNG.
- **Divider**: Adds a divider content block below the previous block.
- **Checkbox**: Adds a checkbox content block. Press Enter/Return after typing in content for your checkbox to add another checkbox within the same block. Please note, Markdown formatting isn't supported within the **Checkbox** content block.

To manage the description content blocks on a card, hover over any existing block and select the options menu |options-icon| to move the block up or down, insert a new block above, or delete the current block. Alternatively, you can hover over any existing block, then select and hold the grid button to drag and drop it to a new position within the description section.

## Attach files to cards

From Focalboard plugin version v7.7, you can attach files to your cards, which other board members can download. There are no limitations to the file types that you can upload.

To upload a file to a card, select **Attach** in the top-right corner of the card. Then select the file you'd like to upload. When your file has been uploaded, you can find it in the **Attachments** section of the card. Select the **+** sign to add additional files to your card.

To delete a file attachment, hover over it and select the 3-dot menu, then select **Delete**. To download the file, select the download icon.

## Add card badges

Card badges are a quick way to view card details without opening up a card. To add them, select **Properties > Comments and Description**. Icons related to the card description, comments, and checkboxes will be displayed on cards with the respective content. Open the card to view the details.

- The description icon indicates that a card has a text description.
- The comment icon displays a number indicating how many comments have been added to a card. When a new comment is added, that number is updated.
- The checkbox icon displays the number of items checked off relative to the total number of checkboxes within the card. When an item is checked off, the icon is automatically updated.

## Comment on a card

Comments allow you to provide feedback and ask questions relevant to the specific work item on the card.

To add a comment, select a card to open the card view, then click on **Add a comment…** to type in your comment, and press **Send** to save the comment to the card. All team members who are `following the card </boards/work-with-cards.html#receive-updates>`_ will receive a notification with a preview of your comment in Mattermost Channels.

From Focalboard plugin v7.4, only board members with the *Commenter* role or higher can comment on a card. Board members assigned the *Viewer* role can view, but not comment on, a card.

## Mention people on cards

You can include a team member on a card by `mentioning them on a card </channels/mention-people.html>`__ the same way you would in Channels. Mentions are supported in the `Comments </boards/work-with-cards.html#comment-on-a-card>`_ and `Description </boards/work-with-cards.html#card-descriptions>`_ sections within a card. The team member you mention will receive a direct message notification from the boards bot with a link to the card you mentioned them on. To mention multiple team members, separate each name with a comma.

## Follow card updates

When you create a card, you automatically follow it. You can @mention someone on a card to add them as a follower. This can be a card you've created or someone else's card. Lastly, you can also follow cards manually using the **Follow** option on the top-right corner of a card. To unfollow a card, select **Following**.

When updates are made to a card you're following, you'll receive a direct message from the boards bot with a summary of the change (e.g. Bob changed status from **In progress** to **Done**) and a link to the card for more detailed information.

You won't get a notification of your own changes made to a card, even if you're following that card.

## Search for cards

You can search through all the cards on a board to find what you’re looking for. Open the board you want to search, then select the **Search cards** field in the top-right of the board.

## Manage card properties

Cards can contain different data fields depending on the purpose of the board. Using card properties, you can customize these data fields to fit your needs and track the information most important to you. For example, in a **Roadmap** board, cards include a **Type** field where you can add categories such as **Bug**, **Epic**, etc. In a **Project Task** board, cards include the **Estimated Hours** field instead.

Properties are displayed in the order they were created and can't be re-ordered.

## Create card properties

To create a new property field open a card and select **Add a property**. Then select the type of property from the drop-down menu. The property type specifies the type of data you plan to capture within that field. When you create new card properties, they're added to all new and all existing cards on the current board.

Properties are automatically added to the board filter list at the top of the page, so ensure you customize all property names to make it easy to filter your board by specific properties later.

## Work with property types

The Focalboard plugin supports a wide range of fully customizable property types:

- **Text** can be used to add short notes to a card. An advantage of the text property over card descriptions is that it can be `shown on the board <https://docs.mattermost.com/boards/work-with-cards.html#toggle-properties-shown-on-a-board>`_ without needing to open the card.
- **Numbers** are useful to capture metrics such as task sizing or effort estimates. Use in conjunction with calculations to get the most out of the number property type.
- **Email** and **Phone** can be used to record contact information.
- **URL** can be used to provide a link to a pull request or relevant website. Clicking on the box of a URL property will automatically open the link in a new tab on your browser. Hover over the box to surface options to copy or edit the URL.
- **Select** and **Multi-select** allows you to create a predefined list of options that can be color-coded and displayed as badges on the card to indicate things like status and priority.
- **Dates** are useful to set and track due dates or milestones. Use the date property to make a card appear on the `Calendar view <https://docs.mattermost.com/boards/work-with-views.html#calendar-view>`_. Set a single date or toggle on the **End date** to set a date range.
- **Person** and **Multi-person** provides a quick way to capture user assignments. Note that this is not available in Personal Desktop.
- **Checkbox** is a toggle property that can be used for assigning simple binary options on a card such as True/False or Yes/No.
- **Created time/Created by/Last updated time/Last updated by** are predefined system properties to help you audit changes on a card. The names of these properties are customizable, but the values are not.

### Rename a property type

The default name for a new property is the name of the property type (e.g. **Date**, **URL**).
To rename a property field, open up a card and select the property name to open an editable field. Enter the new name in the field provided. The change is saved immediately and applied across all cards on the current board.

### Change a property type

To change a property type, select the property then open the **Type** menu and choose a new property type. You’ll be asked to confirm the change from every card on the current board. Changing the type for an existing property will affect values across all cards on the board and may result in data loss.

### Delete a property

To delete properties you no longer need, select the property, then choose **Delete**. You’ll be asked to confirm that you want to remove that property from every card on the current board.

### Define a "Select" or "Multi-select" property

The options on a **Select** and **Multi-select** property type appear as color-coded tags on a card. Options in a **Select** or **Multi-Select** property list are sorted in the order they were created and can't be re-ordered or renamed.

To add and configure the options on these types:

1. Select a card to open the card view.
2. Add a new property, give it a name, and set its type to **Select** (or **Multi-Select**).
3. Select the field box for the property, and start typing the name of a new option. Press Enter to accept. Repeat this step to add additional options.
 - To assign a color to or delete an option, select the value and select the options menu **(...)** next to each option name.
 - To select an option on the property, select the box and choose one of the values from the menu.
 - To remove an option on the property, select the box and chooose the `X` next to the option name you want to remove.

Alternatively, you can also add new options directly from a board:

1. Open a board view.
2. Group by a **Select** property.
3. Scroll to the right of the board and select **+ Add a group**.

This will add a new column, which corresponds to a new value option for the Select property.

### Control what properties are shown on a board

Once you have card properties defined, you have full control over which properties are shown on the board as a preview without having to open the card. Select **Properties** at the top of the board, then enable all properties you want to see at a glance, and hide all properties you don’t want to see.

## Create card templates

Card templates can help reduce repetitive manual input for similar types of work items. Each board can have any number of card templates. To create a new card template:

1. Open the board where you want to add the card template.
2. Select the drop-down arrow next to **New**, then select **New template**.
3. Add a title to the card template.
4. Then assign values to any properties and add a description you wish to have pre-populated when a card is created from the template.
5. Close the card using the **X** in the top left corner.
6. Select the drop-down arrow next to **New**, then select the template you just created.

Alternatively, you can turn any existing card into a template:

1. Open the card you want to use as a template.
2. Select the options menu |options-icon| in the top-right corner of the card.
3. Select **New template from card**.
4. Edit the card as needed, including a helpful name.
5. Close the card using the **X** in the top left corner.
6. Select the drop-down arrow next to **New**, then select the template you just created.

To set a default card template for all new cards created on the board:

1. Select the drop-down arrow next to **New**.
2. Open the options menu |options-icon| next to the card template of your choosing.
3. Select **Set as default**.

**Notes**:

- The card template is applicable only to the board in which it’s created, and isn’t available in other boards within your team workspace.
- Comments on a template don't get populated on to new cards.
- Additionally, properties can't be hidden from a card template at this time. All cards on a board share the same properties, so adding or deleting a property on a template will also apply to all cards on a board.