PHP Q_Response::setToolOptions方法代码示例

/**
 * Standard tool for making payments.
 * @class Assets payment
 * @constructor
 * @param {array} $options Override various options for this tool
 *  @param {string} $options.payments can be "authnet" or "stripe"
 *  @param {string} $options.amount the amount to pay.
 *  @param {double} [$options.currency="usd"] the currency to pay in. (authnet supports only "usd")
 *  @param {string} [$options.payButton] Can override the title of the pay button
 *  @param {String} [$options.publisherId=Users::communityId()] The publisherId of the Assets/product or Assets/service stream
 *  @param {String} [$options.streamName] The name of the Assets/product or Assets/service stream
 *  @param {string} [$options.name=Users::communityName()] The name of the organization the user will be paying
 *  @param {string} [$options.image] The url pointing to a square image of your brand or product. The recommended minimum size is 128x128px.
 *  @param {string} [$options.description=null] A short name or description of the product or service being purchased.
 *  @param {string} [$options.panelLabel] The label of the payment button in the Stripe Checkout form (e.g. "Pay {{amount}}", etc.). If you include {{amount}}, it will be replaced by the provided amount. Otherwise, the amount will be appended to the end of your label.
 *  @param {string} [$options.zipCode] Specify whether Stripe Checkout should validate the billing ZIP code (true or false). The default is false.
 *  @param {boolean} [$options.billingAddress] Specify whether Stripe Checkout should collect the user's billing address (true or false). The default is false.
 *  @param {boolean} [$options.shippingAddress] Specify whether Checkout should collect the user's shipping address (true or false). The default is false.
 *  @param {string} [$options.email=Users::loggedInUser(true)->emailAddress] You can use this to override the email address, if any, provided to Stripe Checkout to be pre-filled.
 *  @param {boolean} [$options.allowRememberMe=true] Specify whether to include the option to "Remember Me" for future purchases (true or false).
 *  @param {boolean} [$options.bitcoin=false] Specify whether to accept Bitcoin (true or false). 
 *  @param {boolean} [$options.alipay=false] Specify whether to accept Alipay ('auto', true, or false). 
 *  @param {boolean} [$options.alipayReusable=false] Specify if you need reusable access to the customer's Alipay account (true or false).
 */
function Assets_payment_tool($options)
{
    Q_Valid::requireFields(array('payments', 'amount'), $options, true);
    if (empty($options['name'])) {
        $options['name'] = Users::communityName();
    }
    if (!empty($options['image'])) {
        $options['image'] = Q_Html::themedUrl($options['image']);
    }
    $options['payments'] = strtolower($options['payments']);
    if (empty($options['email'])) {
        $options['email'] = Users::loggedInUser(true)->emailAddress;
    }
    $payments = ucfirst($options['payments']);
    $currency = strtolower(Q::ifset($options, 'currency', 'usd'));
    if ($payments === 'Authnet' and $currency !== 'usd') {
        throw new Q_Exception("Authnet doesn't support currencies other than USD", 'currency');
    }
    $className = "Assets_Payments_{$payments}";
    switch ($payments) {
        case 'Authnet':
            $adapter = new $className($options);
            $token = $options['token'] = $adapter->authToken();
            $testing = $options['testing'] = Q_Config::expect('Assets', 'payments', $lcpayments, 'testing');
            $action = $options['action'] = $testing ? "https://test.authorize.net/profile/manage" : "https://secure.authorize.net/profile/manage";
            break;
        case 'Stripe':
            $publishableKey = Q_Config::expect('Assets', 'payments', 'stripe', 'publishableKey');
            break;
    }
    $titles = array('Authnet' => 'Authorize.net', 'Stripe' => 'Stripe');
    Q_Response::setToolOptions($options);
    $payButton = Q::ifset($options, 'payButton', "Pay with " . $titles[$payments]);
    return Q::view("Assets/tool/payment/{$payments}.php", compact('token', 'publishableKey', 'action', 'payButton'));
}

/**
 * Renders a Websites/presentation stream,
 * including an interface to edit the presentation
 * for users who have the permissions to do so.
 * @param {array} $options
 * @param {string} $options.publisherId
 * @param {string} $options.streamName
 */
function Websites_presentation_tool($options)
{
    Q_Response::addStylesheet('plugins/Websites/css/Websites.css');
    Q_Response::addScript('plugins/Websites/js/Websites.js');
    Q_Response::setToolOptions($options);
    return '';
}

/**
 * Ticker that scrolls its contents with various speeds and pauses
 * @class Q ticker
 * @constructor
 * @param {array} $options
 *  An associative array of fields, possibly including:
 *
 * "content" => string
 *  The content of the ticker. The first top-level element
 *  should contain sub-elements, and their sizes determine where
 *  the ticker would pause between automatically scrolling.
 *  The ticker animates by scrolling its inner contents.
 *
 * "vertical" => bool
 *  Defaults to true. If false, the ticker scrolls horizontally.
 *
 * "speed" => integer
 *  The scrolling speed.
 *  This is the number of items that would scroll by in 1 second,
 *  if there were no pauses.
 *  When the speed is positive, vertical tickers scroll down, and
 *  horizontal tickers scroll to the right. New content seems to come in
 *  from the bottom (for vertical tickers) or right (for horizontal tickers)
 *  as the ticker scrolls. The element inside the ticker will start out
 *  aligned with the top side of the ticker (for vertical tickers),
 *  or the left side of the ticker (for horizontal tickers).
 *  When the speed is negative, all this faces the other way.
 *
 * "pause_ms" => int
 *  Defaults to 2000. This is the number of milliseconds to wait
 *  after each second-level element of $content is automatically
 *  scrolled completely into view.
 *
 * "pause_ms_min" => int
 *  If set, then the number of milliseconds to pause is a random
 *  integer between $pause_ms_min and $pause_ms.
 *
 * "scrollbars" => bool
 *  Defaults to true. If true, shows scrollbars, otherwise doesn't.
 *  (Note: this will let the user know how much content is left,
 *   and be able to see it before it would automatically scroll into view.)
 *
 * "scrollbars_pause_ms" => int
 *  Defaults to 500. The ticker pauses its automatic scrolling when the user
 *  starts using the scrollbars. This is the number of milliseconds to wait
 *  until resuming the automatic scrolling.
 *
 * "anim_ms" => int
 *  Defaults to 100. This is the number of milliseconds between calls to
 *  autoScroll.
 *
 * "initial_scroll_mode" => string
 *  Defaults to 'auto'. This is the mode that scrolling starts out in.
 *  Possible values are 'auto' and 'paused'.
 *
 * "ease" => string
 *  Optional. If set, specifies the name of the ease function
 */
function Q_ticker_tool($options = array())
{
    $defaults = array('vertical' => true, 'speed' => 1, 'pause_ms' => 2000, 'scrollbars' => true, 'scrollbars_pause_ms' => 500, 'anim_ms' => 100);
    $fields2 = array_merge($defaults, $options);
    if (!isset($fields2['pause_ms_min'])) {
        $fields2['pause_ms_min'] = $fields2['pause_ms'];
    }
    if (!isset($fields2['content'])) {
        $li_array = array();
        for ($i = 0; $i < 100; ++$i) {
            $li_array[] = '<li><div style="background-color:#' . dechex(rand(0, 16)) . dechex(rand(0, 16)) . dechex(rand(0, 16)) . dechex(rand(0, 16)) . dechex(rand(0, 16)) . dechex(rand(0, 16)) . '">Missing $content parameter. This is just example #' . $i . '</div></li>';
        }
        $default_content = implode("\n", $li_array);
        if ($fields2['vertical']) {
            $fields2['content'] = "<ul class='error'>{$default_content}</ul>";
        } else {
            $fields2['content'] = "<ul class='error'>{$default_content}</ul>";
        }
    }
    Q_Response::addStylesheet('plugins/Q/css/ticker.css');
    Q_Response::addScript('plugins/Q/js/tools/ticker.js');
    Q_Response::setToolOptions($fields2);
    $direction_class = $fields2['vertical'] ? 'vertical' : 'horizontal';
    $scrollbars_class = $fields2['scrollbars'] ? 'scrollbars' : '';
    return Q_Html::tag('div', array('class' => "Q_ticker {$direction_class} {$scrollbars_class}"), $fields2['content']);
}

/**
 * Tool for admins to edit the url, title, keywords, description of the current page
 * @class Websites seo
 * @constructor
 * @param {Object} [$options] Options for the tool
 * @param {String} [$options.skipIfNotAuthorized=true] Whether to skip rendering the contents of the tool if the logged-in user is not authorized to edit the SEO information for this page.
 */
function Websites_seo_tool($options)
{
    $skipIfNotAuthorized = Q::ifset($options, 'skipIfNotAuthorized', true);
    if ($skipIfNotAuthorized) {
        $websitesUserId = Users::communityId();
        $sha1 = sha1(Q_Dispatcher::uri());
        $seoStreamName = "Websites/seo/{$sha1}";
        $stream = Streams::fetchOne(null, $websitesUserId, $seoStreamName);
        $user = Users::loggedInUser();
        if (!$user or $stream and !$stream->testWriteLevel('suggest')) {
            $options['skip'] = true;
        }
        if (!$stream and !Streams::isAuthorizedToCreate($user->id, $websitesUserId, 'Websites/seo')) {
            $options['skip'] = true;
        }
    }
    unset($options['skipIfNotAuthorized']);
    Q_Response::addStylesheet('plugins/Websites/css/Websites.css');
    Q_Response::addScript("plugins/Websites/js/Websites.js");
    Q_Response::setToolOptions($options);
    $user = Users::loggedInUser(false, false);
    $userId = $user ? $user->id : "";
    $communityId = Users::communityId();
    $sha1 = sha1(Q_Dispatcher::uri());
    $seoStreamName = "Websites/seo/{$sha1}";
    $streams = Streams::fetch($userId, $communityId, array("Websites/header", "Websites/title", "Websites/slogan", $seoStreamName));
    foreach ($streams as $name => $s) {
        if ($s) {
            $s->addPreloaded($userId);
        }
    }
}

/**
 * This tool implements expandable containers that work on most modern browsers,
 * including ones on touchscreens.
 * @class Q expandable
 * @constructor
 * @param {array} $options Options for the tool
 * @param {string} $options.title Required. The title for the expandable.
 * @param {string} $options.content The content. Required unless you pass "items" instead.
 * @param {array} [$options.items] An array of strings to wrap in <span> elements and render in the content
 * @param {string} [$options.class] If you use "items", optionally specify the class of the container elements for each item
 * @param {integer} [$options.title] A number, if any, to display when collapsed
 * @param {boolean} [$options.autoCollapseSiblings]  Whether, when expanding an expandable, its siblings should be automatically collapsed.
 */
function Q_expandable_tool($options)
{
    if (isset($options['items'])) {
        $classString = isset($options['class']) ? "class='{$options['class']}'" : '';
        $lines = array();
        foreach ($options['items'] as $key => $value) {
            $lines[] = "<span {$classString}>{$key}</span>";
        }
        $between = Q::ifset($options, 'between', '');
        $options['content'] = implode($between, $lines);
    }
    foreach (array('title', 'content') as $field) {
        if (!isset($options[$field])) {
            throw new Q_Exception_RequiredField(compact('field'));
        }
    }
    Q_Response::addScript('plugins/Q/js/tools/expandable.js');
    Q_Response::addStylesheet('plugins/Q/css/expandable.css');
    $count = Q::ifset($options, 'count', '');
    $style = empty($options['expanded']) ? '' : 'style="display:block"';
    $h2 = "<h2>\n\t<span class='Q_expandable_count'>{$count}</span>\n\t{$options['title']}\n</h2>";
    $div = "<div class='Q_expandable_container' {$style}><div class='Q_expandable_content'>\n\t{$options['content']}\n</div></div>";
    Q_Response::setToolOptions($options);
    return $h2 . $div;
}

/**
 * Renders chat tool.
 * @class Streams chat
 * @constructor
 * @param {array} $options Options for the tool
 * @param {string} $options.publisherId Publisher id of the stream to get messsages from.
 * @param {string} $options.streamName Required. Name of the stream to get messsages from.
 * @param {string} [$options.loadMore] May have one these values: 'scroll', 'click' or 'pull' which indicates what kind of algorithm will be used for loading new messages. 'scroll' means that new messages will be loaded when scrollbar of the chat cointainer reaches the top (for desktop) or whole document scrollbar reaches the top (for android). 'click' will show label with 'Click to see earlier messages' and when user clicks it, new messages will be loaded. Finally, 'pull' implements 'pull-to-refresh' behavior used in many modern applications today when new messages loaded by rubber-scrolling the container by more amount than it actually begins. Defaults to 'scroll' for desktop and Android devices and 'pull' for iOS devices.
*/
function Streams_chat_tool($options)
{
    $user = Users::loggedInUser();
    $userId = $user ? $user->id : '';
    /*
    $defaults = array(
    	'loadMore'         => (Q_Request::isTouchscreen() && Q_Request::platform() != 'android') ? 'click' : 'scroll',
    	'messagesToLoad'   => 5,
    	'messageMaxHeight' => 200
    );
    $options = array_merge($defaults, $options);
    */
    extract($options);
    if (!isset($publisherId)) {
        $publisherId = Streams::requestedPublisherId(true);
    }
    if (!isset($streamName)) {
        $streamName = Streams::requestedName();
    }
    $stream = Streams::fetchOne($userId, $publisherId, $streamName);
    if (!$stream) {
        throw new Q_Exception_MissingRow(array('table' => 'stream', 'criteria' => compact('publisherId', 'streamName')));
    }
    $options['userId'] = $userId;
    if (!isset($options['notLoggedIn'])) {
        $options['notLoggedIn'] = 'You are not logged in';
    }
    if (!isset($options['notAuthorized'])) {
        $options['notAuthorized'] = 'You are not authorized';
    }
    Q_Response::setToolOptions($options);
}

/**
 * This tool generates an HTML article viewer that lets authorized users edit the article.
 * @class Websites article
 * @constructor
 * @param {Object} [$options] parameters for the tool
 *   @param {String} $options.publisherId The article publisher's user id
 *   @param {String} $options.streamName The article's stream name
 *   @param {String} $options.stream The article's stream, if it is already fetched
 *   @param {String} [$options.html=array()] Any additional for the Streams/html editor
 *   @param {String} [$options.getintouch=array()] Additional options for the Users/getintouch tool, in case it's rendered
 */
function Websites_article_tool($options)
{
    $publisherId = $options['publisherId'];
    $streamName = $options['streamName'];
    $article = Q::ifset($options, 'stream', Streams::fetchOne(null, $publisherId, $streamName));
    if (!$article) {
        throw new Q_Exception_MissingRow(array('table' => 'article', 'criteria' => $streamName));
    }
    $getintouch = array_merge(array('user' => $article->userId, 'email' => true, 'sms' => true, 'call' => true, 'between' => "", 'emailSubject' => 'Reaching out from your website', 'class' => 'Q_button Q_clickable'), Q::ifset($options, 'getintouch', array()));
    $canView = $article->testReadLevel('content');
    $canEdit = $article->testWriteLevel('edit');
    if ($article->getintouch) {
        if (is_array($git = json_decode($article->getintouch, true))) {
            $getintouch = array_merge($getintouch, $git);
        }
    }
    $getintouch['class'] = 'Q_button';
    if (!$canView) {
        throw new Users_Exception_NotAuthorized();
    }
    $html = Q::ifset($options, 'html', array());
    $article->addPreloaded();
    Q_Response::addStylesheet('plugins/Websites/css/Websites.css');
    Q_Response::addScript("plugins/Websites/js/Websites.js");
    Q_Response::setToolOptions($options);
    return Q::view("Websites/tool/article.php", compact('article', 'getintouch', 'canEdit', 'canView', 'html'));
}

/**
 * This tool renders all user sessions opened.
 *
 * @param {array} $options An associative array of parameters, containing:
 * @param {string} [$options.userId]
 *   The user's id. Defaults to id of the logged-in user, if any.
 * @param {bool} [$options.editable=true]
 *   Whether user can delete sessions
 * @param {bool} [$options.devices=true]
 *   Whether to show devices info
 */
function Users_sessions_tool($options)
{
    $options = array_merge(array('editable' => true, 'devices' => true), $options);
    if (empty($options['userId'])) {
        $options['userId'] = Users::loggedInUser(true)->id;
    }
    Q_Response::addStylesheet('plugins/Users/css/tools/sessions.css');
    Q_Response::setToolOptions($options);
    $sessions = Users_Session::select("us.*, ud.deviceId, ud.platform, ud.version, ud.formFactor", "us")->join(Users_Device::table() . ' ud', array('us.userId' => 'ud.userId', 'us.id' => 'ud.sessionId'), "LEFT")->where(array('us.userId' => $options['userId']))->fetchDbRows();
    $noDevicesClass = $options['devices'] ? '' : "Users_sessions_noDevices";
    $html = "<table class='Users_sessions_container {$noDevicesClass}'><tr><th>Session Id</th><th class='Users_sessions_devicesData'>Platform</th><th class='Users_sessions_devicesData'>Version</th><th>Last Updated</th>";
    if ($options["editable"]) {
        $html .= '<th class="Users_sessions_actions"></th>';
    }
    $html .= '</tr>';
    foreach ($sessions as $session) {
        $updatedTime = date("M j, Y g:i A", strtotime($session->updatedTime));
        $html .= "<tr><td class='Users_sessions_sessionId'>{$session->id}</td>" . "<td class='Users_sessions_devicesData'>{$session->platform}</td>" . "<td class='Users_sessions_devicesData'>{$session->version}</td>" . "<td>{$updatedTime}</td>";
        if ($options["editable"]) {
            $html .= "<td class='Users_sessions_actions'><button name='delete'>Delete</button></td>";
        }
        $html .= '</tr>';
    }
    $html .= "</table>";
    return $html;
}

/**
 * Standard tool for starting or managing subscriptions.
 * @class Assets subscription
 * @constructor
 * @param {array} $options Override various options for this tool
 *  @param {string} $options.payments can be "authnet" or "stripe"
 *  @param {string} $options.planStreamName the name of the subscription plan's stream
 *  @param {string} [$options.publisherId=Q.Users.communityId] the publisher of the subscription plan's stream
 *  @param {string} [$options.subscribeButton] Can override the title of the subscribe button
 *  @param {array} [$options=array()] Any additional options
 *  @param {string} [$options.token=null] required unless the user is an existing customer
 */
function Assets_subscription_tool($options)
{
    if (empty($options['payments'])) {
        throw new Q_Exception_RequiredField(array('field' => 'payments'), 'payments');
    }
    $payments = ucfirst($options['payments']);
    $lcpayments = strtolower($payments);
    $currency = strtolower(Q::ifset($options, 'currency', 'usd'));
    if ($payments === 'Authnet' and $currency !== 'usd') {
        throw new Q_Exception("Authnet doesn't support currencies other than USD", 'currency');
    }
    $className = "Assets_Payments_{$payments}";
    switch ($payments) {
        case 'Authnet':
            $adapter = new $className($options);
            $token = $options['token'] = $adapter->authToken();
            $testing = $options['testing'] = Q_Config::expect('Assets', 'payments', $lcpayments, 'testing');
            $action = $options['action'] = $testing ? "https://test.authorize.net/profile/manage" : "https://secure.authorize.net/profile/manage";
            break;
        case 'Stripe':
            $publishableKey = Q_Config::expect('Assets', 'payments', 'stripe', 'publishableKey');
            break;
    }
    $titles = array('Authnet' => 'Authorize.net', 'Stripe' => 'Stripe');
    $subscribeButton = Q::ifset($options, 'subscribeButton', "Subscribe with " . $titles[$payments]);
    Q_Response::setToolOptions($options);
    return Q::view("Assets/tool/subscription/{$payments}.php", compact('token', 'publishableKey', 'action', 'paymentButton', 'subscribeButton', 'planStreamName'));
}

/**
 * This tool renders a user avatar
 *
 * @param {array} $options An associative array of parameters, containing:
 * @param {boolean} [$options.userId]
 *   "userId" => The user's id. Defaults to id of the logged-in user, if any.
 * @param {boolean} [$options.icon]
 *   "icon" => Optional. Render icon before the username.
 * @param {boolean} [$options.iconAttributes]
 *   "iconAttributes" => Optional. Array of attributes to render for the icon.
 * @param {boolean} [$options.editable]
 *   "editable" => Optional. Whether to provide an interface for editing the user's info. Can be array containing "icon", "name".
 * @param {array} [$options.inplaces] Additional fields to pass to the child Streams/inplace tools, if any
 * @param {boolean} [$options.renderOnClient]
 *    If true, only the html container is rendered, so the client will do the rest.
 */
function Users_avatar_tool($options)
{
    $defaults = array('icon' => false, 'editable' => false);
    $options = array_merge($defaults, $options);
    if (empty($options['userId'])) {
        $user = Users::loggedInUser();
        $options['userId'] = $user->id;
    } else {
        $user = Users_User::fetch($options['userId']);
    }
    Q_Response::addStylesheet('plugins/Q/css/Q.css');
    Q_Response::setToolOptions($options);
    if (!empty($options['renderOnClient'])) {
        return '';
    }
    if (!$user) {
        return '';
    }
    $user->addPreloaded();
    $p = $options;
    $p['userId'] = $user->id;
    Q_Response::setToolOptions($p);
    $result = '';
    $icon = $options['icon'];
    if ($icon) {
        if ($icon === true) {
            $icon = Q_Config::get('Users', 'icon', 'defaultSize', 40);
        }
        $attributes = isset($options['iconAttributes']) ? $options['iconAttributes'] : array();
        $attributes['class'] = isset($attributes['class']) ? $attributes['class'] . ' Users_avatar_icon' : 'Users_avatar_icon';
        $result .= Q_Html::img($user->iconUrl($icon), 'user icon', $attributes);
    }
    $result .= '<span class="Users_avatar_name">' . $user->username . '</span>';
    return $result;
}

/**
 * Renders a photo selector tool
 * @param $options
 *   An associative array of parameters, which can include:
 * @param {Object} [$options] this object contains function parameters
 *   @param {Q.Event} $options.onSelect Required string naming the callback to be called when the user selects a photo.
 *   @param {Q.Event} [$options.beforePhotos] Triggered when photos are about to be rendered.
 *   @param {Q.Event} [$options.onPhotos] Triggered when photos have been rendered.
 *   @param {String} [$options.uid='me'] Optional. The uid of the user on the provider whose photos should be shown. Facebook only allows 'me' or a page id as a value.
 *   @param {String} [$options.fetchBy='album'] The tool supports different algoriths for fetching photos. Can be either by 'album' or 'tags'. Maybe more will be added later.
 *   @param {String} [$options.preprocessAlbums] Optional function to process the albums array before presenting it in the select. Receives a reference to the albums array as the first parameter, and a callback to call when it's done as the second.
 *   @param {String} [$options.preprocessPhotos] Optional function to process the photos array before presenting it in the select. Receives a reference to the albums array as the first parameter, and a callback to call when it's done as the second.
 *   @param {Q.Event} [$options.onLoad] Q.Event, callback or callback string name which is called when bunch of photos has been loaded.
 *   @param {Q.Event} [$options.onError] Q.Event, callback or callback string which will be called for each image that is unable to load. Image DOM element will be passed as first argument.
 *   @param {String} [$options.provider='facebook'] Has to be "facebook" for now.
 *   @param {String} [$options.prompt=false]
 *   Specifies type of prompt if user is not logged in or didn't give required permission for the tool.
 *   Can be either 'button', 'dialog' or null|false. 
 *   In first case just shows simple button which opens facebook login popup.
 *   In second case shows Users.facebookDialog prompting user to login.
 *   In third case will not show any prompt and will just hide the tool.
 *   @param {String} [$options.promptTitle]  Used only when 'prompt' equals 'dialog' - will be title of the dialog.
 *   @param {String} [$options.promptText]  Used either for button caption when 'prompt' equals 'button' or dialog text when 'prompt' equals 'dialog'.
 *   @param {Boolean} [$options.oneLine]  If true, all the images are shown in a large horizontally scrolling line.
 * @return {void}
 */
function Streams_photoSelector_tool($options)
{
    Q_Response::addScript('plugins/Streams/js/Streams.js');
    Q_Response::addStylesheet('plugins/Streams/css/Streams.css');
    Q_Response::setToolOptions($options);
    return '';
}

/**
 * This tool renders a user avatar
 *
 * @param {array} $options An associative array of parameters, containing:
 * @param {string} [$options.userId]
 *   The user's id. Defaults to id of the logged-in user, if any.
 *   Can be '' for a blank-looking avatar.
 * @param {boolean} [options.short]
 *   Optional. Renders the short version of the display name.
 * @param {boolean|integer} [options.icon=false]
 *   Optional. Pass the size in pixels of the (square) icon to render
 *   before the username. Or pass true to render the default size.
 * @param {array} [options.iconAttributes]
 *   Optional. Array of attributes to render for the icon.
 * @param {boolean|array} [options.editable=false]
 *   Optional. Whether to provide an interface for editing the user's info. Can be array containing one or more of "icon", "name".
 * @param {boolean} [$options.show] The parts of the name to show. Can have the letters "f", "l", "u" in any order.
 * @param {boolean} [options.cacheBust=null]
 *   Number of milliseconds to use for Q_Uri::cacheBust for combating unintended caching on some environments.
 * @param {boolean} [options.renderOnClient]
 *   If true, only the html container is rendered, so the client will do the rest.
 */
function Users_avatar_tool($options)
{
    $defaults = array('icon' => false, 'short' => false, 'cacheBust' => null, 'editable' => false);
    $options = array_merge($defaults, $options);
    Q_Response::addStylesheet('plugins/Users/css/Users.css');
    $loggedInUser = Users::loggedInUser();
    $loggedInUserId = $loggedInUser ? $loggedInUser->id : "";
    if (empty($options['userId'])) {
        $options['userId'] = $loggedInUserId;
    }
    unset($options['iconAttributes']);
    if (empty($options['editable'])) {
        $options['editable'] = array();
    } else {
        if (is_string($options['editable'])) {
            $options['editable'] = array($options['editable']);
        } else {
            if ($options['editable'] === true) {
                $options['editable'] = array('icon', 'name');
            }
        }
    }
    Q_Response::setToolOptions($options);
    if (!empty($options['renderOnClient'])) {
        return '';
    }
    $avatar = Streams_Avatar::fetch($loggedInUserId, $options['userId']);
    if (!$avatar) {
        return '';
    }
    $result = '';
    if ($icon = $options['icon']) {
        if ($icon === true) {
            $icon = Q_Config::get('Users', 'icon', 'defaultSize', 40);
        }
        $attributes = isset($options['iconAttributes']) ? $options['iconAttributes'] : array();
        $class = "Users_avatar_icon Users_avatar_icon_{$icon}";
        $attributes['class'] = isset($attributes['class']) ? $attributes['class'] . ' ' . $class : $class;
        if (isset($options['cacheBust'])) {
            $attributes['cacheBust'] = $options['cacheBust'];
        }
        $result .= Q_Html::img(Users::iconUrl($avatar->icon, "{$icon}.png"), 'user icon', $attributes);
    }
    $o = $options['short'] ? array('short' => true) : array();
    $o['html'] = true;
    if (in_array('name', $options['editable'])) {
        $o['show'] = 'fl';
        $streams = Streams::fetch(null, $options['userId'], array('Streams/user/firstName', 'Streams/user/lastName', 'Streams/user/username'));
        foreach ($streams as $s) {
            $s->addPreloaded();
        }
    }
    if (!empty($options['show'])) {
        $o['show'] = $options['show'];
    }
    $displayName = $avatar->displayName($o, 'Someone');
    $result .= "<span class='Users_avatar_name'>{$displayName}</span>";
    return $result;
}

/**
 * Makes an infomation block for adding a bookmarklet on the browser's bookmarks bar
 * the way similar to how facebook does: https://www.facebook.com/share_options.php .
 * Main purpose of the tool is to present in cross-browser way how bookmarklet button will look, how bookmarklet will
 * look on browser panel and instructions how to add bookmarklet to that panel.
 * @param {array} $options An associative array of parameters, which can include:
 * @param {array} [$options.scripts] Array of one or more urls of javascript files (will be run through Q_Html::themedUrl) to be executed in order.
 * @param {string} [$options.content] Literal Javascript code to execute. If scripts option is provided, this code is executed after the scripts have been loaded.
 * @param {Object} [$options.skip] Object of {url: path.to.object} pairs to avoid loading script at the url if path.to.object is already defined. Typically names an object which has been defined by the loaded script.
 * @param {string} $options.title Required. Title for the button which will be added to user's browser bar.
 * @param {string} $options.usage Text which is appended to instructions, identifying purpose and usage of this bookmarklet.
 * @param {string} [$options.icon] Icon for the button which will be added to user's browser bar. Can contain placeholders supported by strftime() and also few special placeholders with specific functionality.
 * @return {string}
 */
function Q_bookmarklet_tool($options)
{
    $options = array_merge(array('icon' => null), $options);
    Q_Response::addScript('plugins/Q/js/tools/bookmarklet.js');
    Q_Response::addStylesheet('plugins/Q/css/bookmarklet.css');
    Q_Response::setToolOptions($options);
    return '';
}

/**
 * Renders a bunch of Stream/preview tools for streams related to the given stream.
 * Has options for adding new related streams, as well as sorting the relations, etc.
 * Also can integrate with Q/tabs tool to render tabs "related" to some category.
 * @class Streams related
 * @constructor
 * @param {array} $options options for the tool
 *   @param {string} [$options.publisherId] Either this or "stream" is required. Publisher id of the stream to which the others are related
 *   @param {string} [$options.streamName] Either this or "stream" is required. Name of the stream to which the others are related
 *   @param {string} [$options.tag="div"] The type of element to contain the preview tool for each related stream.
 *   @param {string} [$options.stream] You can pass a Streams_Stream object here instead of "publisherId" and "streamName"
 *   @param {string} [$options.relationType=""] The type of the relation.
 *   @param {boolean} [$options.isCategory=true] Whether to show the streams related TO this stream, or the ones it is related to.
 *   @param {array} [$options.relatedOptions] Can include options like 'limit', 'offset', 'ascending', 'min', 'max', 'prefix' and 'fields'
 *   @param {boolean} [$options.editable] Set to false to avoid showing even authorized users an interface to replace the image or text
 *   @param {array} [$options.creatable]  Optional pairs of {streamType: toolOptions}  to render Streams/preview tools create new related streams.
 *   The params typically include at least a "title" field which you can fill with values such as "New" or "New ..."
 *   @param {Function} [options.toolName] Optionally name a function that takes (streamType, options) and returns the name of the tool to render (and then activate) for that stream. That tool should reqire the "Streams/preview" tool, and work with it as documented in "Streams/preview".
 *   @param {boolean} [$options.realtime=false] Whether to refresh every time a relation is added, removed or updated by anyone
 *   @param {array} [$options.sortable] Options for "Q/sortable" jQuery plugin. Pass false here to disable sorting interface. If streamName is not a String, this interface is not shown.
 *   @param {string} [$options.tabs] Name of a cuntion for interacting with any parent "Q/tabs" tool. Format is function (previewTool, tabsTool) { return urlOrTabKey; }
 *   @param {array} [$options.updateOptions] Options for onUpdate such as duration of the animation, etc.
 *   @param {string} [$options.onUpdate] Name of a handler for event that receives parameters "data", "entering", "exiting", "updating"
 *   @param {string} [$options.onRefresh] Name of a handler for event that occurs when the tool is completely refreshed, the "this" is the tool
 */
function Streams_related_tool($options)
{
    if (!empty($options['stream'])) {
        $stream = $options['stream'];
        $options['publisherId'] = $stream->publisherId;
        $options['streamName'] = $stream->name;
    }
    Q_Response::setToolOptions($options);
}

/**
 * This tool generates an inline editor to edit the content or attribute of a stream.
 * @class Streams inplace
 * @constructor
 * @param {array} $options Options for the tool
 *  An associative array of parameters, containing:
 * @param {string} [$options.inplaceType='textarea'] The type of the fieldInput. Can be "textarea" or "text"
 * @param {array} [$options.convert] The characters to convert to HTML. Pass an array containing zero or more of "\n", " "
 * @param {Streams_Stream} $options.stream A Streams_Stream object
 * @param {string} [$options.field] Optional, name of an field to change instead of the content of the stream
 * @param {string} [$options.attribute] Optional, name of an attribute to change instead of any field.
 * @param {string} [$options.beforeSave] Reference to a callback to call after a successful save. This callback can cancel the save by returning false.
 * @param {string} [$options.onSave] Reference to a callback or event to run after a successful save.
 * @param {string} [$options.onCancel] Reference to a callback or event to run after cancel.
 * @param {array} [$options.inplace=array()] Additional fields to pass to the child Q/inplace tool, if any
 * @uses Q inplace
 */
function Streams_inplace_tool($options)
{
    if (empty($options['stream'])) {
        if (empty($options['publisherId']) or empty($options['streamName'])) {
            throw new Q_Exception_RequiredField(array('field' => 'stream'));
        }
        $publisherId = $options['publisherId'];
        $streamName = $options['streamName'];
        $stream = Streams::fetchOne(null, $publisherId, $streamName);
        if (!$stream) {
            throw new Q_Exception_MissingRow(array('table' => 'stream', 'criteria' => "publisherId={$publisherId}, name={$streamName}"));
        }
    } else {
        $stream = $options['stream'];
    }
    $inplaceType = Q::ifset($options, 'inplaceType', 'textarea');
    $inplace = array('action' => $stream->actionUrl(), 'method' => 'PUT', 'type' => $inplaceType);
    if (isset($options['inplace'])) {
        $inplace = array_merge($options['inplace'], $inplace);
    }
    $convert = Q::ifset($options, 'convert', array("\n"));
    $inplace['hidden']['convert'] = json_encode($convert);
    if (!empty($options['attribute'])) {
        $field = 'attributes[' . urlencode($options['attribute']) . ']';
        $content = $stream->get($options['attribute'], '');
        $maxlength = $stream->maxSize_attributes - strlen($stream->maxSize_attributes) - 10;
    } else {
        $field = !empty($options['field']) ? $options['field'] : 'content';
        $content = $stream->{$field};
        $maxlength = $stream->maxSizeExtended($field);
    }
    switch ($inplaceType) {
        case 'text':
            $inplace['fieldInput'] = Q_Html::input($field, $content, array('placeholder' => Q::ifset($input, 'placeholder', null), 'maxlength' => $maxlength));
            $inplace['staticHtml'] = Q_Html::text($content);
            break;
        case 'textarea':
            $inplace['fieldInput'] = Q_Html::textarea($field, 5, 80, array('placeholder' => Q::ifset($inplace, 'placeholder', null), 'maxlength' => $maxlength), $content);
            $inplace['staticHtml'] = Q_Html::text($content, $convert);
            break;
        default:
            return "inplaceType must be 'textarea' or 'text'";
    }
    if (!$stream->testWriteLevel('suggest')) {
        if (!isset($options['classes'])) {
            $options['classes'] = '';
        }
        Q_Response::setToolOptions(array('publisherId' => $stream->publisherId, 'streamName' => $stream->name));
        $staticClass = $options['inplaceType'] === 'textarea' ? 'Q_inplace_tool_blockstatic' : 'Q_inplace_tool_static';
        return "<span class='Q_inplace_tool_container {$options['classes']}' style='position: relative;'>" . "<div class='{$staticClass}'>{$inplace['staticHtml']}</div></span>";
    }
    $toolOptions = array('publisherId' => $stream->publisherId, 'streamName' => $stream->name, 'inplaceType' => $options['inplaceType']);
    Q::take($options, array('attribute', 'field', 'convert'), $toolOptions);
    $toolOptions['inplace'] = $inplace;
    Q_Response::setToolOptions($toolOptions);
    return Q::tool("Q/inplace", $inplace);
}