xScape Templates Layout, Part 3: Content Loading

Previously we have seen how header (HTML HEAD block) and footer (last part after content) are made and loaded by the xScape and what can you do to expand it and control. Now, we are going through the main part of the theme layout structure, inside BODY tag: the content.

Main content loading function

Last part of the header.php file was opening of the BODY tag and running of xs_body_top action after BODY is opened. Content inside the BODY is loaded with xss_content() function. This function prepares the framework to load parts of the templates blocks, and starts the loading process. Even before the HEAD is generated, framework will decide what templates is loaded by WordPress, and it will get layout settings for it. Some themes support 2 types of layouts: standard and front. Front layout has different blocks from standard and is usually used for home page of the website. So, this function will load either front.php or content.php in the templates folder for the theme.

Actions run inside the function are:

  1. xs_include_mainblock_before: first thing run when the function is executed. After that call, function gets template and some of the global variables initialized.
  2. xs_include_mainblock_started: after function gets template and all globals, this hook is called.
  3. xs_include_mainblock_after: after everything loaded (content is now loaded and displayed), this hook is last thing run by the content loaded. After this, HTML footer block is loaded.

Templates types

WordPress can work with only one template file: index.php. But, for most uses, there are many default templates used: single.php (for single posts), 404.php (for error pages) and more. But, templates regardless of the name can have same structure. All archive templates are the same, but can have names based on taxonomy or post type. Because of that, xScape works with 6 template types:

  1. home: used for front page template only (home.php, index.php)
  2. single: used for single posts (single.php, attachment.php and single-*.php, where * is post type name)
  3. 404: used for error page only (404.php)
  4. search: used for search results (search.php)
  5. page: used for single page (page.php or anything else that is not belonging to other templates types)
  6. list: used for archive templates (archive.php, date.php, taxonomy.php, category.php…)

So, with this, xScape manages to have default list of options for each template type that can be used to control templates content. For each template type, theme can define one (at least) or more template files that user can select on the layout manager. This template type are only for main content area of the layout. All default content templates are located in templates/content folder. Each theme defines the list of content templates, default blocks layouts for each template type and default settings for use in the layout manager.

Modules or themes can add extra template types. bbPress module adds bbpress template type.

xScape Template Layout
xScape Template Layout

Template content file

Previous function loads content.php or front.php. Content file is not the same for all themes, but in general they all follow similar loading pattern. Each theme can have different blocks and loading of each block is same for all theme, and will be explained bellow.

Main task of content file is to load all blocks for a template based on the layout settings from Layouts Manager. Function xss_include_template() is used to load template blocks. As you can see on the image on the right, all the blocks will be loaded. Middle content area is usually starting after Main Header or Additional Blocks after Main Header (depending on the theme). Middle content ends before Footer Widgets or Footer (again, depending on the theme). Actions run here are:

  1. xs_content_container_top: runs when the middle content area starts.
  2. xs_content_container_bottom:  runs when middle content area ends.

Content files are easy to follow, and since each theme has own content file, you need to check that file for more details about the process. But, most important thing for any customization is loading of blocks, and for each block there are many hooks that can be used.

Template layout blocks loading

Loading of each block depends on the layout manager settings. For some blocks, position also depends on the settings (sidebars). But, in any case, same set of hooks will be used if the block is active. If some of the blocks are not displayed, none of the hooks for them is executed. Right now, xScape supports 4 classes of template elements: block, content, shared and custom. Block is used for all blocks in the layout except for main content area. Shared elements are loaded from xScape theme framework. If the template element loaded by the xss_include_template() function is shared, hooks are not used to change the path for the file used to make sure that template loaded is right one.

For other elements, loading procedure is the same. First part of loading is override for the template element. To do that there is a filter hook that depends on current template type: xs_include_template_path_$templatetype. So, for home template: xs_include_template_path_home, for single post templates: xs_include_template_path_single. Function attached to the hook can get 5 parameters: empty string (for template override), element class, template element name, template object (full current template object with all settings) and file name of the currently loaded WordPress template. Based on all this function hooked to the filter, must return full path to the template that needs to be loaded. If the value is empty, xScape will decide automatically which template to load.

Layouts Manager template selection
Layouts Manager template selection

If the loaded template element is content, xScape will check if in the layout manager user have set custom template for use or some of the standard templates. If its custom one, than it will not use file that it maybe got from the filter discusses in previous paragraph. For custom template set, it will load selected custom template from the layout manager. Look at the image above. For 404.php, Content is set to Custom template. In that case field bellow, marked Custom is used to get the content file to load. If its set to Auto, file loaded will be determined by xScape based on name of the WordPress template file. Or you can select file to load. List of files displayed is from templates/custom folder. By default, that folder is empty but you can add own files there.

If content file to load is not set to Custom, but you actually selected one of the default templates to use, than xScape will use filtered path if set. If not, default template element from templates/content folder is loaded. Now, that file to load is determined, we can go ahead to loading hooks:

  1. xs_include_template_before_$class_$template: filter based on the class for the element and the template name used with function call. This action is run before the template element file is loaded.
  2. xs_include_template_after_$class_$template: similarly to previous function, but its run after the template element is loaded.

All this maybe looking complicated, but in fact its not. It’s pretty much straightforward process. But to make this easier to understand, there are two more tutorials coming soon with practical examples on how to use all this. Remember, this Dev4Press website is made with this approach and custom templates are loaded and modified using hooks and process listed here. So stay tuned for more.


Leave a Reply