Developing

Developing with the Helm Framework

• Introduction
• Creating a Helm buffer
• Creating a Source
• Creating a Class
• Conventions

Introduction

The best way to learn how to create a custom Helm command is to read the source code and look at examples. A good place to start is the helm-info.el file, which is fairly short and straightforward.

That being said, we’ll try to go over some basic ideas in this (far from comprehensive) Wiki.

Creating a Helm buffer

The helm function creates a Helm buffer with candidates to select and/or take action on. The list of candidates is provided by one or more sources.

An example usage of helm is below:

(defun my-first-helm-command ()
  (interactive)
  (helm :sources 'my-source
        :buffer "*helm my command*"))

helm must be called with several keywords arguments.

:sources

Mandatory.

Expects a source of the form:

• Single source (alist)
• Symbol naming the source
• List of sources (alist or symbol)

Examples are below:

;; Alist
sources '((name . "test") (candidates . (a b c d)))

;; List of alists
:sources '(((name . "test") (candidates . (a b c d)))
           ((name . "test2") (candidates . (e f g h))))

;; Symbol
:sources 'helm-source-1

;; List of symbols
:sources '(helm-source-1 helm-source-2 helm-source-3)

:buffer

Optional but important.

The value for the :buffer keyword helps the helm-resume command retrieve the Helm session.

The name of the buffer should be prefixed with helm (e.g. *helm Info*). This is not mandatory, but it is good practice. It will, among other things, allow Helm to automatically hide the buffer.

Creating a Source

There are three basic functions for creating a Helm source:

• helm-source-sync, which puts candidates in a list.
• helm-source-in-buffer, which puts candidates in a buffer.
• helm-source-async, which gets candidates asynchronously using the output of a process.

For consistency, prefix your source names with helm-source- (e.g. helm-source-info-emacs).

helm-source-sync

(helm-build-sync-source "test"
  :candidates '(a b c d e))

(helm :sources (helm-build-sync-source "test"
                 :candidates '(a b c d e))
      :buffer "*helm sync source*")

helm-source-in-buffer

(helm-build-in-buffer-source "test1"
  :data '(a b c d e))

(helm :sources (helm-build-in-buffer-source "test1"
                 :data '(a b c d e))
      :buffer "*helm buffer source*")

helm-source-async

(helm :sources (helm-build-async-source "test2"
                 :candidates-process
                 (lambda ()
                   (start-process "echo" nil "echo" "a\nb\nc\nd\ne")))
      :buffer "*helm source async*")

Help

To give a specific help to your Helm source, create a variable helm-<my-source>-help-string and bind it in your source with the helm-message slot. It will then will appear when you use C-h m or C-c ?.

Creating a Class

Create your own class inheriting from one of the main classes

Create your own class and Inherit from one of helm-type classes

Write your own helm-type class

Create your source from your own class

Conventions

Class names

Class names are currently a mess. Need to come up with a better convention.