Extensions

You can extend imdone in several ways outside of building a plugin.

Board Properties

Board properties are values that can be referenced in templates and cards using string interpolation. These properties are available to all cards in your project.

To add board properties, edit .imdone/properties/board.js by clicking on Extension Files -> Edit properties/board.js. Your module must export a function that conforms to the Plugin.getBoardProperties function

module.exports = function () {
  const project = this.project

  // These are the properties that are available to use in your cards
  // Use ${property_name} to permanently insert the value of the property
  // Use {{property_name}} to insert the value of the property at runtime
  return {
    cardTotal: cardTotal(project.totals),
    allTopics: project.allTopics, // This is an array of all the topics in the project
  }
}

function cardTotal(totals) {
  let count = 0
  Object.keys(totals).forEach((list) => {
    count += totals[list]
  })
  return count
}

Board Actions

Board actions are displayed in the main menu.

To add board actions, edit .imdone/actions/board.js by clicking on Extension Files -> Edit actions/board.js.

Your module must export a function that conforms to the Plugin.getBoardActions function

Here’s an example…

const path = require('path')

module.exports = function () {
  const project = this.project
  return [
    {
      title: "Open in vscode", // This is what displays in the main menu
      keys: ['alt+o'], // This is the keyboard shortcut
      icon: "code", // This is the font awesome icon that displays in the main menu
      action (task) {
        const url = `vscode://file/${path.join(project.path, task.path)}:${task.line}`
        project.openUrl(url)
      }
    }
  ]
}

Card Properties

Card Properties are values that can be referenced in templates and cards using string interpolation. These properties are available to all cards in your project.

To add card properties, edit .imdone/properties/card.js by clicking on Extension Files -> Edit properties/card.js. Your module must export a function that conforms to the Plugin.getCardProperties function

module.exports = function ({ line, source }) {
  // const project = this.project

  // These are the properties that are available to use in your cards
  // Use ${property_name} to permanently insert the value of the property
  // Use {{property_name}} to insert the value of the property at runtime
  return {
    sourceLink: `[${source.path}:${line}](./${source.path}:${line})`,
  }
}

When a new card is created in the imdone UI from a card template, javascript expressions surrounded by ${} will be permanently interpolated to the expressions value. (e.g. ${startDate} becomes 1-5-2020)

If you don’t want an expression permanently interpolated, use {{expression}} in your card template.

Card Actions

Card actions are menu items that will are added to the card menu that appears when you hover over the in the upper right corner of a card. Card Actions

To add card actions, edit .imdone/actions/card.js by clicking on Extension Files -> Edit actions/card.js.

Your module must export a function that conforms to the Plugin.getCardActions function

module.exports = function (task) {
  const project = this.project
  const actions = [
    {
      title: `Add a card in ${task.source.path}`,
      action: () => {
        project.newCard({
          list: 'TODO',
          path: task.source.path,
        })
      },
      icon: 'plus',
    },
    {
      title: `Copy source path to clipboard`,
      action: () => {
        project.copyToClipboard(
          task.source.path,
          `${task.source.path} copied to clipboard`
        )
      },
      icon: 'clone',
    },
    {
      title: `Filter by ${task.source.path.split('/').pop()}`,
      action: () => {
        project.setFilter(`source.path = "${task.source.path}"`)
      },
      icon: 'filter',
    },
    {
      title: 'Tweet this card!',
      action: () => {
        project.openUrl(
          `https://twitter.com/intent/tweet?text=${
            task.data.encodedText
          }%0A${encodeURIComponent(
            task.data.hashtags
          )}%0ATweeted%20with%20@imdoneio`
        )
      },
      icon: 'twitter',
    },
  ]

  if (task.allMeta.github) {
    actions.push({
      title: `Open issue ${task.allMeta.github} in github`,
      action: () => {
        project.openUrl(
          `https://github.com/imdone/imdone/issues/${task.allMeta.github}`
        )
      },
      icon: 'github',
    })
  }
  return actions
}

icon

The icon to display for the link

Attributes of Task and task.data

Name Description
allContext Context declared in the card and file front-matter
allMeta Metadata declared in the card and file
allTags Tags declared in the card and file front-matter
clearFilterURL The URL to clear the current filter
completed If a meta completed date is set, this is the completed date in ISO format
content The content of the card before string interpolation
context The card contexts (e.g. @email @phone would be email, phone)
created If a meta created date is set, this is the created date in ISO format
date The date in ISO format
description An Array of lines occuring after the card in it’s source file
due If a meta due date is set, this is the date due in ISO format
fullPath The path to the card’s source file
getFilterURL(filter) get a filter url for a filter
getFilterLink(filter) get a filter markdown link with the filter as link text
interpretedContent The content of the card after string interpolation
line The line number where the card is located in it’s source file
lastLine The last line of the card in source
list The name of the list the card is in
meta The card metadata (e.g. name:Jesse and {{meta.name}} in the card content would display Jesse.)
progress.completed Number of completed subtasks
progress.total Total number of subtasks
projectPath The path to the project
relPath The path to the card’s source file, relative to the projectPath
source.createdTime The createdTime of the source file in ISO format
source.ext The source file extension
source.modifiedTime The modifiedTime of the source file in ISO format
source.path The path to the card’s source file, relative to your project path
source.repoId The file system path to your project
tags The card tags (e.g. +feature would be feature)
template_ All files in .imdone/templates and .github will be added as a property here. e.g. template_dod would be the contents of .imdone/templates/dod.md
template_simple A simple template for cards
text The first line of markdown in a card
timestamp The timestamp of the card in ISO-8601 format
totals An object containing the total number of cards in each list. e.g. totals.DOING = 2 means there are 2 cards in DOING

The following properties will be available in task.data along with properties declared in .imdone/properties/card.js

Name Description
encodedMD The encoded card content
encodedText The encoded card content with all markdown formatting removed
html The card html
markdown The card content