views.php

Go to the documentation of this file.

<?php
use Elgg\Exceptions\Http\PageNotFoundException;
use Elgg\Exceptions\InvalidArgumentException as ElggInvalidArgumentException;
use Elgg\Menu\Menu;
use Elgg\Menu\UnpreparedMenu;

function elgg_set_viewtype(string $viewtype = ''): bool {
    return _elgg_services()->views->setViewtype($viewtype);
}

function elgg_get_viewtype(): string {
    return _elgg_services()->views->getViewtype();
}

function elgg_register_viewtype_fallback(string $viewtype): void {
    _elgg_services()->views->registerViewtypeFallback($viewtype);
}

function elgg_register_ajax_view(string $view): void {
    _elgg_services()->ajax->registerView($view);
}

function elgg_unregister_ajax_view(string $view): void {
    _elgg_services()->ajax->unregisterView($view);
}

function elgg_view_exists(string $view, string $viewtype = '', bool $recurse = true): bool {
    return _elgg_services()->views->viewExists($view, $viewtype, $recurse);
}

function elgg_view(string $view, array $vars = [], string $viewtype = ''): string {
    return _elgg_services()->views->renderView($view, $vars, $viewtype);
}

function elgg_extend_view(string $view, string $view_extension, int $priority = 501): void {
    _elgg_services()->views->extendView($view, $view_extension, $priority);
}

function elgg_unextend_view(string $view, string $view_extension): bool {
    return _elgg_services()->views->unextendView($view, $view_extension);
}

function elgg_get_view_extensions(string $view): array {
    $list = _elgg_services()->views->getViewList($view);
    unset($list[500]);
    return $list;
}

function elgg_view_page(string $title, string|array $body, string $page_shell = 'default', array $vars = []): string {
    
    if (elgg_is_xhr() && get_input('_elgg_ajax_list')) {
        // requested by ajaxed pagination
        return is_array($body) ? (string) elgg_extract('content', $body) : $body;
    }
    
    if (is_array($body)) {
        $vars['entity'] = elgg_extract('entity', $body, elgg_extract('entity', $vars));

        $body['title'] = elgg_extract('title', $body, $title);
        $body = elgg_view_layout('default', $body);
    }
    
    $timer = _elgg_services()->timer;
    if (!$timer->hasEnded(['build page'])) {
        $timer->end(['build page']);
    }
    
    $timer->begin([__FUNCTION__]);

    $params = [];
    $params['identifier'] = _elgg_services()->request->getFirstUrlSegment();
    $params['segments'] = _elgg_services()->request->getUrlSegments();
    array_shift($params['segments']);
    $page_shell = elgg_trigger_event_results('shell', 'page', $params, $page_shell);

    $system_messages = _elgg_services()->system_messages;

    $messages = null;
    if ($system_messages->count()) {
        $messages = $system_messages->dumpRegister();

        if (isset($messages['error'])) {
            // always make sure error is the first type
            $errors = [
                'error' => $messages['error']
            ];

            unset($messages['error']);
            $messages = array_merge($errors, $messages);
        }
    }

    $vars['title'] = $title;
    $vars['body'] = $body;
    $vars['sysmessages'] = $messages;
    $vars['page_shell'] = $page_shell;

    $vars['head'] = elgg_trigger_event_results('head', 'page', $vars, ['metas' => [], 'links' => []]);

    $vars = elgg_trigger_event_results('output:before', 'page', [], $vars);

    $output = elgg_view("page/{$page_shell}", $vars);

    // Allow plugins to modify the output
    $output = elgg_trigger_event_results('output', 'page', $vars, $output);

    $timer->end([__FUNCTION__]);
    return $output;
}

function elgg_view_resource(string $name, array $vars = []): string {
    $view = "resources/{$name}";

    if (elgg_view_exists($view)) {
        return _elgg_services()->views->renderView($view, $vars);
    }

    if (elgg_get_viewtype() !== 'default' && elgg_view_exists($view, 'default')) {
        return _elgg_services()->views->renderView($view, $vars, 'default');
    }

    _elgg_services()->logger->error("The view {$view} is missing.");

    // only works for default viewtype
    throw new PageNotFoundException();
}

function elgg_view_layout(string $layout_name, array $vars = []): string {
    $timer = _elgg_services()->timer;
    if (!$timer->hasEnded(['build page'])) {
        $timer->end(['build page']);
    }
    
    $timer->begin([__FUNCTION__]);
    
    $vars['identifier'] = _elgg_services()->request->getFirstUrlSegment();
    $vars['segments'] = _elgg_services()->request->getUrlSegments();
    array_shift($vars['segments']);

    $layout_name = elgg_trigger_event_results('layout', 'page', $vars, $layout_name);

    $vars['layout'] = $layout_name;

    $layout_views = [
        "page/layouts/{$layout_name}",
        'page/layouts/default',
    ];

    $output = '';
    foreach ($layout_views as $layout_view) {
        if (elgg_view_exists($layout_view)) {
            $output = elgg_view($layout_view, $vars);
            break;
        }
    }

    $timer->end([__FUNCTION__]);
    return $output;
}

function elgg_view_menu($menu, array $vars = []): string {

    $menu_view = (string) elgg_extract('menu_view', $vars);
    unset($vars['menu_view']);

    if (is_string($menu)) {
        $menu = _elgg_services()->menus->getMenu($menu, $vars);
    } elseif ($menu instanceof UnpreparedMenu) {
        $menu = _elgg_services()->menus->prepareMenu($menu);
    }

    if (!$menu instanceof Menu) {
        throw new ElggInvalidArgumentException('$menu must be a menu name, a Menu, or UnpreparedMenu');
    }

    $name = $menu->getName();
    $params = $menu->getParams();

    $views = [
        $menu_view,
        "navigation/menu/{$name}",
        'navigation/menu/default',
    ];

    foreach ($views as $view) {
        if (elgg_view_exists($view)) {
            return elgg_view($view, $params);
        }
    }
    
    return '';
}

function elgg_view_entity(\ElggEntity $entity, array $vars = []): string {

    $defaults = [
        'full_view' => true,
    ];

    $vars = array_merge($defaults, $vars);
    
    if (elgg_extract('register_rss_link', $vars, elgg_extract('full_view', $vars))) {
        elgg_register_rss_link();
    }

    $vars['entity'] = $entity;

    $entity_type = $entity->getType();
    $entity_subtype = $entity->getSubtype();

    $entity_views = [
        (string) elgg_extract('item_view', $vars, ''),
        "{$entity_type}/{$entity_subtype}",
        "{$entity_type}/default",
    ];

    $contents = '';
    foreach ($entity_views as $view) {
        if (elgg_view_exists($view)) {
            $contents = elgg_view($view, $vars);
            break;
        }
    }

    return $contents;
}

function elgg_view_entity_icon(\ElggEntity $entity, string $size = 'medium', array $vars = []): string {

    $vars['entity'] = $entity;
    $vars['size'] = $size;

    $entity_type = $entity->getType();

    $subtype = $entity->getSubtype();

    $contents = '';
    if (elgg_view_exists("icon/{$entity_type}/{$subtype}")) {
        $contents = elgg_view("icon/{$entity_type}/{$subtype}", $vars);
    }
    
    if (empty($contents) && elgg_view_exists("icon/{$entity_type}/default")) {
        $contents = elgg_view("icon/{$entity_type}/default", $vars);
    }
    
    if (empty($contents)) {
        $contents = elgg_view('icon/default', $vars);
    }

    return $contents;
}

function elgg_view_annotation(\ElggAnnotation $annotation, array $vars = []): string {
    $defaults = [
        'full_view' => true,
    ];

    $vars = array_merge($defaults, $vars);
    $vars['annotation'] = $annotation;

    $name = $annotation->name;
    if (empty($name)) {
        return '';
    }

    $annotation_views = [
        (string) elgg_extract('item_view', $vars, ''),
        "annotation/{$name}",
        'annotation/default',
    ];

    foreach ($annotation_views as $view) {
        if (elgg_view_exists($view)) {
            return elgg_view($view, $vars);
        }
    }

    return '';
}

function elgg_view_entity_list(array $entities, array $vars = []): string {
    $offset = (int) get_input('offset', 0);

    // list type can be passed as request parameter
    $list_type = get_input('list_type', 'list');

    $defaults = [
        'items' => $entities,
        'list_class' => 'elgg-list-entity',
        'full_view' => true,
        'pagination' => true,
        'list_type' => $list_type,
        'offset' => $offset,
        'limit' => null,
    ];

    $vars = array_merge($defaults, $vars);

    if (!$vars['limit'] && !$vars['offset']) {
        // no need for pagination if listing is unlimited
        $vars['pagination'] = false;
    }

    $view = "page/components/{$vars['list_type']}";
    if (!elgg_view_exists($view)) {
        $view = 'page/components/list';
    }
    
    return elgg_view($view, $vars);
}

function elgg_view_annotation_list(array $annotations, array $vars = []): string {
    // list type can be passed as request parameter
    $list_type = get_input('list_type', 'list');

    $defaults = [
        'items' => $annotations,
        'offset' => null,
        'limit' => null,
        'list_class' => 'elgg-list-annotation',
        'full_view' => true,
        'list_type' => $list_type,
        'offset_key' => 'annoff',
    ];

    $vars = array_merge($defaults, $vars);

    if (!$vars['limit'] && !$vars['offset']) {
        // no need for pagination if listing is unlimited
        $vars['pagination'] = false;
    }

    $view = "page/components/{$vars['list_type']}";
    if (!elgg_view_exists($view)) {
        $view = 'page/components/list';
    }
    
    return elgg_view($view, $vars);
}

function elgg_view_relationship_list(array $relationships, array $vars = []): string {
    // list type can be passed as request parameter
    $list_type = get_input('list_type', 'list');

    $defaults = [
        'items' => $relationships,
        'offset' => null,
        'limit' => null,
        'list_class' => 'elgg-list-relationship',
        'full_view' => false,
        'list_type' => $list_type,
        'offset_key' => 'reloff',
    ];
    
    $vars = array_merge($defaults, $vars);
    
    if (!$vars['limit'] && !$vars['offset']) {
        // no need for pagination if listing is unlimited
        $vars['pagination'] = false;
    }
    
    $view = "page/components/{$vars['list_type']}";
    if (!elgg_view_exists($view)) {
        $view = 'page/components/list';
    }
    
    return elgg_view($view, $vars);
}

function elgg_view_relationship(\ElggRelationship $relationship, array $vars = []): string {
    $defaults = [
        'full_view' => true,
    ];
    
    $vars = array_merge($defaults, $vars);
    $vars['relationship'] = $relationship;
    
    $name = $relationship->relationship;
    if (empty($name)) {
        return '';
    }
    
    $relationship_views = [
        (string) elgg_extract('item_view', $vars, ''),
        "relationship/{$name}",
        'relationship/default',
    ];
    
    foreach ($relationship_views as $view) {
        if (elgg_view_exists($view)) {
            return elgg_view($view, $vars);
        }
    }
    
    return '';
}

function elgg_view_title(string $title, array $vars = []): string {
    $vars['title'] = $title;

    return elgg_view('page/elements/title', $vars);
}

function elgg_view_friendly_time($time, $time_updated = null): string {
    $view = 'output/friendlytime';
    $vars = [
        'time' => $time,
        'time_updated' => $time_updated,
    ];
    $viewtype = elgg_view_exists($view) ? '' : 'default';

    return _elgg_view_under_viewtype($view, $vars, $viewtype);
}

function elgg_view_comments(\ElggEntity $entity, bool $add_comment = true, array $vars = []): string {
    if (!$entity->hasCapability('commentable')) {
        return '';
    }

    $vars['entity'] = $entity;
    $vars['show_add_form'] = $add_comment;
    $vars['class'] = elgg_extract('class', $vars, "{$entity->getSubtype()}-comments");
    
    $default_id = 'comments';
    if ($entity instanceof \ElggComment) {
        $default_id .= "-{$entity->guid}";
    }
    
    $vars['id'] = elgg_extract('id', $vars, $default_id);

    $output = elgg_trigger_event_results('comments', $entity->getType(), $vars, false);
    if (is_string($output)) {
        return $output;
    }
    
    return elgg_view('page/elements/comments', $vars);
}

function elgg_view_image_block(string $image, string $body, array $vars = []): string {
    $vars['image'] = $image;
    $vars['body'] = $body;
    return elgg_view('page/components/image_block', $vars);
}

function elgg_view_module(string $type, string $title, string $body, array $vars = []): string {
    $vars['type'] = $type;
    $vars['title'] = $title;
    $vars['body'] = $body;
    return elgg_view('page/components/module', $vars);
}

function elgg_view_message(string $type, string $body, array $vars = []): string {
    $vars['type'] = $type;
    $vars['body'] = $body;
    return elgg_view('page/components/message', $vars);
}

function elgg_view_river_item(\ElggRiverItem $item, array $vars = []): string {

    // checking default viewtype since some viewtypes do not have unique views per item (rss)
    $view = $item->getView();

    $subject = $item->getSubjectEntity();
    $object = $item->getObjectEntity();
    if (!$subject || !$object) {
        // subject is disabled or subject/object deleted
        return '';
    }
    
    if (elgg_extract('register_rss_link', $vars)) {
        elgg_register_rss_link();
    }

    $vars['item'] = $item;

    // create river view logic
    $type = $object->getType();
    $subtype = $object->getSubtype();
    $action = $item->action_type;

    $river_views = [
        elgg_extract('item_view', $vars, ''),
        'river/item', // important for other viewtypes, e.g. "rss"
        $view,
        "river/{$type}/{$subtype}/{$action}",
        "river/{$type}/{$subtype}/default",
        "river/{$type}/{$action}",
        "river/{$type}/default",
        'river/elements/layout',
    ];

    foreach ($river_views as $view) {
        if (elgg_view_exists($view)) {
            return elgg_view($view, $vars);
        }
    }

    return '';
}

function elgg_view_form(string $action, array $form_vars = [], array $body_vars = []): string {
    return _elgg_services()->forms->render($action, $form_vars, $body_vars);
}

function elgg_set_form_footer(string $footer = ''): void {
    _elgg_services()->forms->setFooter($footer);
}

function elgg_get_form_footer(): string {
    return _elgg_services()->forms->getFooter();
}

function _elgg_split_vars(array $vars = [], array $prefixes = null): array {

    if (!isset($prefixes)) {
        $prefixes = ['#'];
    }

    $return = [];
    $default_section = ''; // something weird with PHP 8.1 compatibility
    
    foreach ($vars as $key => $value) {
        foreach ($prefixes as $prefix) {
            if (substr($key, 0, 1) === $prefix) {
                $key = substr($key, 1);
                $return[$prefix][$key] = $value;
                break;
            } else {
                $return[$default_section][$key] = $value;
            }
        }
    }

    return $return;
}

function elgg_view_field(array $params = []): string {

    if (!empty($params['#html'])) {
        return $params['#html'];
    }
    
    if (empty($params['#type'])) {
        _elgg_services()->logger->error(__FUNCTION__ . '(): $params["#type"] is required.');
        return '';
    }

    $input_type = $params['#type'];
    if (!elgg_view_exists("input/$input_type")) {
        return '';
    }

    $hidden_types = ['hidden', 'securitytoken'];
    if (in_array($input_type, $hidden_types)) {
        $params = _elgg_split_vars($params);
        return elgg_view("input/{$input_type}", $params['']);
    }

    if (empty($params['id'])) {
        $params['id'] = 'elgg-field-' . base_convert(mt_rand(), 10, 36);
    }

    $make_special_checkbox_label = false;
    if ($input_type == 'checkbox' && (isset($params['label']) || isset($params['#label']))) {
        if (isset($params['#label']) && isset($params['label'])) {
            $params['label_tag'] = 'div';
        } else {
            $label = elgg_extract('label', $params);
            $label = elgg_extract('#label', $params, $label);

            $params['#label'] = $label;
            unset($params['label']);

            // Single checkbox input view gets special treatment
            // We don't want the field label to appear a checkbox without a label
            $make_special_checkbox_label = true;
        }
    }

    // Need to set defaults to prevent input keys with same name ending up in element vars if not provided
    $defaults = [
        '#class' => ELGG_ENTITIES_ANY_VALUE,
        '#help' => ELGG_ENTITIES_ANY_VALUE,
        '#label' => ELGG_ENTITIES_ANY_VALUE,
        '#view' => ELGG_ENTITIES_ANY_VALUE,
    ];
    $params = array_merge($defaults, $params);
    
    // first pass non-hash keys into both
    $split_params = _elgg_split_vars($params);

    // $vars passed to input/$input_name
    $input_vars = $split_params[''];
    
    // $vars passed to label, help and field wrapper views
    $element_vars = array_merge($split_params[''], $split_params['#']);

    // field input view needs this
    $input_vars['input_type'] = $input_type;

    // field views get more data
    $element_vars['input_type'] = $input_type;

    // correct the label vars
    $label_vars = $element_vars;
    if (in_array($input_type, ['checkboxes', 'radio'])) {
        // the field label shouldn't point to the wrapping <ul> as that isn't a valid target for a <label>
        unset($label_vars['id']);
    }

    $element_vars['label'] = elgg_view('elements/forms/label', $label_vars);

    // wrap if present
    $element_vars['help'] = elgg_view('elements/forms/help', $element_vars);

    if ($make_special_checkbox_label) {
        $input_vars['label'] = $element_vars['label'];
        $input_vars['label_tag'] = 'div';
        unset($element_vars['label']);
    }
    
    $element_vars['input'] = elgg_view('elements/forms/input', $input_vars);

    return elgg_view('elements/forms/field', $element_vars);
}

function elgg_view_tagcloud(array $options = []): string {
    return elgg_view('output/tagcloud', [
        'value' => elgg_get_tags($options),
        'type' => elgg_extract('type', $options, ''),
        'subtype' => elgg_extract('subtype', $options, ''),
    ]);
}

function elgg_view_list_item($item, array $vars = []): string {

    if ($item instanceof \ElggEntity) {
        return elgg_view_entity($item, $vars);
    } else if ($item instanceof \ElggAnnotation) {
        return elgg_view_annotation($item, $vars);
    } else if ($item instanceof \ElggRiverItem) {
        return elgg_view_river_item($item, $vars);
    } else if ($item instanceof ElggRelationship) {
        return elgg_view_relationship($item, $vars);
    }

    $view = (string) elgg_extract('item_view', $vars);
    if ($view && elgg_view_exists($view)) {
        $vars['item'] = $item;
        return elgg_view($view, $vars);
    }

    return '';
}

function elgg_view_icon(string $name, array $vars = []): string {
    $vars['class'] = elgg_extract_class($vars, "elgg-icon-{$name}");

    return elgg_view('output/icon', $vars);
}

function elgg_register_rss_link(): void {
    _elgg_services()->config->_elgg_autofeed = true;
}

function elgg_unregister_rss_link(): void {
    _elgg_services()->config->_elgg_autofeed = false;
}

function _elgg_has_rss_link(): bool {
    if (_elgg_services()->config->disable_rss) {
        return false;
    }

    return (bool) _elgg_services()->config->_elgg_autofeed;
}

function elgg_views_boot(): void {
    _elgg_services()->viewCacher->registerCoreViews();

    elgg_register_external_file('css', 'font-awesome', elgg_get_simplecache_url('font-awesome/css/all.min.css'));
    elgg_load_external_file('css', 'font-awesome');

    elgg_extend_view('elgg.css', 'lightbox/elgg-colorbox-theme/colorbox.css');
    elgg_extend_view('elgg.css', 'entity/edit/icon/crop.css');
    
    elgg_require_css('elgg');
    
    elgg_register_esm('cropperjs', elgg_get_simplecache_url('cropperjs/cropper.esm.js'));
    elgg_register_esm('jquery', elgg_get_simplecache_url('elgg/jquery.mjs'));
    elgg_register_esm('jquery-ui', elgg_get_simplecache_url('jquery-ui.js'));
    elgg_register_esm('jquery-cropper/jquery-cropper', elgg_get_simplecache_url('jquery-cropper/jquery-cropper.esm.js'));
    
    elgg_import_esm('elgg');
    elgg_import_esm('elgg/lightbox');
    elgg_import_esm('elgg/security');

    elgg_extend_view('jquery-ui.js', 'jquery.ui.touch-punch.js');
    elgg_extend_view('initialize_elgg.js', 'elgg/prevent_clicks.js', 1);

    elgg_register_ajax_view('languages.js');
}

function _elgg_get_js_page_data(array $params = []): array {
    $data = elgg_trigger_event_results('elgg.data', 'page', $params, []);
    if (!is_array($data)) {
        elgg_log('"elgg.data" Event handlers must return an array. Returned ' . gettype($data) . '.', 'ERROR');
        $data = [];
    }
    
    $message_delay = (int) elgg_get_config('message_delay');
    if ($message_delay < 1) {
        $message_delay = 6;
    }

    $elgg = [
        'config' => [
            'lastcache' => (int) _elgg_services()->config->lastcache,
            'viewtype' => elgg_get_viewtype(),
            'simplecache_enabled' => (int) elgg_is_simplecache_enabled(),
            'current_language' => elgg_get_current_language(),
            'language' => _elgg_services()->config->language ?: 'en',
            'wwwroot' => elgg_get_site_url(),
            'message_delay' => $message_delay * 1000,
        ],
        'release' => elgg_get_release(),
        'security' => [
            // refresh token 3 times during its lifetime (in microseconds 1000 * 1/3)
            'interval' => (int) _elgg_services()->csrf->getActionTokenTimeout() * 333,
            
            'token' => [
                '__elgg_ts' => $ts = _elgg_services()->csrf->getCurrentTime()->getTimestamp(),
                '__elgg_token' => _elgg_services()->csrf->generateActionToken($ts),
            ],
        ],
        'session' => [
            'user' => null,
            'token' => _elgg_services()->session->get('__elgg_session'),
        ],
        'data' => $data,
    ];

    $user = elgg_get_logged_in_user_entity();
    if ($user instanceof ElggUser) {
        $user_object = $user->toObject();
        $user_object->admin = $user->isAdmin();
        
        $elgg['user'] = (array) $user_object;
    }

    return $elgg;
}

function _elgg_view_under_viewtype(string $view, array $vars, string $viewtype): string {
    $current_view_type = null;
    if ($viewtype) {
        $current_view_type = elgg_get_viewtype();
        elgg_set_viewtype($viewtype);
    }

    $ret = elgg_view($view, $vars);

    if (isset($current_view_type)) {
        elgg_set_viewtype($current_view_type);
    }

    return $ret;
}

function elgg_view_url(string $href, string $text = null, array $options = []): string {
    $options['is_trusted'] = elgg_extract('is_trusted', $options, true);
    $options['href'] = $href;
    $options['text'] = $text;
    
    return elgg_view('output/url', $options);
}

function elgg_view_entity_url(\ElggEntity $entity, array $options = []): string {
    return elgg_view_url($entity->getURL(), $entity->getDisplayName(), $options);
}

function elgg_view_deprecated(string $view, array $vars, string $suggestion, string $version): string {
    return _elgg_services()->views->renderDeprecatedView($view, $vars, $suggestion, $version);
}