A Basic Plugin

##Before reading this, make sure you have installed Quail.

A Basic Plugin

This plugin will, when a query containing the word 'sample' is said, respond accordingly.

The Easy Way

1. Go to this repo: https://github.com/1egoman/qplugin
2. Clone it, or click the "Download Zip" button in the lower left
3. Extract the zip (if necessary)
4. Copy the examples/basic folder that has just been cloned into Quail's plugins folder (<quail root>/plugins)
5. Start Quail
6. Run a test query: (query phrase in the server console)
7. Watch the magic happen!

The Harder Way

This will guide you through writing the code on your own. ###The Code All a plugin minimally has to have is an info.json:

{
  "name": "Plugin Name, Capitalized",
  "desc": "short description of the plugin, maybe a line or so",
  "author": "your name, contact info",
  "main": "main_file.py:sample_parser"
}

and a main_file.py (named accordingly in info.json):

from base import *
class sample_parser(parser):
  
  def validate(self):
    return "phrase" in self.query
  
  def parse(self): 
    self.resp["text"] = "This is a sample response!"
    self.resp["status"] = STATUS_OK
    return self.resp

Put both those files in a folder inside the plugins folder, and you've made a small plugin (that does nothing)!

main_file.py Explained

from base import *

This is a module that contains everything the plugin will need to function. Always include it at the top of any plugin!

class sample_parser(parser):

Creates a new object named 'sample_plugin'. If you aren't familiar with object oriented programming and the concept of objects, I found this to explain them pretty well.

  # whether to run the plugin based on the user's query
  def validate(self):
    # the query is available under self.query to test against
    return "sample" in self.query

The validate() function is one of the functions required in a plugin. This function should return a boolean value depending on if the plugin is suited to handle what the query says. If the plugin can parse the query, return True. Otherwise, return False. In every plugin, self.query contains the contents of the query that the user made, as a list of words. In our example:

test phrase -> False
sample test phrase -> True
sampletest phrase -> False

(the last example doesn't work because self.query is a list of words, not a string)

  # parse the query if it was validated
  def parse(self, parent): 
    self.resp["text"] = "This is a sample response!"
    self.resp["status"] = STATUS_OK
    return self.resp

The parse() function is the main function in any plugin. If validate() is true, then parse() is executed to determine what the plugin's output is. In parse(), the parent argument points back to the main app class. I'll get into why this is useful in another page. self.resp is a dictionary that holds the data sent back to the user. Always set the status element to be equal to STATUS_OK unless the plugin failed to produce a result. Set the text element equal to the output of the plugin, or whatever message that you want the user to recieve. If you don't return self.resp from the parse function, strange things will happen!

Running the plugin

When testing out plugins, it is recommended to run Quail a little differently than normal. After opening a terminal in Quail's drectory, run ./quail.py go. This will run Quail in verbose mode so you can see any errors or issues that may arise. A list of commands is available here.