Pages Overrides

What is an override? It's a technique to create a clone-copy of a specific layout file that generates the graphical output of a specific page/content of the plugin, or one of its widgets. Imagine that you would like to remove a link from a page, or to add a text or a button. If you were to modify the original (core) file of the plugin, then at its next update all your modifications would go lost. Instead, you can create an override for that specific layout file so that it will be preserved during the installation of the future updates.
Just to be clear, this is a feature of the plugin VikAppointments and all its widgets, because WordPress does not support overrides by default. It's a function that our programmers have built to meet the needs of our clients.

The plugin actually supports 3 types of overrides: pages, widgets and layouts.

In order to create an override-file you need an FTP client software to create a couple of folders and to download/upload some PHP files.

Pages

All the supported pages of VikAppointments, for both the front-end and back-end sections, are always contained within the following folders:

• /wp-content/plugins/vikappointments/admin/views/[PAGE_NAME]/tmpl/[FILE_NAME].php (back-end pages)
• /wp-content/plugins/vikappointments/site/views/[PAGE_NAME]/tmpl/[FILE_NAME].php (front-end pages)

The first thing to know is how an override path should be built. Here it is:

/wp-content/uploads/vikappointments/overrides/[CLIENT]/[PAGE_NAME]/[FILE_NAME].php

• [CLIENT] - should be replaced by "site" for front-end pages or "admin" for back-end pages;
• [PAGE_NAME] - should be replaced by the name of the page for which we need to create an override;
• [FILE_NAME] - should be replaced by the file name contained within the view folder (usually starts with default.php).

In order to complete the creation of an override, it is needed to copy all the PHP files (only one or maybe more) contained within the tmpl folder of the selected page, and paste them within the related override folder.

Let's clarify with a practical example by overriding the "Services List" page in the front-end, the one that displays all the published services. You'll see that this page split the output in different sub-templates, just to keep the code a lot clearer. It is not needed to create an override for each sub-template, so you might have to inspect the code of those files to figure out who's holding the code you need to change. In example, if you wish to wrap the name of the groups within a heading tag, then you should definitely override the default_group.php file.

1. before all we need to download the file of the page to override from the path below:
   /wp-content/plugins/vikappointments/site/views/serviceslist/tmpl/default_group.php
2. the downloaded file has to be uploaded in the related overrides folder:
   /wp-content/uploads/vikappointments/overrides/site/serviceslist/
3. we can now start editing the uploaded file in order to change the HTML tag.

This override file will never be touched by future updates, and it's a secure layout file because it can only be accessed by VikAppointments during the execution of the WordPress framework.

Widgets

The overrides for the widgets work almost in the same way. Here's the default path of the file that displays the contents of a widget:

/wp-content/plugins/vikappointments/modules/[WIDGET_NAME]/tmpl/default.php

And here is the resulting path of an override:

/wp-content/uploads/vikappointments/overrides/modules/[WIDGET_NAME]/default.php

Unlike the overrides for the pages, you are not forced to use the same name of the widget file (default.php). You may use the name you prefer, such as "mywidget.php".

For example, to create an override file of the "Search" widget, you should copy the following file:
/wp-content/plugins/vikappointments/modules/mod_vikappointments_search/tmpl/default.php

onto the following path (create the missing directories, if needed):
/wp-content/uploads/vikappointments/overrides/modules/mod_vikappointments_search/default.php

The widgets overrides are never automatically applied. In order to take effect, you MUST instruct your widgets to use a specific override. This because you might want to publish the same widget with different styles. You can do that from the Appearance > Widgets page. While editing a widget, you should be able to see a Layout parameter, which lets you choose the override to use. In case you are not seeing the override you created, there's probably something wrong with its path.

Layouts

While creating an override for a specific page, you may encounter a piece of code built as follows:

echo JLayoutHelper::render($layoutId, $displayData);
// or
$layout = new JLayoutFile($layoutId);
echo $layout->render($displayData);

This code is used to include a layout within the page. But, what is a layout? A Layout is an external piece of code that the plugin may use several times in different sections. So, instead of repeating the same code more than once, the system declares a layout file that can be included in different sections of the program. Is there a practical example? Sure, the login/registration form. This is an immediate example, because the same login layout is used by 6 different sections of the program.

In summary, when you encounter a code similar to the one mentioned above, you have to create an override for a layout file. Obviously only in case the changes you need to do are contained inside that layout.

The layout files are contained within the following folders:

• /wp-content/plugins/vikappointments/admin/layouts/ (back-end)
• /wp-content/plugins/vikappointments/site/layouts/ (front-end)

Curious fact: some front-end layouts are also used by the back-end section of the plugin. Back-end layouts are never used by the front-end section of the plugin.

The first argument of the render method ($layoutId) indicates the relative path of the layout with a dotted notation. The login form uses the following path: blocks.login. This means that the resulting path of the login form will be this one: /wp-content/plugins/vikappointments/site/layouts/blocks/login.php.

The override path of the layouts will be built as follows:

/wp-content/uploads/vikappointments/layouts/[CLIENT]/[$layoutId]

• [CLIENT] - should be replaced by "site" for front-end layouts or "admin" for back-end layouts;
• [$layoutId] - follows the relative path of the layout file.

So, in case you wish to create an override for the registration form, here's the resulting path of the override:
/wp-content/uploads/vikappointments/layouts/site/blocks/login.php