<?php
/*
* RCMCardDAV - CardDAV plugin for Roundcube webmail
*
* Copyright (C) 2011-2022 Benjamin Schieder <rcmcarddav@wegwerf.anderdonau.de>,
* Michael Stilkerich <ms@mike2k.de>
*
* This file is part of RCMCardDAV.
*
* RCMCardDAV is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* RCMCardDAV is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with RCMCardDAV. If not, see <https://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
namespace MStilkerich\RCMCardDAV\Frontend;
use rcube_utils;
/**
* Adapter interface to roundcube APIs.
*
* This allows us to decouple the dependencies from roundcube to a large extent (except for where be subclass roundcube
* classes) and therefore improves testability.
*
* @psalm-type RcMsgType = 'notice'|'confirmation'|'error'|'warning'
*/
interface RcmInterface
{
/**
* Returns a localized text string.
*
* @param string $msgId The identifier of the text.
* @param array<string,string> $vars Variables to replace in the text.
* @return string The localized text string.
*/
public function locText(string $msgId, array $vars = []): string;
/**
* Gets a POSTed input value.
*
* @param string $id Form identifier of the field.
* @param bool $allowHtml Whether to allow HTML tags in the input. If false, HTML tags will be stripped.
* @param \rcube_utils::INPUT_* $source
* @return ?string Field value or NULL if not available.
*/
public function inputValue(string $id, bool $allowHtml, int $source = rcube_utils::INPUT_POST): ?string;
/**
* Shows a message to the roundcube user.
* @param string $msg The message.
* @param RcMsgType $msgType
* @param bool $override Override last set message
* @param int $timeout Message displaying time in seconds
*/
public function showMessage(string $msg, string $msgType = 'notice', bool $override = true, int $timeout = 0): void;
/**
* Call a client (javascript) method
*
* @param string $method Method to call
* @param string|bool|int|array ...$arguments Additional arguments
*/
public function clientCommand(string $method, ...$arguments): void;
/**
* Installs a roundcube hook function.
*/
public function addHook(string $hook, callable $callback): void;
/**
* Register a handler for a specific client-request action
*
* The callback will be executed upon a request like /?_task=mail&_action=plugin.action
*
* @param string $action Action name (should be unique)
* @param callable $callback Callback function
*/
public function registerAction(string $action, callable $callback): void;
/**
* Loads localized texts for the current locale.
*/
public function addTexts(string $dir): void;
/**
* Includes a CSS on the page.
*
* @param string $cssFile Path to CSS file relative to the plugin's skin path.
*/
public function includeCSS(string $cssFile): void;
/**
* Includes a javascript file on the page.
*
* @param string $jsFile Path to JS file relative to the plugin's skin path or roundcube standard JS paths.
* @param bool $rcInclude If true, the script to include is taken from the roundcube path, not the plugin.
*/
public function includeJS(string $jsFile, bool $rcInclude = false): void;
/**
* Register a GUI object to the client script
*
* @param string $obj Object name
* @param string $id Object ID
*/
public function addGuiObject(string $obj, string $id): void;
/**
* Setter for page title
*
* @param string $title Page title
*/
public function setPageTitle(string $title): void;
/**
* Register a template object handler
*
* @param string $name Object name
* @param callable $func Function to call
* @psalm-param callable(array{id: string}):string $func
*/
public function addTemplateObjHandler(string $name, callable $func): void;
/**
* Send the request output to the client.
* This will either parse a skin template.
*
* @param string $templ Template name
* @param bool $exit True if script should terminate (default)
*/
public function sendTemplate(string $templ, bool $exit = true): void;
/**
* Build a form tag with a unique request token
*
* @param array<string,string> $attrib Named tag parameters including 'action' and 'task' put into hidden fields
* @param string $content Form content
*
* @return string HTML code for the form
*/
public function requestForm(array $attrib, string $content): string;
/**
* Sets an environment variable in roundcube and optionally also the frontend.
*
* @param string $name Property name
* @param string|bool|int $value Property value
* @param bool $addToJs True if this property should be added to client environment
*/
public function setEnv(string $name, $value, bool $addToJs = true): void;
}
// vim: ts=4:sw=4:expandtab:fenc=utf8:ff=unix:tw=120