WebMail Pro 7 documentation

JavaScript API

Introduction

Client-side API is used in WebMail plugins when it's necessary to have some interface changes, e.g. add another user setting screen, modify menu layout, etc.

Plugin architecture

To invoke client-side API, it's necessary to create 2 directories under data/plugins/plugin-name-here dir, called js and templates. They'll hold JavaScript files and HTML templates, respectively.

Let's assume the plugin is called my-custom-plugin, and the plugin class name is CMyCustomPlugin. We'll create data/plugins/my-custom-plugin/index.php file with the following content:

class_exists('CApi') or die();

class CMyCustomPlugin extends AApiPlugin
{
	/**
	 * @param CApiPluginManager $oPluginManager
	 */
	public function __construct(CApiPluginManager $oPluginManager)
	{
		parent::__construct('1.0', $oPluginManager);
	}

	public function Init()
	{
		parent::Init();

		/* This is where JS files and HTML templates are included */

		$this->AddJsFile('js/include.js');
	}
}

return new CMyCustomPlugin($this);

Including files

Under Init function, the following functions can be used to include JS files and HTML templates:

AddJsFile

Includes JavaScript file. Parameters:

$sJsFileName (string) — relative file path

AddTemplate

Includes HTML template. Parameters:

$sTemplateName (string) — template name for referencing in JS files. Will be prefixed with 'Plugin_'; so if the name is set to MyCustomTemplate, it's referenced as 'Plugin_MyCustomTemplate' in JS files.

$sTemplateFileName (string) — relative file path.

$sLayoutName (string, optional) — layout name this template will be used in. By default, mail template is used.

$sLayoutPosition (string, optional) — layout position this template will be used at. Available positions are are 'Layout-Top', 'Layout-Screens-Top', 'Layout-Screens-Middle' (default), 'Layout-Screens-Bottom', 'Layout-Bottom', Login-Footer.

IncludeTemplate

Include template into existing view model. Parameters:

$sParsedTemplateID (string) — template name we're including this template into. Currently, 'Login_LoginViewModel' is available.

$sParsedPlace (string) — template location this template is placed to.

$sTemplateFileName (string) — relative file path.

Screen	Location
Login_LoginViewModel	Login-Before-Submit-Button Login-Before-Description Login-After-Description.
Mail_ComposeViewModel	Compose-Attach-Buttons
Settings_AccountFoldersViewModel	Account-Folders-After-Buttons
Mail_LayoutSidePane_MessagePaneViewModel	Message-Pane-More-Actions-Menu
Common_HeaderViewModel	Header-Middle
Common_HtmlEditorViewModel	Html-Editor-Buttons

Including images and fonts

You might need to have images or fonts included in your plugin. However, standard security measures disallow accessing files found under the data directory. To work around that restriction, special methods were introduced.

AddFontFile

Includes font file for using it within a plugin. Parameters:

$sFontName (string) — font name.

:$sFontPath (string) — relative filesystem path from plugin directory to font file.

Once you have a font included that way, you can reference it in CSS as follows:

url("?plugins/fonts/plugin_name/font_name")

AddFontFile

Includes font file for using it within a plugin. Parameters:

$sImageName (string) — image name.

$sImagePath (string) — relative filesystem path from plugin directory to image file.

Once you have an image included that way, you can reference it in CSS as follows:

url("?plugins/images/plugin_name/image_name")

Client-side API reference

The following functions may be used in JS files:

AfterLogicApi.addScreenToHeader

Creates a link in top pane, with a specified screen opened on clicking it. Parameters:

sName (string) — screen name. Will be displayed in URL hash when screen is opened.

sHeaderTitle (string) — link text.

sDocumentTitle (string) — document title displayed for custom screen.

sTemplateName (string) — HTML template name used for this screen

oViewModelClass (Object) — JS view model constructor name used for this screen

AfterLogicApi.addSettingsTab

Creates an additional tab in settings screen, with custom setting screen opened on clicking it. Parameters:

oViewModelClass (Object) - JS view model constructor name
    Constructor prototype must contain the following properties:
    TemplateName (string) — HTML template name
    TabName (string) — screen name. Will be displayed in URL hash when screen is opened.
    TabTitle (string) — link tex displayed as tab name.

AfterLogicApi.getSetting

Obtain WebMail setting. Parameters:

sSettingName (string) – setting name.

AfterLogicApi.addPluginHook

Adds plugin hook handler. Parameters:

sName (string) — hook name. List of available hooks is found in next section.

fCallback (string) — function run when hook is triggered.

AfterLogicApi.sendAjaxRequest

Sends AJAX request to server. Parameters:

oParameters (Object) — AJAX-request parameters. Action parameter is required, it stands for specific operation to be performed.

fResponseHandler (Function, optional) — function called once response from server is received.

oContext (Object, optional) — context of fResponseHandler function call.

AfterLogicApi.isMobile

Returns boolean value, true if mobile version is currently used, false otherwise.
Works for Pro/Aurora only.

Client-side API hooks

The following hooks are available for use in AfterLogicApi.addPluginHook function:

response-custom-messages

Triggered upon fetching message list from server. Parameters:

iAccountId - account ID

sFolderFullName - full name of folder

aMessages - full list of messages. Custom properties can be accessed there, assuming they're added on backend API level

move-messages-to-trash

Triggered upon moving mails to Trash folder. Parameters:

iAccountId - account ID

sFolderFullName - full name of folder

aUids - UIDs of messages which were moved

move-messages-to-spam

Triggered upon moving mails to Spam folder. Parameters:

iAccountId - account ID

sFolderFullName - full name of folder

aUids - UIDs of messages which were moved.

delete-messages

Triggered upon deleting mails permanently. Parameters:

iAccountId - account ID

sFolderFullName - full name of folder

aUids - UIDs of messages which were deleted

view-message

Triggered upon viewing mail. Parameters:

iAccountId - account ID

sFolderFullName - full name of folder

sUid - UIDs of selected email message

view-model-on-show

Triggered upon rendering view model. Parameters:

sViewModelName - view model name

oViewModel - view model object

view-model-defined

Triggered after executing of constructor of view model. Parameters:

sViewModelName - view model name

oViewModel - view model object

ajax-default-request

Triggered prior to sending any AJAX request. Does not allow for aborting, but permits adding more request data. Parameters: sAction, oParameters

ajax-default-response

Triggered upon processing any AJAX request. Parameters: sAction, oData

close-all-htmleditor-popups

Triggered upon closing all popups in html editor. Without parameters.