Plugin follows a simple API for producing results.
Tag your theme modules with the keywords: dext
, and dext-plugin
.
For an example, please refer to the dext-demo-plugin.
All plugin modules are required to have a keyword
property. You will also need to define the type of action
for your items.
keyword | description |
---|---|
keyword |
the keyword filter for your plugin |
action |
the type of action to be executed when an item is chosen |
query |
an object containing an items array or a function returning the object or a Promise resolving the object |
details |
see Details Pane |
Copies the arg
of the selected item. (Uses modifiers where necessary).
Executes a the node script arg.script
of the selected item and is passed the array arg.arg
as an argument.
The script can retrieve the arguments like this:
const arg = process.argv // Returns an array of arguments:
// The first element is the node enviroment
// The second element is the script being run
// The third element onwards are the arguments passed on by the plugin.
Opens a file in the desktop's default banner.
Opens the item in a new browser window. (Uses modifiers where necessary).
A very basic module.
module.exports = {
keyword: 'foo',
action: 'openurl',
query: {
items: [], // array of items (refer to the item schema below)
},
};
You can use functions for your search query.
module.exports = {
keyword: 'foo',
action: 'openurl',
query: function(q /**, options */) {
// q is the query the user entered (excludes the keyword)
// do something here like query a remote database to retrieve results
return {
items: [], // array of items (refer to the item schema below)
};
},
};
Your function can also return Promises that resolves the result object.
module.exports = {
keyword: 'foo',
action: 'openurl',
query: function(q /**, options */) {
// q is the query the user entered (excludes the keyword)
// do something here like query a remote database to retrieve results
return new Promise(function(resolve) {
resolve({
items: [], // array of items (refer to the item schema below)
});
});
},
};
The options
parameter contains the following key(s):
Type: Number
You can use size
to set a limit on an API call in your plugin
query: function(q, { size }) {
return new Promise(function(resolve) {
request.get({ url: `example.org?search=${q}&limit=${size}` }, (err, response, body) => {
// handle response...
})
});
},
Plugin helper items can provide quick information to the user as they drill deeper into your plugin commands.
Simple helper item.
module.exports = {
keyword: 'foo',
action: 'openurl',
// The helper property follows the Item schema and will be
// shown to the user when the keyword is active
helper: {
title: 'This is the title',
subtitle: 'This is the subtitle',
icon: {
path: './icon.png',
},
},
query: {
items: [],
},
};
Like the search query, you can return the item within a Function
.
module.exports = {
keyword: 'foo',
action: 'openurl',
// The query keyword is passed as the first argument in the callback function
helper: function(q) {
title: 'Search for ' + q,
subtitle: 'This is the subtitle',
icon: {
path: './icon.png',
},
},
};
Or as a Promise
.
module.exports = {
keyword: 'foo',
action: 'openurl',
// The query keyword is passed as the first argument in the callback function
helper: function(q) {
return new Promise(function(resolve) {
resolve({
title: 'Search for ' + q,
subtitle: 'This is the subtitle',
icon: {
path: './icon.png',
},
});
});
},
};
Sometimes you want to display more information to the user because a small icon with 2 lines is just not enough in some instances. A details pane can be created and shown to the user per item by creating a details
object in your plugin module.
The Details Pane currently supports only 2 types of renderer:
html
md
Specify the type of renderer to use. Details Pane currently supports only html
and md
Type: String
The rendered output.
When using render
as a Function
, this should return a String
or returns a Promise
that resolves a String
. The currently selected item
is passed into the callback function.
Type: String
, Function
Using basic HTML.
module.exports = {
keyword: 'foo',
query: {
items: [], // array of items
},
details: {
type: 'html',
render: '<p>This is regular HTML.</p>',
},
};
Using Markdown.
module.exports = {
keyword: 'foo',
query: {
items: [], // array of items
},
details: {
type: 'md',
render: '## This is Markdown',
},
};
You can use a function to access the currently selected item.
module.exports = {
keyword: 'foo',
query: {
items: [], // array of items
},
details: {
type: 'md',
render: function(item) {
return item.bodyContent;
},
},
};
Use a Promise if you need to do some work that requires waiting.
module.exports = {
keyword: 'foo',
query: {
items: [], // array of items
},
details: {
type: 'md',
render: function(item) {
return new Promise(function(resolve) {
// load data from an external API...
fetch('https://my-api.com/demo/endpoint/').then(function(data) {
resolve(loadedContent);
});
});
},
},
};
Type: String
The title to be displayed.
Type: String
An optional subtitle to be displayed beneath the title.
Type: String
Additional parameters to be passed to the action.
Type: Object
Type: String
If specified, this string will be copied into the clipboard when the user activates the copy to clipboard command: cmd + c.
Type: object
Type: String
Options: file
, text
Type: String
If icon.type
isn't set or is file
, the image will be served as the icon. (Can be a URL or file path.)
Type: String
If icon.type
is set to text
, a round circle will be displayed with the specified letter.
Type: String
If icon.type
is set to text
, you can specify the background color of the icon with a valid CSS color value.
Sample item with a regular URL icon.
{
"title": "GitHub",
"subtitle": "Build software better, together",
"arg": "https://github.com",
"icon": {
"path": "https://github.com/fluidicon.png"
}
}
Sample item with letter icon.
{
"title": "GitHub",
"subtitle": "Build software better, together",
"arg": "https://github.com",
"icon": {
"type": "text",
"letter": "G",
"bgColor": "transparent"
}
}
You can use alfy to create a workflow or you can create your own.
Your plugin should output a string representing an array of result items.