WebMods

Check out Modules for an overview on loading/unloading and other general information.

Overview

Webmods are normal global/user modules like any other that implement code for serving web content. There are a few hooks (virtual functions in the CModule base class) that can be overriden to customize the pages served via the http/https socket(s). It's probably best to think of znc as a webserver serving a webapp (website) with modular content.

Currently a module author can do the following...

1. Insert a link to your module into the main menu
2. Insert sub pages into the main menu
3. Serve content to Admins only
4. Serve content to logged in users only
5. Serve content to anonymous users
6. Provide your own .tmpl file and <? INC Header ?> your content <? INC Footer ?> to use the current skin
7. Ditch the current skin and do your own thing (xml feed, binary files, etc)

Connecting

By default znc serves web traffic and irc traffic on the same port

ZNC listens on the port using the HTTP protocol so that you may connect to znc using a web browser. For example, if your ZNC is running on a shell called foo.com and it listens on port 8080 (non-SSL) and port +9090 (ssl) then you would open up your favorite browser and go to either of these URLs:

http://foo.com:8080/

https://foo.com:9090/

ZNC users who are not admins are still able to connect using their ZNC username and password to authenticate. Some modules will provide extra functionality to admin users and other modules might even serve content to users who are not authenticated all together.

Hooks

Currently there are hooks that can be overridden to modify the site's behavior.

WebRequiresLogin()

virtual bool WebRequiresLogin() { return true; }

Return true to deny anonymous access. The user must have a znc login/pass.

WebRequiresAdmin()

virtual bool WebRequiresAdmin() { return false; }

Return true to require admin privileges. The user must have a znc login/pass with the admin flag set.

GetWebMenuTitle()

virtual CString GetWebMenuTitle() { return ""; }

Return the title of your module. This is currently only used in the Menu.tmpl for the nav link. It may be used elsewhere by skin authors or future code.

OnWebRequest()

virtual bool OnWebRequest(CWebSock& WebSock, const CString& sPageName, CTemplate& Tmpl);

This is where the magic happens. It is the entry point to serving your own page.

The WebSock object handles things like GetParam(), Redirect(), PrintErrorPage(), etc.

The sPageName string tells you which subpage is being requested. An empty page name is the same as "index" and will load the index.tmpl. Other page names will load their pagename.tmpl file. There are multiple paths that pagename.tmpl files are looked for, see the Paths section below.

The Tmpl object is filled with some global values and passed to you to fill the values needed for your specific .tmpl file.

OnEmbeddedWebRequest()

bool OnEmbeddedWebRequest(CWebSock& WebSock, const CString& sPageName, CTemplate& Tmpl);

This behaves similarly to OnWebRequest in that it looks for web content to add but this allows modules to embed content in pages served by other modules.

Currently it is only implemented for embedding in webadmin user and channel pages. blockuser, stickychan, and lastseen take advantage of embedding currently.

Paths

One sec!

Modules

When serving normal pages from modules, you will normally put your template files here...

  <zncroot>/modules/example_mod/tmpl/pagename.tmpl

Assuming your znc listens on +9999 and that module's type is "global", the above file can be reached via this url...

  https://your.shell_name.com:9999/mods/global/example_mod/pagename

If your page requires extra files such as an rss.gif for example, you should put it here...

  <zncroot>/modules/example_mod/files/rss.gif

And it will be available at this url...

  https://your.shell_name.com:9999/modfiles/global/example_mod/rss.gif

When referring to any path, you should use GetWebPath() or GetWebFilesPath(). For example, to get the path to rss.gif, you would use the following:

GetWebFilesPath() + "rss.gif"

In a template you should use the variables "ModPath" and "ModFilesPath", to get rss.gif in a template you should use:

<? VAR ModFilesPath TOP ?>rss.gif

Custom Module Skins

You can add your own style to znc's web interface. All of the HTML is stored in templates.

SubPage Templates

In order for your module's subpages to have the same look and feel of the currently selected skin, the templates should generally look like this...

  <? INC Header.tmpl ?>
     Your Content Here
  <? INC Footer.tmpl ?>

Since you won't be supplying a Header.tmpl nor a Footer.tmpl (you could, but probably won't since you're a module author not a skin author) these templates will both be obtained from the currently selected skin for that session.

Blending In

You should also follow a few guidelines so that your module will blend in nicely with the rest of the site. For instance, if you have tabular data, you should use <table class="data">, <thead> and <tbody> where appropriate. You can also use for highlighting. These classes are handled in the skin's css file. Hopefully this document will be kept up to date with all of the conventions used, but it would probably be a good idea to check what the other modules are doing. Tables should always use <tr class="<? IF __EVEN__ ?>evenrow<? ELSE ?>oddrow<? ENDIF ?>">.

Module List

Some of the modules listed here may not be available in the current release. If that's the case, you have to use GIT.

Modules Known to Serve Web Pages

This is not an exhaustive list of modules, or even webmods for that matter. See Modules for a list of all documented modules.

webadmin

Web based administration. This module is the predecessor to webmods.

webchat

Web based chat. Currently a work in progress.

notes

Keep notes for yourself that get played back upon connect. You can also display/edit notes in your browser. Look here for the basic example of ZNC webmod.

lastseen

Overview page to spot inactive users

stickychan

Stick and unstick channels from the web