Display settings
1. Overview {#overview}
The Display settings is the main engine for dynamic website management. Through display settings you can control any piece of your project and maintain it in your own way. Don't expect to learn everything in one hour just by reading this guide, because this section is a very complex one.
In general any website is divided into main sections (displays), which are shown in the URL address immediatelly after the domain name. We usually have displays as: [domain]/company, [domain]/products, [domain]/gallery, [domain]/contact, etc...
Every display can have up to 9 subdisplays, for example: [domain]/products/cameras/sony/sony-alpha-dslr-a230. Each one of then can be maintained through display settings, where we can set combinations of functions, built-in queries, php templates, php variables and website locations. Any combination is presented in one row and can be separately controlled (cache, disable, edit, delete).
Every website has one special display which is shown as the first one, when we visit the website by basic URL address. The first display is not shown in the URL address, but you have to define it in main settings / start page and in display settings. When you define start page as home, both URLs will work: [domain] and [domain]/home.
Displays are available also in php as global array $GET, where every part of URL address is in it's own index. The parts of URL address [domain]/products/cameras/sony/sony-alpha-dslr-a230 are stored as php array: $GET[1] = products, $GET[2] = cameras, $GET[3] = sony and $GET[4] = sony-alpha-dslr-a230.
2. Templates management {#templates-management}
Imagine a simple website, which is divided into main sections as head, foot, center, left and right part. Each seaction has it's own name, which can be any one, but is recommended to use logical names that are simple to remember and maintain. Each section has it's own location as you can see from the image below. In each section we use one sub-template, for example we create a php file tplheadblock.php and inject it into $head section. All parts together are finally controled by template.php file, which holds basic HTML structure with information about section names and locations.
The best part of that logic is the fact, that the whole structure of website is totally flexible. You can put any php sub-template file into any website section, the displays settings just simply control when and where something happens. This adds the real dynamic to your website, because you can put tplcontacts.php_ file into $contact section when visiting [domain]/home, otherwise you put there tpllastimages.php file. Of course, by visiting [domain]/news, you put the tpllast2news.php_ file into $contact section. Get it? And that's only the $contact section! Every section can have any php file at any time, depending on the URL address (displays and sub-displays).
The above explained flexibility has one more upgrade indeed! Any php sub-template can be joined together with the results of DB query, which can be executed through MyPortal's built-in functions. Imagine the URL address [domain]/news, where we put the tpllast2_news.php into the $contact section. At the same time MyPortal executes the articles_list function from the articles category News and gets last two news by date. The result is stored into php variable, let's name it $lastNews, which is available for use in the tpllast2_news.php! This example would be one row (combination of function, built-in query, php template, php variable and website location) in the displays settings and each part (bolder text) is fully maintainable!
3. Displays management {#displays-management}
Here is the example how a part of display setting looks in MyPortal 2.3:
The first (gray) row determines the main display called forum, which has 4 icons on the right side: add function, add sub-display, cache and edit. The second (blue) row holds names for each column, so you can see that every display setting runs throung some function, which returns function output as php variable, joins together with a php template file and stores template output into specific website location. Each function has also some options as you can see in the last row, where the function determines the title of website, has enabled statistics and requires the article to exist in the database (otherwise returns 404 error).
Silver rows represent sub-displays and white rows contain display functions. Each sub-display has two icons for cache and edit. Each function has four icons for disable, global, cache and edit. In this example you can see sub-displays as forum/*, forum/*/* and forum/*/*/*. The asterisk sign stands for any string, which is put in the URL address and can be available through variables $GET[2], $GET[3] or $GET[4] ($GET[1] = forum). You can have also fixed sub-displays such as forum/theme/lock/*, where you can determine anything that should happen, when the website calls URL address [domain]/forum/theme/lock/123 (123 could be the theme's ID).
Let's explain the second white row, categories_list function:
- Checkbox: select functions in combination with buttons REMOVE SELECTED, COPY DISPLAYS and COPY FUNCTIONS.
- Up and down arrows: move function up or down
- articles categories list: the name of the function categories_list in ___articles___ module
- cnt: the results of categorieslist_ function are stored into $cnt variable (function output)
- tpl_rightmenu.php: the sub-template file with HTML and PHP script ($cnt is available for use)
- right: the website location where the tplrightmenu.php_ will be injected and executed (you have to put php <?=$right;?> command into your main template.php file)
- currently no extra options
- disable icon: the function executes if icon is off otherwise is disabled
- global icon: the function executes also in all sub-displays if is set to 'on' otherwise executes only in it's display
- cache icon: the final HTML result of this function is saved as txt file into cache folder for faster website loading if icon is set to 'on' (see also main settings), otherwise it executes every time
- edit icon: opens the window with all function settings
Reserved displays are: image, file, mail and sys, so you cannot use them as your custom displays.
General functions: templates and functions which you need to execute every time on each URL address (displays independent) should be put into the general functions section, which is at the top of the Displays settings. Those functions are global, but you can override them with displays functions, if you inject them into the same website locations.
4. Displays functions {#displays-functions}
articles:
- article
- articles list
- articles list light
- articles pages
- category
- categories list
core:
- system
- custom block
- model view
files:
- file
- files list
- files list light
- files pages
- category
- categories list
images:
- image
- images list
- images list light
- images pages
- category
- categories list
users:
- user
- users list
4.1 Article, articles list and pages
Here is the example of the articles article function settings, which gets the article with IID 27 from database, stores article into the $content variable, executes the tpldescriptionmain.php file and injects it into template.php at the $right2 location (the article's name becomes the title of the website and the statistics for that article is updated):
The item field is not obligatory, the image above just shows an example. You could leave the item field empty and use dropdown menu GET (for example setting it to 3). The articles article function would read the IID number from the URL address ($GET[3]) and use it in the DB query to search the desired article. The dropdown menu field is also not fixed to IID field, you could search for an article by it's furl field (the unique alias, created from article's title, such as sony-alpha-dslr-a230). The category dropdown menu holds the whole structure of articles categories, so you can restrict DB query to search for an article only in one category (or more in depth if recursive is checked).
The sql where field is another option to restrict the built-in DB query, because you can put your additional conditions to it, for example articles.name LIKE '%sony%'.
The searchable field saves the current URL address to article's category's field surl, so you can recreate the article's URL address when making search results or sitemap.
The required field requires the article to exist in the database if it is checked (otherwise returns 404 error).
The articles_list settings are preaty much the same as the article settings, just without _set title, log statistics, searchable and required_ checkboxes. The built-in DB query searches for a group of articles, respecting your settings and rules.
The articleslistlight has the same functionallity as the articleslist_, the difference is only in the build-in DB query, which can be faster in some extreme situations.
The articles_pages can be used only in combination with the _articles_list_ function, because you have to set the same rules and restrictions in both functions. The output of this function is not an array of articles but an array of pages numbers (for example [1,2,3,4,5]), which are calculated from the number of all found articles and the number of articles per page. In the _articles_list_ function you have to check the _pagination_ field and determine the same _limit_ number in both functions (articles per page). Pagination works automatically if you use ?page=n in you URL address, where n is the number of the desired page.
4.2 Category and categories list
- Those functions are very much the same as article and articleslist_ function, because the only difference is in the fact, that the built-in DB query searches for categories instead of articles.
4.3 Files, images and users
- You should use all of those functions (file, fileslist, filespages, image, imageslist, imagespages, user, etc...) in the same manner as articles functions, because the rules and restrictions in their settings are very similar. The built-in DB queries are constructed in such way, that provide you all data you need. You can get from the database almost anything you want, so it is very simple to create websites with images galleries, files collections, blog articles, users management and so on.
4.4 Core functions
It is true, even in the MyPortal 2.3 CMS you can run into situations, which can't be solved only by using pre-prepared functions and built-in DB queries. Therefore you can use three core functions:
system
Call any sys file (for examplesyscheckdb.php), which has to be in template/system folder. Suitable for php processes in background, mail sending, rss reading, etc...
custom block
You can write your own DB query, which stores results into the $companies variable, joins it with the tplleftmenu.php file and shows it in the $left website location. All red variables are just for example, you can user your own, of course. You can also leave the function output and sql query fields empty and just simply show some php file in some website location. The example above could be solved also by userslist_ function, this is just an illustration.
model view
The model view is used for some very tight related scripts, where you want to have nicely separated PHP logic from HTML structure. This function joins together the php script from the template/models folder with the php script from the template folder and inject them into the same website location.
