HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


ocPortal Code Book

For ocPortal version 9.0
« Return to Code Book table of contents


Using git to deploy

Deploying to a live server using git is a great idea. However, be aware some caveats…
  1. Disable dev-mode in the config file using:

    PHP code

    $SITE_INFO[(EUR-)~dev_mode‚(EUR-)(TM)]=(EUR-)~0‚(EUR-)(TM);

    git automatically enables dev mode, which intentionally inteferes with things to help you develop quality code – such as adding extra checks, or disabling cookies so that you don't rely on them. This is great for development, where the developer is in control of everything, but not correct for production.
  2. Use a decent .gitignore so you don't get a lot of noise when running git status. Our default one is good but may need tuning.
  3. Either keep the config file out of git, or put code in there to differentiate between machines via checking $_SERVER['SERVER_ADDR'] ($_SERVER['LOCAL_ADDR'] on a Windows server).
  4. Make heavy use of git branches so that you don't get stuck having to perfect all code before you can update anything onto the server.

You can consider a half-way house, by having a full checkout on the server, then separately symlinking specific directories into the main public_html. This is useful if you only want certain directories in git, such as a docs zone (docs in this example being managed offline, and pushed live using git).

You can also consider multiple checkouts on the server, such as a testing site, and a live site. This allows you to test things with greater care.

Troubleshooting

There are a number of issues developers face when programming for ocPortal. Our high standards and development mode means issues are raised to the surface that less skilled programmers may not easily notice when working with other systems.

XHTML

Not many developers realise that the XHTML doctype does not tell web browsers to render a page as XHTML. The doctype serves two purposes:
  • It specifies what rules the document should validate with (browsers do not do validation at all, so this is a non-issue from the rendering perspective)
  • It tells browsers to not render in "quirks mode". This is a fudge invented by Microsoft and Netscape programmers, and is nothing to do with XHTML – it is to do with enabling correct CSS.

XHTML rendering is in-fact enabled via a mime-type. In development mode, ocPortal turns on the XHTML mime type, which means sloppy non-XHTML practices will not work. Many developers are surprised by some of the restrictions this brings up as they thought they were already good XHTML developers and understood how to work with XHTML – when the reality is they had always been developing for HTML renderers in the past. If you are one of these developers it is important you learn how XHTML really works.

The two biggest restrictions added by XHTML are as follows:
  • Basic XHTML errors like writing "&" instead of "&" will cause the browser to not be able to render the page fully. In Firefox this is worst, as the whole page will fail to render at all.
  • You cannot use .innerHTML and some other Javascript properties. Instead you will need to use the set_inner_html and get_inner_html functions that ocPortal supplies to get around this issue. Our functions have been carefully tuned over the years to work on all browsers, but they correctly work in XML rather than by fiddling with an HTML "byte-dump". Some Javascript libraries use .innerHTML a lot, so if you use them with ocPortal and want development mode to work (or want to write XHTML correctly in general) then you'll need to alter them a bit.

If you are seeing an XHTML error because ocPortal has died with some kind of error and it couldn't output fully correct XHTML in the process, you'll want to be able to see the error, but Firefox makes it hard due to it's total failure to render invalid XHTML. You can either look at the XHTML source, or here is a good quick tip:
  • Install this Firefox extension: Open in Browser :: Add-ons for Firefox
  • If you see an error go to the View menu, the View As submenu, and choose "Web page".
  • You will see the page will re-load (the extension has forced the HTML renderer to be enabled for that page view).

ocPortal tries very hard to output nice errors without ugly XHTML errors, but the following known situations cannot be handled due to limits in PHP:
  • The PHP time limit being exceeded (and development mode intentionally imposes a 10 second time limit). It is possible if you load a page with lots of iframes that the iframes could show XHTML errors due to overall server load being high due to simultaneous stress. Then when you look at the iframe source you see no error because it reloads outside of a stress situation.
  • See also the 'blank pages' section below, as blank pages will result in XHTML errors.

MySQL errors

ocPortal is not just built for MySQL. It is designed to work with any kind of database software. It is all to common for developers to assume specifics of the MySQL platform are standard SQL and can be used freely. MySQL in fact is very non-standard in certain ways. ocPortal enables "MySQL strict mode" to force MySQL to (correctly) complain when mistakes (such as non-specified field values) are made.

If is advisable for you to:
  • code SQL conservatively and not try use things ocPortal does not already use
  • avoid being sloppy and getting MySQL to perform automatic type conversions and to automatically guess missing values during insert queries.

Tempcode

A common mistake is to use Tempcode objects as strings. These are not strings, and can't be used as strings unless you do something like $string=$tempcode->evaluate(); to get the string equivalent first. We can't rely on PHP 5's __toString functionality in ocPortal unfortunately (and we don't want to actually, because that makes the code a bit harder to analyse).

Blank pages

If you find you are getting a blank page it is likely because you either have exceeded the PHP memory limit, or a PHP parse error has happened.

You can often find out what the error was by putting &keep_show_parse_errors=1 into the URL. This will make ocPortal run slower and it might introduce some weirdness, but it often will also reveal the errors. Additionally, enabling the PHP display_errors and display_startup_errors in your main php.ini is a good idea (for a development server only).

Sometimes this advice will not help: if there is an "@" (error suppression operator) somewhere above the function call chain for where a fatal error happened then this will make fatal errors result in a silent blank screen. ocPortal cannot detect them. You should use "@" sparingly anyway.

Query limits

If you get errors about query limits consider optimising your code to use less queries. If you cannot do this, you can set:

PHP code

$GLOBALS['NO_QUERY_LIMIT']=true;

in your code.

You can also put &keep_no_query_limit=1 into the URL to have query limits temporarily disabled. Often when caching is disabled or empty the query limit can be exceeded.

Debugging

If development mode is running then the inspect function will be available in PHP. You can run commands like:

PHP code

inspect($a,$b,$c);

and ocPortal will output the contents of these variables very neatly for you, and give a stack trace.

If output has already started then ocPortal will give you your details in an info box at the bottom of the rendered screen; otherwise you'll get a text dump.

This is very useful when stepping through code. Often bugs are because you are using the wrong data types (e.g. Tempcode objects being treated as strings). Temporarily placing inspect calls in your code and moving them along as you analyse exactly what is happening is a good way to test exactly what is happening for the occasions when the automatic stack dumps are not available or do not reveal the real cause of the problem.

If you have an IDE with a debugger then this is better, but we find most developers do not have one, and also PHP debuggers tend to be quite unreliable. This old fashioned manual technique of manually tracing through code works well if you are quick at making changes and refreshing the browser window.

Tips

Form fields

To save time and auto-populate form fields during testing, if you have the Web developers toolbar extension for Firefox, you can right click, then choose: Web Developer –> Forms –> Populate form fields.

Debugging CSS

Use the Firefox Firebug extension's 'Inspect' tool, or an equivalent utility in your web browser of choice. It will save you a lot of time.

Debugging Javascript

Use the Firefox Firebug extension's Javascript breakpoint facility, or an equivalent utility in your web browser of choice. It will save you a lot of time.

Advanced deployment and customisation

Hidden features inside ocPortal

ocPortal contains a number of hidden 'values', 'keep' parameters, and empty file flags. These allow activation of special functionality that isn't considered important/mainstream enough to warrant user-interface space within ocPortal.

Empty files

The presence of the following empty files in the root directory have a special meaning to ocPortal:
  • install_ok – don't complain if install.php is left present (DO NOT use this unless your install is not connected to the Internet or if you definitely have an install_locked file)
  • install_locked – whether to lock the installer (prevent it running)
  • old_mysql – degrade mySQL functionality so that old (official unsupported) versions will basically work with ocPortal

Hidden 'values'

Values are like hidden configuration options. They are either hidden because they are managed by code (perhaps used for keeping track of something), or because they are obscure. To set a value, open up OcCLE (under the 'tools' section in the Admin Zone or clicking the symbol at the bottom-left of any page) and type :set_value('<name>','1'); (replace '1' if appropriate, but usually we do use '1' to enable). In normal PHP code, you can use the same set_value function, and also the get_value function. You can automatically add a new hidden value just by setting it for the first time.

The values you might want to manually change are:
  • disable_animations – set this to '1' if you do not want animations in the UI.
  • breadcrumb_crop_length – set this to the maximum number of characters to include in a breadcrumb segment.
  • seq_post_ids – set this to '1' if you want to make the post ID numbers shown on topics sequential rather than refer to the true ID of the post in the database (those IDs are forum-wide).
  • disable_staff_notes – set this to '1' if you want to no longer have 'staff notes' options on forms.
  • disable_seo – set this to '1' if you want to handle content SEO automatically and not ever show for fields for it. Set this to '2' if you want to handle it automatically on add, but allow fine tuning on edit.
  • max_forum_detail – set this to the number of forums, before which sub-subforums will not show. Default is 100.
  • max_forum_inspect – set this to the number of forums that will be shown as subforums, or inspected for unread topics. Default is 300.
  • force_local_temp_dir – set this to '1' if your server has a problem creating/deleting temporary files in the system directory.
  • jpeg_quality – set this to a desired JPEG quality level, for any JPEG thumbnails that are created. It should be a value between 0 and 100. Thumbnails are generated in the same image format as the source images; i.e. a JPEG source image would have a JPEG thumbnail.
  • simplify_privacy_options – set this to '1' if you want the custom profile field privacy options to be simplified/compressed a lot (less multi-dimensional, no usergroup filters).
  • disable_mark_forum_read – set this to '1' if you want to remove the mark-forum-read feature.
  • disable_mark_topic_unread – set this to '1' if you want to remove the mark-topic-unread feature.
  • disable_forum_dupe_buttons – set this to '1' if you want to disable the duplicated set of buttons when viewing forums and forum topics.
  • disable_pt_filtering – set this to '1' if you want to remove the private topic categorisation feature.
  • disable_user_online_groups – set this to '1' if you want to not show the usergroups that online users are in (this simplifies the display).
  • no_inline_pp_advertise – set this to '1' if you want to not advertise the inline-private-posts feature.
  • disable_multi_quote – set this to '1' if you want to disable the multi-post-quote feature.
  • disable_add_topic_btn_in_topic – set this to '1' if you want to disable the ability to create one topic when viewing another.
  • disable_skip_sig – set this to '1' if you want to disable the 'skip signature' option.
  • disable_views_sigs_option – set this to '1' if you want to disable the per-member 'view signatures' option.
  • disable_pt_restrict – set this to '1' if you want to disable the per-member "private topic restriction options".
  • disable_ecards – set this to '1' if you don't want ecards on galleries and still want the recommend addon on.
  • disable_csv_recommend – set this to '1' if you don't want the CSV upload option on the recommend-to-a-friend form.
  • disable_boolean_search – set this to '1' to disable an explit option to do boolean searches (which can be slow). It does not actually disable boolean searches fully, you can activate them by using + and - in queries; but really short keywords will fail because boolean search will work via the full-text search index, which has a character limit
  • proxy – set this to the hostname/IP-address of the machine acting as an HTTP proxy server. This can also be set via a server environmental variable of the same name, although you likely need to reset the whole server first (you definitely do on Windows with Apache, as it does not get into the environment until you do this).
  • proxy_port – set this to the port name of your HTTP proxy (if you do not set it it defaults to 8080). This can also be set via a server environmental variable of the same name (see above).
  • proxy_user/proxy_password – set this to the authentication user/password for your HTTP proxy (if you do not set it, no authentication will be used). This only works if 'prefer_curl' is on. This can also be set via a server environmental variable of the same name (see above).
  • minutes_between_sends – set this to the number of minutes between batches of newsletter sends (default is 10).
  • mails_per_send – set this to the number of e-mails to send out in each e-mail send batch (default is 60).
  • primary_paypal_email – set this to your primary PayPal email address, if you have set up PayPal to work against a secondary PayPal address instead. Without it ocPortal will fail to validate payments, causing all eCommerce to fail.
  • simplify_wysiwyg_by_permissions – set this to '1' if you want to show a simpler WYSIWYG editor to members with limited Comcode permissions.
  • edit_with_my_comcode_perms – set this to '1' if content you edit should render with your Comcode permissions. Only enable this if you trust yourself to spot XSS attacks.
  • permission_log_success_too – set this to '1' if you want the permission log file (data_custom/permissioncheckslog.php) to show both successful and unsuccessful permission checks. Usually it only shows fails.
  • site_location – an address for where your website is, sometimes used in meta-data.
  • google_news_urls – set this to '1' if news URLs should contain a Google-News-friendly entry ID.
  • enable_delayed_inserts – set this to '1' to enable MySQL delayed inserts. Delayed inserts can cause a very small performance improvement if log calculations happen quite regularly; however they only work on MyISAM tables and are deprecated as of MySQL 5.6
  • really_want_highlighting – set this to '1' if you want to force HTML to be converted to Comcode when searches happen, so keyword highlighting works better.

We also have the following which are either unlikely to be useful, or potentially unstable or unpolished:
  • stupidity_mode – set to 'leet' or 'bork', for a fun April Fools-style Comcode joke (clear the Comcode cache after you're done though)
  • rebrand_name – if ocPortal is called something else as far as the site staff are concerned, set the name here
  • rebrand_base_url – to change where branding URLs go to (e.g. the stub that is used when linking to documentation), set it here
  • company_name – if ocPortal is being rebranded to be 'made' by another company, set the name here (this has no effect of copyright of course, but ocProducts allows this)
  • comment_forum__galleries / comment_forum__images / comment_forum__videos / comment_forum__downloads / comment_forum__calendar / comment_forum__news / comment_forum__iotds / comment_forum__polls – override the comment forum for a particular content type
  • comment_forum__catalogues__<catalogue-name> – define a comment forum for a specific catalogue
  • ionic_on – inform the software that the IIS Ionic Rewriter plugin is installed and configured
  • unofficial_ecommerce – set to '1' if your forum driver contains usergroup manipulation functions (we don't support this, but wanted to be able to allow those willing to extend forum drivers to use our full eCommerce framework)
  • lots_of_data_in_* – set this to '1', with '*' replaced with a database table name, if you want the ocFilter mechanism to work with recursive db lookups rather than one huge flat lookup
  • textmate – set this to '1' if you are developing on a local machine and use the Apple Mac TextMate editor. It will cause TextMate editing links to come up in stack traces.
  • disable_iconv – set this to '1' if your iconv extension causes PHP to crash
  • disable_mbstring – set this to '1' if your mbstring extension causes PHP to crash
  • no_frames – set this to '1' if you do not want ocPortal to use frames at all in public screens. Set to '2' if you are very anal and don't want them in admin UI's where they are there to improve usability.
  • xhtml_strict – set this to '1' to do some magic to make ocPortal's output XHTML strict. This is slow and not really advisable as it will degrade the user experience if Javascript is not available (new-window links would break). You must enable 'no_frames' also
  • no_password_hashing – set this to '1' if you want passwords to be stored as plain-text in the database (not recommended)
  • agency_email_address – set this to a secondary e-mail address where you would like all error e-mails to go (the primary one being the staff address). Only set this if you are an agency and want to receive error e-mails in addition/instead of your client.
  • prefer_curl – set this to '1' if the server requires you to not use network sockets directly from PHP and instead use the CuRL extension (although if you need this it is likely you actually need to just configure the proxy settings instead, see further below).
  • allow_no_lang_selection – set this to '1' if you want members to be able to leave their language selection as 'Unset' (otherwise normally it'll copy the auto-detected language into their profile or they can change it, but it never stays as unset). This option is useful on multi-site-networks, with each site having a different language.
  • cdn – set this to a comma-separated list of domain name you'd like CSS and images to run from. A random name will be taken for each CSS file/image. You will want some kind of file mirroring setup across all CDN machines, such as an rsync setup or an ocPortal implementation via implementing 'sync_file'.
  • ntlm – set this to '1' if you want to allow automatic logins via NTLM. Note that this is not secure, so only really appropriate for low-security Windows intranets. It also does not work on all networks. If you want true NTLM support you can use the Apache module for it, or what is built into IIS – but it'd be better to use Kerberos as NTLM is deprecated (if you can work your head around configuring it, as it's very hard, especially between Active Directory and the Apache module for it).
  • force_admin_auth – set this to '1' if you want any super-administrator to have to have some kind of authorisation-based login by redirecting them to http://base_url/admin_login/ which presumably you have configured to be a redirect-through that catches logins (Apache only).
  • no_base_check – set this to '1' if you do not want ocPortal to empty caches if the base URL gets changed (this is if the base URL is not defined, and someone accesses from something different). If you set this to '1', you also will want to disable frames (set no_frames to '1').
  • allow_php_in_templates – set this to '1' to enable the undocumented Tempcode 'PHP' directive, and it's short-hand syntax (written like normal PHP long-tags). This allows you to write PHP code inside templates, but please aware there are strong risks associated with this. It means that themes you install may contain PHP code, or people submitting Comcode content may put in PHP code which you could accidentally unwittingly activate when validating content (as it would be validated against your own security credentials).
  • base64_emails – set this to '1' if you want base64 emails to be used. These are more robust (PHP's wordwrapping, which we use to make non-base-64 emails compliant, can be buggy) but some servers do not like them or consider them very slightly more spammy.
  • disable_sunk – set this to '1' if you want to disable the sunk-topics feature. This improves performance a little on MySQL.
  • implicit_usergroup_sync – set this to '1' to enable synching of implicit usergroups (see the advanced members tutorial for more information)
  • disable_password_change_mails_for_staff – set this to '1' if you want staff password edits to not result in emails to users.
  • google_translate_api_key – set this to a google translate API key for the content translation feature to work much better.
  • real_memory_available_mb – set this to the number of MB GD should consider available for image generation, if PHP is lying about it's memory limit.
  • md_default_sort_order – set this to a sort parameter to change the member directory's default sort order.
  • disable_highlight_name – set this to '1' to disable the member name highlighting option.
  • poll_no_member_ip_restrict – set this to '1' if members should not be limited by IP address when voting in poll (i.e. more than one member can vote per household, but we can't stop people registering multiple profiles).
  • commercial_spellchecker – set this to '1' if you want to enable the WYSIWYG editor's spellcheck.net spellchecker.
  • disable_theme_img_buttons – set this to '1' if you don't like the theme image edit buttons that appear to staff when hovering the images.
  • disable_cat_cat_perms – set this to '1' if you want to disable catalogue category permissions.
  • no_confirm_url_spec_cats – set this to '1' if you don't want to have to confirm the category for a new catalogue entry when the category was specified in a URL parameter already.
  • use_true_from – set this to '1' if you want ocPortal to send emails 'from' the user that triggered the message, rather than the website. Usually it is set to 'from' the server to avoid problems with spam filters and uses the true sender address as the 'reply from' address. It is not recommended you turn this on, although it does aid usability if you know the recipient is not using SPF in their spam filter.
  • flow_mode_max – set this to the maximum number of images/videos to show in flow-mode.
  • no_individual_gallery_view – set this to '1' if all images/videos in a flow-mode gallery must be viewed from the flow-mode view (never individually).
  • notification_safety_testing – set this to '1' to enable extra checks to ensure notifications or welcome emails don't get mistargeted/over-sent.
  • no_threaded_buttons – set this to '1' if you don't want the buttons to switch between linear and threaded mode on the forum.
  • allow_admin_in_other_zones – set this to '1' if you want to allow admin and CMS modules to run in other zones (small performance cost).
  • memory_tracking – set this to '1' if you want error mails to go out if a non-admin uses more than 50MB of memory. The check happens during Tempcode output phase.
  • ocselect_protected_fields – a comma-separated list of fields ocSelect cannot work on (above the ones hard-coded as forbidden).
  • memory_limit – set this to a memory limit to override ocPortal's built in one (e.g. "128M"). This will make memory bugs on your server more dangerous, so use at your own risk (a memory usage problem can take down a whole server) – although memory bugs are unlikely given that ocPortal users report if they ever see this error.
  • no_call_home – disable the private sharing of your website URL to the ocPortal developers when the Admin Zone front page loads.
  • alternate_search_join_type – set this to '1' if your database server does 'JOIN' translate table searches intractably slowly, and 'LEFT JOIN' ones fast. This is the exact opposite of the behaviour of most MySQL versions, but we think we have seen a case of this so on some MySQL servers to make catalogue searches tractable you might need to enable this.
  • catalogue_limit_cat_field_load__<cataloguename> – set this to '1' if you want that catalogue to not have all fields loaded on category views, an optimisation that reduces templating flexibility
  • canonical_keep_params – set this to a comma-separated list of keep_ parameters that should be allowed to propagate within search engines.
  • disable_sitemap_for__* – disable sitemap generation for a particular page (e.g. if there's too much data in it and the server can't cope, and the data isn't so important anyway)
  • http_faux_loopback – a regular expression of URLs that may be accessed via direct filesystem reading rather than HTTP loopback. Be very careful with this, as it could seriously harm security. It can improve performance however. Some poor web hosts may also require it (we've only seen one though). It does support PHP scripts, which are given special treatment, via passing through the php-cgi interpreter (file uploads and POST requests not supported). Set via a command such as:

Code

:set_value('http_faux_loopback','^'.preg_quote(get_base_url(),'#').'.*\.(php|jpg|jpeg|png|gif|htm|html|ico|txt|css|js|cur|tar|gz|mp3|mp4|m4v|mpg|mpeg|pdf|svg|swf|ttf|woff|wav|zip|xsd|xsl|xml|webm)\??');
  • cc_sort_date__<catalogue-name> – set this to '1' if you want catalogue category children to be sorted by date rather than title.
  • cloudflare_workaround – set this to '1' if you need to fix the IP address of requests marked as coming from CloudFlare.
  • resize_rep_images – set this to '0' if you do not want uploaded rep-images to be sized down automatically to the standard thumbnail size
  • disable_ssl_for__<domain> – set this to '1' to disable SSL certificate checking for the given domain name. This is not a great idea, but may be necessary if a required service has a broken certificate yet it only supports HTTPS.
  • enable_profiler – set this to '1' if you want to enable the ocPortal profiler, which will write select performance information to data_custom/profiling.(ID).log. For your security you should ensure these files are web-accessible (we will do this by default if we can via the data_custom/.htaccess, but you should take care). The web server needs permissions to save files into data_custom/ (this is possible by default on modern suexec environments). Set to '2' if you want to read Linux performance data, which will then be included in the logging (takes a bit more work by the profiler, assumes Linux and sufficient permissions).

Hidden 'keep' parameters

'keep' parameters are placed inside URLs in order to give ocPortal some extra information when loading a page. Their URL-presence is automatically relayed/preserved in all ocPortal links within the page. To enable a 'keep' parameter, simply append &<name>=1 to the URL (replace '1' if appropriate, but usually we do use '1' to enable). If there are no parameters in the URL and short-URLs are not enabled, use a '?' instead of a '&'.

The 'keep' parameters available are:
  • keep_cache – set to '1' to temporarily enable cacheing or '0' to temporarily disable. You can also use 'cache' so it works on a per-page basis, with the exception of this not affecting the template and language cacheing.
  • keep_no_dev_mode – set to '1' to disable development mode (which only runs if you're working out of a subversion repository anyway)
  • keep_no_ext_check – set to '1' to force the validator to not check dependency files
  • keep_force_htaccess – set to '1' to force the OCF login to go via htauth in precedence over other login methods (e.g. login cookies, sessions)
  • keep_textonly – set to '1' if the 'text only' stylesheet is to be used
  • keep_simplified_donext – set to '1' to temporarily act as if the simplified do-next option is turned on
  • keep_mobile – set to '1' to pretend you're using a PDA
  • keep_has_js – set to '1' to force ocPortal to think you have Javascript (useful if the has-JS cookie isn't saving yet you need to use a JS-based interface)
  • keep_forum_root – see root below; this one works for the forum and is a 'keep' parameter due to how the forum has links going all-over
  • keep_ldap_debug – set to '1' to forcefully show LDAP errors, when suppressing them might normally be wise due to over-sensitivity
  • keep_hide_mail_failure – set to '1' if you want to avoid showing e-mailing errors
  • keep_huge – set to '1' if you want to override the precautionary filesize check used by the JS validator
  • keep_show_query – set to '1' if you want the SQL query used by a search to be echoed out
  • keep_just_show_query – set to '1' if you want ocPortal to echo out the query as above, but then to exit before running it
  • keep_currency – set to an ISO currency code to tell ocPortal which currency you use
  • keep_country – set to an ISO country code to tell ocPortal which currency you're in
  • keep_cat_display_type – set to a number representing the catalogue category display-type to try out (0=entry-tables, 1=lists, 2=matrix)
  • keep_id_order – use this in conjunction with the admin_ocf_groups page to force a usergroup reordering based on the named DB field of your choice
  • keep_backup_instant – set this to '1' if the backup module should do a backup instantly, rather than in the background (useful for debugging, as you can add 'echo's to the backup code)
  • keep_backup_alien – set this to '1' if the backup module should only be backing up non-ocPortal files (i.e. do a backup of the website, but not the software)
  • keep_module_dangerous – set this to '1' to allow uninstallation of modules that are locked
  • keep_preserve_ids – set this to '1' when doing an OCP-merge import, to preserve ID's in the import (and not import duplicated ID's); this is not supported officially
  • keep_theme – set this to a theme name, to temporarily try out a different theme
  • keep_safe_mode – set this to '1' so that where possible, any customised files will be ignored; the default theme will be used
  • keep_fatalistic – set this to '1' if terminal warning errors should be handled as terminal fatal errors (which include stack traces); useful for debugging the origin of an error message
  • keep_firephp – set this to '1' to dump permissions checks that occurred to FirePHP. It only works for authenticated administrators, but if the administrator is using 'keep_su' to masquerade as another user it will work (which is particularly useful for debugging permissions problems).
  • keep_firephp_queries – set this to '1' to dump queries that occurred to FirePHP. It only works for authenticated administrators, but if the administrator is using 'keep_su' to masquerade as another user it will work.
  • keep_show_parse_errors – set this to '1' if you think you have a corrupt PHP file but you can't tell which as your PHP display errors option isn't on (and hence just get blank screens). This will allow ocPortal to generate stack traces for most corrupt files it tries to include. Note another cause of blank screens can be the PHP memory limit being exceeded.
  • keep_send_immediately – set this to '1' if you want to debug newsletter code, and not have newsletters sent in the background.
  • keep_su_online – set this to '1' if you want the user 'keep_su' is used with to also show as online, and for their last online/submit statuses to be updated.
  • keep_no_frames – set this to '1' if you do not want frames to be used.
  • keep_no_minify – set this to '1' if you want to use a Javascript debugger and hence do not want the JS to be minified (unreadable).
  • keep_show_loading – set this to '1' if you want comments inside the HTML source showing memory usage taken up as server-side scripts load
  • keep_no_swfupload – set this to '1' if you don't want the flash uploader to be used
  • keep_avoid_memory_limit – do not put on a memory limit (admins only)
  • keep_memory_over_speed – use less memory for Tempcode
  • keep_no_query_limit – do not place a query limit during development mode
  • keep_on_same_msn – set this to '0' if you are doing an ocPortal site merge import and want to force OCF content to import even if the importer thinks that you are on the same MSN as the other site
  • keep_theme_test – set this to '1' if you are testing lots of themes. It will cause installed theme addons to have their Comcode pages extracted with a special prefix, it will remove that prefix on addon packaging, and page detection will give preference to the prefix for the particular theme you are currently using (so use in conjunction with keep_theme).
  • keep_debug_notifications – set this to '1' if you are debugging the notifications system and therefore need them to be sent before the page output finishes.

The following 'keep' parameters have interface triggers, but are also handy for manual activation:
  • keep_markers – set this to '1' if you want template start/end markers to be output in the page HTML source when viewed in ocPortal
  • keep_novalidate – set this to '1' to force page output validation to not occur
  • keep_su – set this to a username or member ID when logged in as admin, to pretend to be that member. May choose the guest member ('Guest' on OCF by default).
  • keep_theme_seed – set this to kiddie or random or a 6-character HTML colour code, to get dynamic themegen going for your page view (this is very slow, but fun!); you must be staff, with a confirmed session, for this to work
  • keep_theme_dark – used in conjunction with keep_theme_seed; set to '1' if it is a dark seed
  • keep_theme_source – used in conjunction with keep_theme_seed; set to the name of the theme being used as the source
  • keep_theme_algorithm – used in conjunction with keep_theme_seed; set this to 'equations' or 'hsv' to set the theme algoritm
  • keep_print – set this to '1' to render a 'printer friendly' version of the page
  • keep_lang – set to a two-letter ISO language code to tell ocPortal which language to use
  • keep_session – this isn't useful for manual editing, but it is used to note session-IDs when [session-]cookies are not working
  • keep_timezone – this is the timezone code (tz style) to view in

The following aren't 'keep' parameters, but are still useful and otherwise behave in the same way:
  • auth – set to '1' to make ocPortal request HTTP authentication. This is useful for RSS URLs, if you want the feeds to be generated as authenticated.
  • wide – set to '1' if you don't want to show side panels
  • wide_high – set to '1' if you don't show to show panels or the TOP/BOTTOM
  • root – set to a category ID for the current viewed content type to trick the breadcrumbs into showing a 'virtual root'; this can also be activated by browsing to the category you'd like to be virtual root (as staff) and then clicking on the final link in the breacrumb chain (the link representing the current category)
  • start – set to the start number in the result browsing
  • max – set to the maximum number of results to show per-page
  • page/type/id – I hope you know what these ones do ;)
  • kfsXX – this isn't useful for manual editing but people ask what it's for; it's to preserve the browse positions in forumviews, such that when returning, the browse positions are remembered

Extra info.php settings

Setting,

Code

$SITE_INFO['no_email_output']='1';
in info.php will disable emails. This is useful on a development server running with live user accounts.

Hints for making websites for other people

ocPortal is a great platform for web developers. A web developer can build all kinds of sites using ocPortal – from simple new media sites, to social networks, to seeminly-bespoke sites such as property directories.

However, if you're making a website for somebody else it is is important to bear in mind they probably do not want to learn ocPortal like you have.

Here are some hints:
  • You might want to use the 'debranding' feature in the Admin Zone (Tools section)
  • You might want to give the user a non-admin username (e.g. a super-moderator user instead), and then set Admin Zone permissions so that many unnecessary pages are hidden. ocPortal is then smart enough to automatically simplify it's interface to compensate.
  • If you have to hand code a Comcode page with HTML then include the following hint in it: {$,page hint: no_smart_conversion}. This will stop the WYSIWYG editor trying to convert the HTML back into Comcode, which can mess up hand-crafted markup and CSS (normally WYSIWYG only guarantees to preserve style/structure created within itself).
  • If for some reason you don't want the WYSIWYG editor to run for a page (e.g. if it has a Google ad on, that can cause the editor to malfunction) then include the following hint in it: {$,page hint: no_wysiwyg}
  • When deploying make sure to get your canonical URL right. Ask the client whether they want 'www.' in their URL or not. Set up a .htaccess file (http://seoclass.org/canonical-redirects-htaccess-and-seo) that redirects the non-canonical URL to the correct one. This will remove a lot of headaches related to duplicate cookies, bad SEO, confusion, and ocPortal error messages.
  • Always, always, test the e-mails a site gives out. It is very embarrassing if you accidentally customise your MAIL.tpl template in a custom theme and then find e-mails are being sent out of the Admin Zone using the default theme and ocPortal logo. Always save your MAIL.tpl in the default theme, and make sure that the default theme's 'logo/-logo' and 'logo/trimmed-logo' theme images correctly reflect your design. And, test it! If you made complex changes, test in different e-mail programs/webmail-apps.
  • Develop using a staging/developer website, and deploy to live/customer-demo after you've finished all changes. This primarily involves uploading changed files. ocPortal 4.2+ has a great tool for transferring data between ocPortal sites using XML too, if you find you are needing to sync data.
  • If there are separate frontend and backend developers, the frontend developer can do an effective mockup by coding a simple minimodule/miniblock that uses a static array of data passed directly into templates. This way the built CSS and markup is "ocPortal ready" (particularly things like the 'IMG' symbol can be used from the start). This requires the frontend developer to have basic PHP and Tempcode experience.
  • In particular, do not make theme image changes using ocPortal's theme editor, as these are really painful to sync. Make use of ocPortal's automatic theme image detection by simply saving new theme image files into appropriate directory locations; note you will need to clear the caches if you are overriding a default image.
  • Remember when uploading to a live site that you do not want to overwrite customised Comcode pages, or other files that may have since been changed. Be careful what you upload, and keep backups.
  • If you are adding new functionality and write new templates, it is best to save these into the default theme's templates_custom/css_custom directories, so that your functionality works on all themes. If you are overriding default theme templates/CSS, it is then that you save them into your site's theme. A similar rule applies for custom images.

It's overkill to apply the full range of ocPortal coding standards if you're writing PHP code for use on just one website. You shouldn't get into bad habits by skipping any of the conventions but some of our standards are particularly time consuming to meet, and in particular the following time savers can be applied:
  • It is better to have "hackerish" overrides (using the code rewrite facility) than to override whole files. This is because it makes upgrades easy, which is far more important than code maintenance for a one-off ocPortal project.
  • You can almost always assume the site runs one theme and thus save your new templates into the new theme. One caveat is the 'CMS' zone will need to run your theme, and also bear in mind that any files used in outgoing emails must be available from the default theme.
  • You don't need to write everything using language strings.
  • You don't need full MVC. For example, you could code in add/edit functionality straight into modules rather than via a sources file (model).
  • You can make more assumptions than you ordinarily would be able to. For example, you might be able to assume cURL is installed. It is sensible to document your assumptions though, to make sure they continue to be met, or so someone breaking them has an idea that they need to act to change your code.
  • For simple dynamic functionality you can use minimodules and miniblocks instead of full blown object-orientated modules and blocks.
  • You do not need to write PHPdoc comments unless you think other developer's would benefit from them.
  • On some sites you may be able to assume Javascript is enabled, or that accessibility isn't an issue (e.g. on a video site it's unlikely to need to cater for blind users – unless you plan to support audio description). Generally we would advise to be very cautious here, it usually does not take much longer to support full accessibility, and is worth doing routinely. But it is worth us pointing this out because some sites may require particular complex Javascript interfaces and it might be unviable to support Javascript being disabled.

Bear in mind that some sites need maintenance or have multiple people working on them, so you should bear this in mind when you decide the level of engineered design and code documentation to implement for your custom functionality. It is a trade-off between initial development cost, and long-term time savings.

Overriding files

If you change an original ocPortal file for a client project you must save it into the _custom equivalent of it's original directory. E.g. if you change site/pages/modules/calendar.php you need to save into site/pages/modules_custom/calendar.php. Otherwise if the client ever upgrades their website chances are all the customisations you've made would be lost when a newer version of the original file is placed.

This said, It's best to avoid completely overriding default files if possible, so that any bug fixes from upgrades are more likely to work. ocPortal provides some techniques so you can override just stuff you want to change rather than a whole file.
This is explained in the The ocPortal programming framework tutorial (there are two techniques: replacing/supplementing, and progmattic alternation).

If you are considering overriding a file just so that you can add some new functions to it used by one of your new modules (for example, adding a new form_input_something function), consider adding to a new file (or existing file in your module's addon) instead. There is no rule that says similar functions have to go together, and it makes no sense unless they are all core functions – in fact it increases average memory usage to have excess functions defined in core files (each required-up function uses quite a lot of memory).

Conclusion

We're glad you've made it to the end of our Code Book. Thanks for reading this far, and we hope you find ocPortal an effective and enjoyable environment to code for.