Content / Jet\MVC_Page_Content

You already know how the MVC works in Jet , what is a base, what is a page. And now it's time to look at the content of the page. That is, the perhaps a bit inconspicuous (or rather tucked away) but nonetheless very important Jet\MVC_Page_Content class and its Jet\MVC_Page_Content_Interface. This class is also interchangeable thanks to the factories system, as are all other classes within the MVC ecosystem.

For clarity, we will again divide the class into at least topic headings. Although its implementation is not that large and thus not divided into traits.

Basic methods

Method	Meaning of
public setPage( MVC_Page_Interface $page ): void	Determines to which page the content belongs. This is done by the page entity itself (e.g. during __wakeup). So it is not necessary to use the methods normally.
public getPage( ): MVC_Page_Interface	Returns the page instance to which the content belongs.
public toArray( ): array	A method for converting an object into raw data for storage.

Content position within the layout

Method	Meaning of
public getOutputPosition( ): string	The method returns the name of the position within the layout to which the content belongs.
public setOutputPosition( string $output_position ): void	Sets the position (position name) within the layout.
public getOutputPositionOrder( ): int	The definition of the position title is not enough. There can be any amount of content on one position. A position is not reserved for just one output/content. Thus, it is necessary to define the order (priority) in which the content should be displayed in a given position.
public setOutputPositionOrder( int $output_position_order ): void	See method getOutputPositionOrder

Static content or callback

For a page you have the option to define all of its static content, or the callback by which the content is generated.

And the same goes for individual content. The difference is that it doesn't apply to the whole page, of course, but only to individual content in a certain position.

Suppose you only want to have some informational text in a certain position. This text will not be changed often, it will not need to be edited from the administration. On the other hand, you don't want to put it directly into the layout, because this text (or any other type of content) can vary on different pages.

For such a thing it may not make sense to make a whole module, controller, view ... The content can be completely static (and you can edit it in Jet Studio if you want), or you can use callbacks. Incidentally, a demonstration of using a callback for such a situation is in the sample application.

Of course, if you use this approach, then you don't use module and controller bindings.

Method	Meaning of
public getOutput( ): string\|callable	Returns the set static content or callback.
public setOutput( string\|callable $output ): void	Sets static output or callback.

Content using application modules

If the content isn't static or callback generated, then it can be linked to application modules. While this is an option, it's the most common way for me to approach things and I use this method most often.

For example, this article showed the "Web.Doc.Browser" module, but there are plenty of other modules to explore in the sample application, such as "Content.Articles", "Test.MVC" and a host of others.

Method	Meaning of
public getModuleName( ): string	The getModuleName method returns the name of the application module that generates content.
public setModuleName( string $module_name ): void	Sets the name of the application module that generates content.
public getModuleInstance( ): Application_Module\|bool	Returns the instance of the application module that takes care of the content. Warning! It can also return false. And it's perfectly fine. The system takes into account that the module may not be installed or not active. And such content is simply skipped. So if you use application modules (correctly), you have the ability to activate and deactivate various elements and features of your application.

Controller - using application modules

If an application module will be in charge of the content, then it is necessary to specify which controller of the application module will be in charge of the content. Of course, it does not specify the full/full name of the controller class, but only the name of the controller, which is automatically converted to the name of the class belonging to the application module.

I'd better explain it straight with an example. For example, in the sample application you have a "Localization Test" page that demonstrates what Locale can do.

This is the definition of the content of the mentioned page:


return [ 

      // ... ... ...

      'content' => [

               [

            'module_name'           => 'Test.Locale',

            'controller_name'      => 'Main',

            'controller_action'     => 'test_locale',

            'output_position_order' => 1

        ]

    ]

];

As you can see, the content points to the Test.Locale application module and the controller name is Main (which is the default value by the way and is used even if the controller is not directly specified - so you may not always find this in the definitions)..

But the name of the controller "Main" will be changed to the name of the class in the final version:
JetApplicationModule\Test\Locale\Controller_Main

And this class will take care of the security of specific content. Jet will take care of the controller class name.

The content already knows which controller class of the application module it will be routed to - that is, which specific class will secure the content. That's almost it, but one question remains: What method of that class should be called?

If you become more familiar with the controller, you will know that the controller introduces the concept of action. Actions are de facto methods with the suffix _Action in their name.

Of course, one controller can have more actions - as many as needed. It is not true that a controller has one action, and therefore it is necessary to specify which specific action (actually methods) the content security should be directed to.

To put it simply: the action name specifies which method (which has the _Action suffix in its name) of the controller class should be called to dispatch the content.

Method	Meaning of
public setControllerName( string $controller_name ): void	Sets the name of the application module controller that should take care of the content.
public getControllerName( ): string	Returns the name of the application module controller that should take care of the content.
public getControllerInstance( ): MVC_Controller\|bool	Returns the controller instance of the application module. Beware! The same applies here as for the getModuleInstance method. That is, the method may return false. Logically, if the content is bound to an uninstalled and/or inactive application module, the controller cannot be instantiated. However, as I already wrote, the system fully accounts for this and the content is simply "skipped".
public getControllerAction( ): string\|bool	Returns the name of the controller action. If the action name is not specified in the definition, the value of the constant MVC_Page_Content::DEFAULT_CONTROLLER_ACTION is used, which means the "default" action.
public setControllerAction( string $controller_action ): void	Sets the controller action.

Controller - without application modules

There is another way to take care of the content. And it's neither static content, nor callbacks, nor application modules.

The content can be directly linked to a class (a class that will be in your application space) that does not need to be part of any module and this class represents a controller, so it inherits from the abstract class Jet\MVC_Controller.

Yes, it's technically to keep almost everything from Jet MVC but not use application modules. Personally, I've never used this option, but it might be a better solution for something someday.

Method	Meaning of
public setControllerClass( string $controller_class ): void	Sets the full class name of the controller responsible for content that is not part of any application module.
public getControllerClass( ): string	Returns the full class name of the controller responsible for content that is not part of any application module.

Parameters

As with a page, you can use parameters for individual content. The parameters are part of the definition, but can be freely manipulated within the application space.

Method	Meaning of
public getParameters( ): array	This method returns a list of all parameters in the form of an associated array, where the array key is the parameter name.
public setParameters( array $parameters ): void	Sets internal content parameters. See the getParameters method.
public getParameter( string $key, mixed $default_value = null ): mixed	Returns the value of a specific parameter, or the default value if the parameter is not defined.
public setParameter( string $key, mixed $value ): void	Sets one specific parameter.
public parameterExists( string $key ): bool	Determines whether the parameter exists.

Cache

The MVC cache is a topic in itself. But there's something to be said for caching in the context of the page content.

First of all, the content must define whether it is/is not cacheable.

So for example if it is for example a listing of an article, i.e. content that does not change or changes only minimally, then it is certainly cacheable.

But if it's a real-time data dump, just something that changes frequently and the cache would be constantly deleted anyway, there's no point (or it's even counterproductive) in caching such a thing.

Here's a small insertion. Over the years I have tried different strategies to do this. Determining whether to cache or not to cache is very important. I have searched and tried different paths, different automation and semi-automation within Jet. But I've come to the conclusion that the application developer (i.e. you) knows best how it will and should behave, and that the best thing to do is to simply define cacheability and leave it up to the developer how to handle it.

Method	Meaning of
public setIsCacheable( bool $state ): void	Sets whether the content is cacheable.
public isCacheable( ): bool	Indicates whether the content is cacheable.
public saveOutputCache( string $output ): void	Saves the output to the cache. This is a system issue, you don't have to deal with it in the application space.
public loadOutputCache( ): bool	Pre-record the content from the cache. Again an internal system issue that you don't have to worry about in practice.

Dispatch and output

Method	Meaning of
public dispatch( ): void	And this is where it all happens... Where the controller is called, or a callback is called, or the static content is directly included in the layout. But the method also solves everything around. It sets up the translator correctly. It also automatically creates profiler blocks. So your code, your modules, and your classes will already be called from this important place.
public output( string $output ): void	Using this method, the controller returns the generated output back to the content. If you use the normal path and work with modules, you will not encounter this method in practice. But if you do need a different approach, it is important to keep this method in mind. This method takes care of saving the output to the cache and also placing the output in the correct position in the layout.