\QuickApps\ViewView

QuickApps View class.

Extends Cake's View class to adds some QuickAppsCMS's specific functionalities such as theme regions handling, objects rendering, and more.

Summary

Methods
Properties
Constants
__construct()
region()
render()
renderLayout()
trigger()
eventDispatcher()
triggered()
shortcodes()
stripShortcodes()
escapeShortcodes()
enableShortcodes()
disableShortcodes()
viewMode()
addViewMode()
viewModes()
onViewMode()
asViewMode()
$Block
No constants found
_getElementFileName()
_paths()
_getLayoutFileName()
_evaluate()
_setTitle()
_setDescription()
$_hasRendered
$_regions
N/A
No private methods found
No private properties found
N/A

Properties

$Block

$Block : \Block\View\Helper\BlockHelper

Type

\Block\View\Helper\BlockHelper

$_hasRendered

$_hasRendered : boolean

True when the view has been rendered.

Used to stop infinite loops when using render() method.

Type

boolean

$_regions

$_regions : array

Holds all region instances created for later access.

Type

array

Methods

__construct()

__construct(\Cake\Network\Request $request, \Cake\Network\Response $response, \Cake\Event\EventManager $eventManager, array $viewOptions)

{@inheritDoc}

The following helpers will be automatically loaded:

  • Url
  • Html
  • Form
  • Menu
  • jQuery

Parameters

\Cake\Network\Request $request
\Cake\Network\Response $response
\Cake\Event\EventManager $eventManager
array $viewOptions

region()

region(string $name, array $options, boolean $force) : \Block\View\Region

Defines a new theme region to be rendered.

Usage:

Merge left-sidebar and right-sidebar regions together, the resulting region limits the number of blocks it can holds to 3:

echo $this->region('left-sidebar')
    ->append($this->region('right-sidebar'))
    ->blockLimit(3);

Valid options are:

  • fixMissing: When creating a region that is not defined by the theme, it will try to fix it by adding it to theme's regions if this option is set to TRUE. Defaults to NULL which automatically enables when debug is enabled. This option will not work when using QuickAppsCMS's core themes. (NOTE: This option will alter theme's composer.json file).

  • theme: Name of the theme this regions belongs to. Defaults to auto- detect.

Parameters

string $name

Theme's region machine-name. e.g. left-sidebar

array $options

Additional options for region being created

boolean $force

Whether to skip reading from cache or not, defaults to false will get from cache if exists.

Returns

\Block\View\Region

Region object

render()

render( $view,  $layout)

{@inheritDoc}

Overrides Cake's view rendering method. Allows to "render" objects.

Example:

// $content, instance of: Content\Model\Entity\Content
$this->render($content);

// $block, instance of: Block\Model\Entity\Block
$this->render($block);

// $field, instance of: Field\Model\Entity\Field
$this->render($field);

When rendering objects the Render.<ClassName> event is automatically triggered. For example, when rendering a Content Entity the following event is triggered, and event handlers should provide a HTML representation of the given object, it basically works as the __toString() magic method:

$someContent = TableRegistry::get('Content.Contents')->get(1);
$this->render($someContent);
// triggers: Render.Content\Model\Entity\Content

It is not limited to Entity instances only, you can virtually define a Render for any class name.

You can pass an unlimited number of arguments to your Render as follow:

$this->render($someObject, $arg1, $arg2, ...., $argn);

Your Render event-handler may look as below:

public function renderMyObject(Event $event, $theObject, $arg1, $arg2, ..., $argn);

Parameters

$view
$layout

renderLayout()

renderLayout( $content,  $layout)

{@inheritDoc}

Parses shortcodes.

Parameters

$content
$layout

trigger()

trigger(array|string $eventName) : \Cake\Event\Event

Triggers the given event name. This method provides a shortcut for:

$this->trigger('EventName', $arg1, $arg2, ..., $argn);

You can provide a subject to use by passing an array as first arguments where the first element is the event name and the second one is the subject, if no subject is given $this will be used by default:

$this->trigger(['GetTime', new MySubject()], $arg_0, $arg_1, ..., $arg_n);

You can also indicate an EventDispatcher instance to use by prefixing the event name with <InstanceName>::, for instance:

$this->trigger('Blog::EventName', $arg1, $arg2, ..., $argn);

This will use the EventDispacher instance named Blog and will trigger the event EventName within that instance.

Parameters

array|string $eventName

The event name to trigger

Returns

\Cake\Event\Event —

The event object that was fired

eventDispatcher()

eventDispatcher(string $name) : \QuickApps\Event\EventDispatcher

Gets an instance of the given Event Dispatcher name.

Usage:

$this->eventDispatcher('myDispatcher')
    ->trigger('MyEventName', $argument)
    ->result;

Parameters

string $name

Name of the dispatcher to get, defaults to 'default'

Returns

\QuickApps\Event\EventDispatcher

triggered()

triggered(string|null $eventName) : integer|array

Retrieves the number of times an event was triggered, or the complete list of events that were triggered.

Parameters

string|null $eventName

The name of the event, if null returns the entire list of event that were fired

Returns

integer|array

shortcodes()

shortcodes(string $content, object|null $context) : string

Look for shortcodes in the given text.

If any is found an event is triggered asking for its Event Lister method. For example:

{nice_button color=green}Click Me!{/nice_button}

You must define an Event Lister nice_button:

class YourListener implements EventListenerInterface {
    public function implementedEvents() {
        return ['nice_button' => 'shortcodeNiceButton'];
    }

    public function shortcodeNiceButton(Event $event, $atts, $content, $tag) {
        // return some text
    }
}

As you can see shortcodes methods will receive three arguments:

$atts

Array which may include any arbitrary attributes that are specified by the user. Attribute names are always converted to lowercase before they are passed into the handler function. Values remains untouched.

{some_shortcode Foo="bAr" /}

Produces:

$atts = ['foo' => 'bAr'];

TIP: Don't use camelCase or UPPER-CASE for your $atts attribute names

$content

Holds the enclosed content (if the shortcode is used in its enclosing form). For self-closing shortcodes $content will be null:

{self_close some=thing /}

$tag

The shortcode name. i.e.: some_shortcode

Parameters

string $content

The the text to parse

object|null $context

Context to use when triggering events

Returns

string —

Orginal string modified with no shortcodes [..]

stripShortcodes()

stripShortcodes(string $content) : string

Removes all shortcodes from the given content.

Parameters

string $content

Text from which to remove shortcodes

Returns

string —

Content without shortcodes

escapeShortcodes()

escapeShortcodes(string $content) : string

Escapes all shortcodes from the given content.

Parameters

string $content

Text from which to escape shortcodes

Returns

string —

Content with all shortcodes escaped

enableShortcodes()

enableShortcodes() : void

Enables shortcode parser.

disableShortcodes()

disableShortcodes() : void

Globally disables shortcode parser.

The shortcodes() method will not work when disabled.

viewMode()

viewMode(string|null $slug) : void

Sets a view mode or get current view mode.

Parameters

string|null $slug

Slug name of the view mode

addViewMode()

addViewMode(string|array $slug, string|null $name, string|null $description) : void

Registers a new view mode. Or overwrite if already exists.

Parameters

string|array $slug

Slug name of your view mode. e.g.: my-view mode. Or an array of view modes to register indexed by slug name

string|null $name

Human readable name. e.g.: My View Mode

string|null $description

A brief description about for what is this view mode

viewModes()

viewModes(boolean|string $viewMode) : array

Gets the full list of all registered view modes, or for a single view mode if $viewMode is set to a string value.

Parameters

boolean|string $viewMode

Set to true to get full list. Or false (by default) to get only the slug of all registered view modes. Or set to a string value to get information for that view mode only.

Returns

array

onViewMode()

onViewMode(string|array $viewMode, callable $method) : mixed

Runs the given callable when the in-use view mode matches.

You can provide multiple view modes, in that case callable method will be executed if current view mode matches any in the given array.

Usage

// run this only on `teaser` view mode
echo $this->onViewMode('teaser', function () use ($someVar) {
    return $this->element('teaser_element', compact('someVar'));
});

// run this on "teaser" view mode, or "search-result" view mode
echo $this->onViewMode(['teaser', 'search-result'], function () use ($someVar) {
    return $this->element('teaser_or_search_result', compact('someVar'));
});

Parameters

string|array $viewMode

View Mode slug, or an array of slugs

callable $method

A callable function to run, it receives $this as only argument

Returns

mixed —

Callable return

asViewMode()

asViewMode(string|array $viewMode, callable $method) : mixed

Runs the given callable as it were under the given view mode.

Usage

$this->viewMode('full');
echo 'before: ' . $this->viewMode();

echo $this->asViewMode('teaser', function () {
     echo 'callable: ' . $this->viewMode();
});

echo 'after: ' . $this->viewMode();

// output:
// before: full
// callable: teaser
// after: full

Parameters

string|array $viewMode

View Mode slug, or an array of slugs

callable $method

A callable function to run, it receives $this as only argument

Returns

mixed —

Callable return

_getElementFileName()

_getElementFileName( $name)

{@inheritDoc}

Workaround patch that allows plugins and themes provide their own independent "settings.ctp" files so themes won't "override" plugin element.

The same goes for "help.ctp" template files. So themes and plugins can provide help information.

Parameters

$name

_paths()

_paths( $plugin,  $cached)

{@inheritDoc}

Allow users to overwrite ANY template by placing it at site's ROOT/templates/Front and ROOT/templates/Front directories. These directory has the highest priority when looking for template files. So in other words, this directories behaves as some sort of "primary themes". Each directory represents a "Frontend" and "Backend" respectively.

Parameters

$plugin
$cached

_getLayoutFileName()

_getLayoutFileName( $name)

{@inheritDoc}

Adds fallback functionality, if layout is not found it uses QuickAppsCMS's default.ctp as it will always exists.

Parameters

$name

_evaluate()

_evaluate( $viewFile,  $dataForView)

{@inheritDoc}

Parameters

$viewFile
$dataForView

_setTitle()

_setTitle() : void

Sets title for layout.

It sets title_for_layout view variable, if no previous title was set on controller. Site's title will be used if not found.

_setDescription()

_setDescription() : void

Sets meta-description for layout.

It sets description_for_layout view-variable, and appends meta-description tag to meta block. Site's description will be used if not found.