Skip to content

03. Plugins

Jump to bottom Edit New page
github-actions[bot] edited this page Feb 26, 2025 · 1 revision

Overview

Kiwi IRC support customisation through the use of plugins. They can be used to add features, change behaviour, change styles or even replace existing components.

Plugins can be used by uploading them to your server and loading them via config.json


Creation

Plugin creation comes in three main forms a simple javascript file .js, a simple HTML file .html, or a webpack javascript file .js.

Bigger plugins may have multiple assets (images, translations etc), it is recommended to put them into a directory with the same name as the plugin (without its extension)


Simple Javascript

This is the most basic of plugin formats and is good for smaller plugins that do not require any of the features provided by the other types.

A plugin in this format would start begin with this example:


kiwi.plugin('plugin_name', function(kiwi, log) {
    // Plugin code here
});

Simple HTML

A plugin with a .html extension is treated more like a vue.js single file component

It can contain multiple <template id="example-ui-browser"> the id property would be used to tell the <script> part how to find the template.

The <script> tag would contain the javascript required for the plugin similar to Simple Javascript

One or more <style> tags can be used to contain any css styles that are used within the plugin, or to override existing Kiwi IRC styles.

Following is an example HTML plugin that adds a button to the state browser just under the users avatar:


<template id="example-ui-browser">
    <div @click="doClick" class="example-ui-browser">
        <div>addUi('browser'</div>
        <div>{{ text }}</div>
        there are {{ networks.length }} networks
    </div>
</template>

<script>
const browserComponentObject = {
    template: '#example-ui-browser',
    props: ['networks', 'sidebarState', 'text'],
    methods: {
        doClick(event) {
            console.log('Clicked addUI browser', event);
        }
    }
};

kiwi.addUi('browser', browserComponentObject, { props: { text: 'this is a prop' } });
</script>

<style>
.example-ui-browser {
    border: 2px dashed red;
    cursor: pointer;
}
</style>

Webpack Javascript

This is the most complicated method of creating plugins for Kiwi IRC. It is the best option for larger plugins as it allows for compiling .vue files and other tooling.

A good example of this method can be seen in plugin-conference. This plugin could also be used as a template to start a new plugin as its configured for webpack and vue files.


API

Most interactions with the Kiwi IRC API are done via window.kiwi.* global.

The following documentation will attempt to guide you through the features supported by the API.

For simpler commands they can be tested via the web browser's console (F12).


Globals

The plugin API provides two main global javascript variables kiwi and _.

kiwi is the main API interface for Kiwi IRC.

_ is a global instance of lodash, which provides some useful javascript helpers.

note: If you are using webpack you can use comments to inform your linters that these variables exist. The comment would be placed at the top of your <script>.

/* global kiwi:true, _:true */

Kiwi IRC also provides a global instance of FontAwesome v4.7

They can be used within your <template> like below:

<i class="fa fa-thumbs-up" aria-hidden="true"></i>

window.kiwi.*

The main API interface

Property Description
.version The Kiwi IRC version
.commithash The Kiwi IRC git hash that was built
.Vue A Vuejs global instance
.themes Theme manager
.state The Kiwi internal application state. Described below
plugin(pluginName, fn) Create a new plugin
addUi(type, element) Extend the Kiwi UI
addTab(name, component, props) Add a custom tab to a section of the UI
addView(name, component, props) Add a custom view (page)
showView(name) Show a view added via addView()
addStartup(name, ctor) Add a new startup screen
showInSidebar(component) Show a view in the sidebar
require(module) Get a Kiwi internal module instance
replaceModule(module, new_module) Replace an module or component
on(eventName, fn) Listen for an application event
once(eventName, fn) Listen for an application event one time only
off(eventName, fn) Stop listening for an application event
emit(eventName, arg1, arg2) Emit an event on the application event bus

window.kiwi.state.*

The Kiwi internal application state. The entire application uses this interface to modify state such as adding or removing networks, adding buffers / messages / users, getting the active network or buffer.

exportState(includeBuffers)
importState(stateStr)
resetState()

setting(name, val)
getSetting(name)
setSetting(name, newVal)

getActiveNetwork()
getNetwork(networkid)
getNetworkFromAddress(netAddr)
addNetwork(name, nick, serverInfo)
removeNetwork(networkid)

getActiveBuffer()
setActiveBuffer(networkid, bufferName)
openLastActiveBuffer()
updateBufferLastRead(networkid, bufferName)
getOrAddBufferByName(networkid, bufferName)
getBufferByName(networkid, bufferName)
addBuffer(networkid, bufferName)
removeBuffer(buffer)

addMessage(buffer, message)
getMessages(buffer)

getUser(networkid, nick, usersArr_)
usersTransaction(networkid, fn)
addUser(networkid, user, usersArr_)
removeUser(networkid, user)
addMultipleUsersToBuffer(buffer, newUsers)
addUserToBuffer(buffer, user, modes)
removeUserFromBuffer(buffer, nick)
getBuffersWithUser(networkid, nick)
changeUserNick(networkid, oldNick, newNick)

getStartups()

Event bus

This is the main event bus for the application. Events are emitted by many places and some allow you to emit your own so that you can interact with Kiwi.

These events can be listened for via kiwi.on('event.name', function() {}). For events marked that they can be fired from plugins, you can do so via kiwi.emit('event.name', arg1, arg2).

Name Arguments Can be fired from plugins Description
ready no Kiwi has loaded and ready to show the startup screen
document.clicked MouseEvent no The page has its click event triggered
document.keydown KeyboardEvent no The page has its keydown event triggered
active.component VueComponent yes Set the active component in the main view
statebrowser.toggle yes Hide / Show the state browser
statebrowser.hide yes Hide the state browser
statebrowser.show yes Show the state browser
sidebar.toggle yes Hide / Show the sidebar
sidebar.hide yes Hide the sidebar
sidebar.show yes Show the sidebar
network.settings network yes Show the settings for the given network
input.raw rawText yes Simulate user input
input.command.[command] event, command, params no An input command is being executed
mediaviewer.hide yes Hide the media viewer
mediaviewer.show url yes Open the media viewer with the given URL
mediaviewer.opened no Media viewer has been opened
userbox.show user yes Open the user information panel for the given user
irc.raw command, event, network no Raw IRC message from the IRC server
irc.raw.[command] command, event, network no A raw IRC message from the IRC server
irc.[command] event, network, ircEventObj no A parsed IRC event from the IRC library
network.new eventObj no A new network has been added
network.removed eventObj no A network has been deleted
network.connecting eventObj no A network connection is about to start
buffer.new eventObj no A new buffer has been added
buffer.close eventObj no A buffer has been closed
server.tab.show tabName yes When a server buffer is open, show the given tab
theme.change yes Notify the application that the theme has been changed
message.render eventObj no A message is about to be rendered
user.avatar.create eventObj no A unique avatar is attempting to be rendered
user.avatar.failed eventObj no All avatar urls failed to load
Add a custom footer
Add a custom sidebar
Clone this wiki locally