ocPortal Tutorial: ocPortal site structure
Written by Chris Graham, ocProductsocPortal has a number of interacting systems, that together form the structure and navigation paradigm of your website. This tutorial will detail these systems, and show how they fit together.
To view the structural contents of your website, head over to the 'Structure' section of the Admin Zone, and choose the 'Site Tree Editor' icon. The Site Tree Editor is a very powerful tool for viewing the zones, pages, and categories within your website, and will help you build up a mental picture of how everything relates.
Table of contents
ZonesZones are the software's method for supporting sub-sites. The website directory structure could be heavily simplified from the user's point of view, to be as follows:
- (root directory)
The default zones in ocPortal are for the following purposes:
- Welcome Zone: this is a 'welcome' zone, that gives users the chance to join or login. It could be modified to act more like a 'splash screen' if you desire that
- Site: this is your main web site; it includes primary content viewing, and permission based submission, editing, and deleting features. The contents of this zone may automatically be merged into the Welcome Zone via the 'Single public zone' option, which will simplify things for you
- Collaboration Zone: this is a section for users given greater trust and tools
- Admin Zone: this is a section for site staff to manage the site
- Content Management: this is where content is added, edited and deleted
- Forum: this is where the forum resides
This is a detailed annotated diagram that explains ocPortal site structure
- Comcode pages – these are textual pages, written in Comcode (described in another tutorial)
- Modules – these are formal code-based pages
- HTML pages – these are pages written in HTML, and rarely used except for cacheing purposes
- Minimodules – these are like modules, except much easier to write; ocProducts does not use them for core ocPortal code, as they do not have the same 'fluff' around them that we need to maintain our clean architecture, but most technical users are better off writing these (if any new modules at all!) than full modules
A page/zone combination is accessed by URL and it is invisible to the user, and most elements of ocPortal itself, what kind of pages are being used for any given URL.
There is a priority system, to define which actual page to load:
- customised module
- customised Comcode page (users language)
- Comcode page (users language)
- customised HTML page (users language)
- HTML page (users language)
- customised minimodule
- customised Comcode page (site default language)
- Comcode page (site default language)
- customised HTML page (site default language)
- HTML page (site default language)
- (Page is marked as missing and an option is giving to add a Comcode page)
- Comcode pages should therefore be named not to conflict with the names of modules.
HTML pages can be placed in a pages/html_custom directory, but they should only contain the part that goes inside the body tag, not the body tag itself, the head section, or the HTML tag. In addition, it is preferable if URLs in the file are specified in full, rather than using relative URLs; this allows the page to be moved between zones without modification. If you do use relative URLs, they will be placed relative to the ocPortal zone URL, not the directory the HTML file is in.
This system is extremely powerful, allowing you to edit any page in ocPortal, including modules, but keep track of exactly what you have edited so that problems do not occur during upgrades. ocPortal even comes with a code editor that will automatically promote files to override directories upon edit.
ModulesocPortal comes with dozens of modules as standard. Most ocPortal pages are actually modules, and most of the ocPortal database tables are created by module self-installation code.
Entry points / Page linksThere is a simple standard in ocPortal for identifying a page accessed by URL, in a way that is not tied down to installation domain and directory, like a URL is. This standard is sometimes called an 'entry point' and sometimes called a 'page link'; generally, an 'entry point' is a predictable 'page link' that will work on any ocPortal installation with the same set/configuration of zones and pages. A 'page link' on the other hand, might depend on the actual content of the site.
Page links are commonly seen in their most simple form in the Comcode page editor. In this, a page is simply '<zone-name>:<page-name>'. This is the simplest case, as a Comcode page will never need any parameters (although they could take them, and use them if they contain blocks that do, to the parameter relates to ocPortal rather than the page itself). Note that the Welcome Zone is given with a blank, and hence just ':<page-name>' is written for a page in the Welcome Zone.
A more complex case is used in the menu editor, which has the ability to insert any ocPortal 'entry point' as an item on the menu. An example of an entry point is 'site:downloads:type=cat'. This points to the downloads module in the site zone, and specifies a 'type' parameter to be of value 'cat'; the URL will turn out to be like <base-url>/site/index.php?page=downloads&type=cat (or <base-url>/site/pg/downloads/cat if short-urls are enabled). Note that 'type' is a standard parameter name in ocPortal, used by almost all modules to segregate internal command (for instance, 'cat' in this case specifies category listing functionality, as opposed to viewing an actual download); the page-link syntax does not handle it any different, but the short-URL syntax does.
The most complex case is for a full blown 'page link' that could not be referred to as merely a standard 'entry point', because it depends on the state of content. An example of this might be 'site:downloads:type=cat:id=10', to view the download category of ID#10.
It is also worth understanding that page links have a long-form and a short form syntax. For simplicity I have used the long-form syntax above. The short form syntax allows you to remove type= and id=, so long as the parameters match the expected order. You can remove type= from the third component, and id= from the fourth component. So site:downloads:type=cat:id=10 will shorten to site:downloads:cat:10.
If you do not want to hard-code what zone to use, you may specify either '_SEARCH' or '_SELF' as the zone name in the page link. '_SEARCH' will cause ocPortal to dynamically find the module involved, whilst '_SELF' will use the same zone as the page link is dynamically being interpreted in (e.g. If if it used on a menu in the site zone, '_SELF' will be equivalent to 'site').
PanelsPanel pages rest around your main page, if they exist. Panel pages are nothing more than pages given special names in the same zone as the pages that they surround. The special names are:
If a zone is marked as 'wide' in its configuration, then no panels will be shown. In addition, if '&keep_wide=1'/'&wide=1' is attached to the URL, the target page for any links will also not use any panels. If '&keep_wide_high=1'/'&wide_high=1' is attached to the URL, the target page for any links will not use any panels, and will not have the standard top/bottom.
Panel pages (by default) are Comcode pages that arrange blocks, some of which are used to display menus. Blocks are described in the 'Custom pages of information (via Comcode pages)' tutorial, and are essentially dynamic sections of code (such as link menus, a login box, a search box, etc) that are pinpointed onto a Comcode page. Blocks may be inserted onto a Comcode page, and also into templates.
The Zone Editor
The Zone Editor
The Zone Editor makes use of special tabs to fit everything together, with each panel/page getting its own tab-set. The tabs provided are: view, edit, details, and settings (except for the panels).
This is a detailed annotated diagram that explains basic ocPortal template structure
This might seem bewildering, but after you get used to it, it will make perfect sense.
Another view of the structure of an ocPortal-driven website is that of the composition of templates. Templates are sections of HTML that are used (basically) to structure the visual output of your site. Blocks, modules and the ocPortal layout system that binds menus, use templates directly, to structure the data they wish to output; for example, the login block needs to give the username of the currently logged in user: this, along with a lot of other data, is passed into various templates. Templates are attached together, such that one template may follow on from another, or actually be embedded in one another. Comcode pages also use templates in a sense, but ocPortal itself decides what templates to use to display the Comcode involved. And ocPortal uses templates throughout its own internal code, for countless situations, such as displaying an error message, or generating a page title.
As mentioned previously, the two common ways templates are joined are:
- attaching/appending one to another: this is called attaching
- embedding one (or various, attached together) into another: this is called wrapping
A simplified view of the part of the ocPortal template tree that is common across all pages is:
(main pages wrapping template, and a lot more)
When something appears beneath, on the same level, it has been attached. When one of more things appear beneath, on one level deeper, they have been wrapped. As a tree structure, it is built up from the most deep parts of the tree, and wrapped/attached all the way back until the final composition exists: and then it is output.
HTMLA third view of the structure of an ocPortal-driven website, is that of the HTML itself. HTML forms its own tree structure, which is actually similar to how the final ocPortal template tree looks before it is output. HTML is of a lower level however, and if ocPortal didn't have the template system as an intermediary, layout control for non-programmers would be severely limited.
Navigation mechanismsocPortal includes a rich collection of navigation mechanisms to help you and your visitors quickly move around your website.
The main forms of navigation are:
- Panel menus; these are the main menus that are controlled by the menu editor
- Links; links are placed all over the system to allow navigation between areas and often provide far more detailed navigation than menus could provide (for example, clicking on a username hyperlink would normally take to that you to that member's member profile)
- Control actions; many 'view' style pages provide 'Control Actions' boxes that include links associated with the management of the entry or category you are viewing – for example, the screen for viewing a download would include a link to edit it in the control actions box
- The zone menu; the zone menu is the menu near the top of every page that allows quick navigation between zones
- The admin menu; this is the menu that allows moving between sections of the Admin and CMS Zones
- The community menu; this is the menu that allows moving between community sections of the site, and is shown by default if you visit the OCF forums
- The management menus (aka "Where to" menus); these are the menus in the Admin and CMS zones that provide icons – they are actually specialisations of the 'do next' menu system, which is also presented to provide tailored do-next links after you perform most kinds of management action in the system (such as adding a download)
- The breadcrumbs; these are the links that allow you to navigate backwards along modules or site sections that support tree structures – for example, if you were deep within the download system then breadcrumbs would be displayed allowing you to quickly go back to any of the categories underneath the category you are currently at, all the way back to the root category
- Bottom menu; this is the menu of small icons placed at the bottom of each page
- The admin popup menu; this is the popup menu that may be activated by clicking an icon in the bottom menu – this menu provides an alternative to the use of the admin and management menus
Some website adminstrators may wish to remove the zone menu in favour of their own, more tailored, navigation. This is perfectly acceptable and possible, and can be done by removing the relevant portion of Tempcode from the GLOBAL_HTML_WRAP.tpl template. Alternatively you can change the zone menu into a normal editable menu by enabling a special Theme Option (Admin Zone, Setup Section, Configuration icon, Theme options).
The admin and community menus may also be converted into normal editable menus quite easily should you wish to edit them. They are implemented via the 'menu' block being placed on 'panel_top' pages within their respective zones. All you need to do is to edit those 'panel_top' pages from the Comcode page editor (located in the CMS zone) to reference a different menu code (you can make a code up and you'll then be given the option to create it when the non-existent menu fails to display). The default menu codes start with the '_' letter which indicates they are code-generated menus that may not be edited, but if you change the referenced codes, normal menu editing may be applied.
Overriding breadcrumbsThere is a breadcrumb override facility in the Admin Zone that allows you to change how breadcrumbs work. It allows you to substitute in new chains, with powerful wildcard matching (PHP regular expressions). It is very useful if, for example, you want to show a gallery as existing underneath a download category. It is, however, advanced functionality and requires a rudimentary understanding of XML and a strong understanding of ocPortal page-links.
- Page link
- A special syntax that is like 'an ocPortal URL' that is written in a simplified form, local, and not tied to PHP/ocPortal URL reality (so if ocPortal URLs start to look different, Page links still work)
- Short URL
- A URL that points to content in a simpler, shorter, form. Also called a Quick URL' or an 'SEO URL'
- A sub-directory of ocPortal that stores pages and has separate configuration (including permissions)
- An ocPortal site consists of pages, and some pages (mainly modules) consist of multiple screens
- An actual screen that could be roughly categorised distinctly from all other screens (e.g. the backup system has a screen to start a backup, and a screen to view the results)
- An ocPortal page that is written in PHP to a very strict structure
- A module that is easier to write, but less powerful (it has no installation support, for example)
- Zone editor
- A unified zone and panel editor
- Site-Tree editor
- A frontend for viewing and manipulating all content on the website