[title sub="Written by Chris Graham (ocProducts)"]Composr Tutorial: The Composr programming framework[/title]

Composr is not just a web application, but also a programming framework. Composr defines a very large, fully documented, API, and has numerous mechanisms for the addition of code. Programmers are able to cleanly extend or override any aspect of the system, to enhance Composr or bend Composr in any area necessary.

It should be noted that Composr can be heavily customised without any programming, via editing the templates, but this will mostly only adjust layout and appearance, rather than adding-to or modifying Composr behaviour. Wherever possible we make things work on a configurable level though (such as [concept]Comcode page[/concept]s, or [concept]Catalogue[/concept]s) so users with specific needs do not need to hire-in-help or learn programming to fulfil them for such cases.

It is also important to note, that this is a tutorial for programmers, and that programming tasks are inherently technical, and requires some combination of some of these elements:
 - education
 - experience
 - a technical mind

This tutorial covers day-to-day aspects of making and installing addons, especially embedding or overriding code. For a more exhaustive document describing ground-up Composr programming, see the [page="_SEARCH:codebook"]Composr Code Book[/page].

[contents]decimal,lower-alpha[/contents]

[title="2"]Open Source[/title]

Composr is Free Software and Open Source, meaning it's completely open and customisable.

[title="2"]The Composr API[/title]

[media width="150" description="Composr has a well documented API (code)" float="right"]data_custom/images/docs/tut_framework/framework_api.png[/media]
[media width="150" description="Composr has a well documented API (compiled out)" float="right"]data_custom/images/docs/tut_framework/framework_devguide.png[/media]
Every [concept]function[/concept] in Composr is documented using a system based on [concept]phpdoc[/concept] (itself based on 'javadoc'). One purpose in this documentation is that it makes it easy for a programmer to program for Composr: they have a few hundred fully documented Composr functions available to them.

With phpdoc and the function header-line itself, every function has the following:
 - A description
 - A list of all parameters:
  - The code-name of the parameter
  - The type of the parameter (including whether false [~type] or null [?type] values are accepted)
  - A description of the parameter
  - Whether the parameter is optional
 - The return type (if any), and a description of it
Of course, the actual function code is also available. All this information is presented as a part of the [url="API guide"]{$BRAND_BASE_URL}/docs/api/[/url] which is precompiled using phpDocumentor. We also have the [page="docs:codebook"]Code Book[/page] which includes a lot of additional information about programming for Composr, and is one of the actual sources of information for ocProducts staff; it includes a lot of important and expert information, including guidelines for writing secure code.

[title="2"]Extending Composr[/title]

This section provides a high-level overview of Composr's core programming. Much more thorough documentation is in the Code Book.

Composr is not just a lump of code like most software: a lot of effort has gone into structuring the system so that code may be cleanly hooked in, via various methods.

[media thumb="0" framed="0" float="right"]data_custom/images/docs/advantage.png[/media]
These methods include:
 - Overriding of existing source files with modified versions. Every directory that holds effective source code (as opposed to the shell files such as [tt]index.php[/tt] or [tt]dload.php[/tt] that just provide entry points into Composr) support a system of overriding: in other words, every Composr source code file can be replaced with a customised version, cleanly, without damaging the existing code and without the changes getting buried. This is done via elevation of a file to a [tt]_custom[/tt] suffixed directory of where the file originally was
 - A Composr editor (the code editor) is provided to provide a simple (password protected) editor for your site, and does this automatically
 - New [concept]Module[/concept]s can be added just by writing a file and placing it in the modules_custom directory for the zone that it is to run in. In addition, there is support for a simple form of module, called a [concept]Mini-module[/concept] that can be added in a similar way, but is much easier to write for amateur programmers
 - New [concept]Block[/concept]s can be added just by writing a file and placing it in the [tt]sources_custom/blocks[/tt] directory. In addition, there is support for a simple form of module, called a 'mini-block' that can be added in a similar way, but is much easier to write for amateur programmers
 - New [concept]API[/concept] source code files can be added just by writing a file and placing it into the [tt]sources_custom[/tt] directory
 - 'Hooks' to add features into a hooked area can be written. For example, a 'search hook' can be written by writing a file and placing it into the [tt]sources_custom/hooks/modules/search[/tt] directory

[title="2"]An example of a new module[/title]

[media width="150" description="Composr language files for the tester addon" float="right"]data_custom/images/docs/tut_framework/framework_file_language.png[/media]
[media width="150" description="Composr templates for the tester addon" float="right"]data_custom/images/docs/tut_framework/framework_file_templates.png[/media]
As a part of testing ocPortal 2.5 (along time ago now), we wrote a new custom module that provided a quick way for all testers and developers to progress for the testing/bug-fixing process in a collaborative fashion. The module allowed the addition of tests, and assigning of those tests to members in a testing usergroup. It had a security system, so that non-testers could not access the system, and so that security could be defined to determine which testers had write access to edit tests. It also had forum integration, so that bug report topics could automatically be created and associated with a test.

All this was done, without touching the core Composr code. The Composr API made all the integration (security, members, usergroups, forum topics, etc) very easy. It is not the intent of this tutorial to explain exactly how this module was written, but some screen-shots have been attached to illustrate where new files were created in order for it to work.

The process of writing the module went along this basic route:
1) The functionality of the module was decided upon, and tests designed that would allow us to test all this functionality worked once the module was finished (we usually define tests first, write a module in one go, and then carry out all the tests: it usually is the most efficient and robust way for us to write the code)
2) The database schema was designed for the module, by consideration and then simply listing of the tables and fields that would be needed to adequately (and consistently with our standards and the guidance of our expertise)
3) The shell for the main module was written, based on that which all other modules (other than mini-modules and abstracted CRUD modules) uses
4) It was decided what screens that module would use, and these were all assigned code-names. Functions were created for these code-names, and the run function was filled in to call them up according to the [tt]type[/tt] parameter (as featured in all other modules)
5) Install and uninstall functions were written for the module, according to the database schema
6) Add, edit, and delete backend functions were written for the data of the module
7) Add, edit, and delete screens were written for the data of the module (including definition of associated language strings for the standard Composr field inputting interface [wherever possible, referencing existing ones, to reduce the burden for anyone wishing to translating the module once we release it publicly as a Composr addon])
8) The screens for the main interface were written
9) The module was tested, and then deployed

[media width="150" description="Composr module for the tester addon" float="right"]data_custom/images/docs/tut_framework/framework_file_module.png[/media]
The new module, approximately 1,000 lines of code (PHP and XHTML) was completed within one long day, and in active use soon after. It is a moderately advanced module, and was of great help to our organisation. Naturally, it would take a lot longer for an inexperienced Composr programmer to create this module, but the point is that it was made a lot faster due to our API and extension infrastructure: without these, a custom application from scratch might have taken a full week to develop. The alternative to a custom module would have been a third party application, but this would not have provided us with the level of integration we demand for our systems (not to mention compatibility with things as they are currently, and how they might change in the future). Professional developers are available for implementing systems built around on Composr (as third party developers may be also).

Some of the API functions used in the module include:
 - [tt]create_table[/tt]
 - [tt]add_privilege[/tt]
 - [tt]query_select[/tt]
 - [tt]do_template[/tt]
 - [tt]do_lang[/tt]
 - [tt]has_privilege[/tt]
 - [tt]build_url[/tt]
 - [tt]assign_refresh[/tt]
 - [tt]get_param_integer[/tt]
 - [tt]get_member[/tt]
 - [tt]member_group_query[/tt]
I'm sure you can see why such a function library (and the pre-written subsystems that exist behind them) speeds up development considerably. All this is built into Composr by default, so no libraries need hunting down, installing and managing to achieve all this.

[title="2"]Overrides[/title]

There are 3 different kinds of PHP override in Composr:
1) Extending a module
2) Replacing/supplementing a file
3) Replacing/supplementing a file, [b]with support for programmatic alteration of the original code[/b]

It's important to note that as well as overrides you can place entirely new files in the [tt]*_custom[/tt] directories, and Composr will be able to reference them as if they were original files.

All these techniques are handled inside the Composr [tt]sources/global.php[/tt] file. If you are a good programmer but still can't work out how to do all this stuff (it's easy once you know how, but a bit unorthodox compared to normal techniques), look at the code of this file. As [tt]sources/global.php[/tt] is the file that does the magic it's the only file that you can't override; it is therefore kept minimal, hence why we have a [tt]sources/global2.php[/tt] which picks up where [tt]sources/global.php[/tt] leaves off.

[title="3"]Extending a module[/title]

This form of overriding works via class inheritance. All you need to do is to make a [tt]modules_custom[/tt] directory version of an original [tt]modules[/tt] directory file, with two differences:
1) Instead of just naming the module class [tt]Module_<modulename>[/tt], rename it and inherit using [tt]Mx_<modulename> extends Module_<modulename>[/tt]
2) As this works via standard class inheritance you are at liberty to, and should, only redefine methods in your override when those methods are actually different from the original ones. i.e. start with a shell of a class and only redefine methods that you are actually wanting to change

[title="3"]Replacing/supplementing a file[/title]

If you override a file to the [tt]sources_custom[/tt] directory then that file will essentially be overlaid on top of its equivalent in the [tt]sources[/tt] directory. (You can use this technique in other [tt]*_custom[/tt] directories too, such as [tt]modules_custom[/tt] directories -- although in this case it is less useful, as there is less granularity due to a module only containing a single class)

You can redefine any existing function or class, and you can define new functions or classes. Composr does some magic so that you can reference the old versions of the functions or classes by prepending [tt]non_overridden__[/tt] to their names (e.g. [tt]example_function[/tt] would become [tt]non_overridden__example_function[/tt]). This is very useful if you can write your overridden function without having to completely replace the original function. For example, if we just want to add some logging to [tt]example_function[/tt]...
[code="PHP"]
function example_function($a,$b)
{
	some_logging_function('call to example_function with ' . $a.' and ' . $b);
	$ret = non_overridden__example_function($a,$b);
	some_logging_function('leaving example_function returning ' . $ret);
	return $ret;
}
[/code]
It is also very useful for classes because it allows you to create a subclass of the original, without changing its name (which would break Composr, as Composr expects a certain fixed name for its classes). For example:
[code="PHP"]
class example extends non_overridden__example
{
	function mymethod($a,$b)
	{
		some_logging_function('call to example::mymethod with ' . $a.' and ' . $b);
		$ret = parent::mymethod($a,$b);
		some_logging_function('leaving example::mymethod returning ' . $ret);
		return $ret;
	}
}
[/code]
This is a great technique for making changes to forum drivers.

One word of caution -- if you are not supplementing a code files [tt]init[/tt] function, then you will want to strip out the init function from your override, otherwise both it and the original will be called in sequence. This is unavoidable, because the modified file is loaded first and thus cannot call the original init function itself -- and thus responsibility for that stays with the Composr code. There are two exceptions:
1) If your override contains every class or function the original file has (i.e. you overrode the whole file by copy&pasting) then the original init function will not be called as Composr assumes you copy&pasted all that code into your own init function.
2) If you want a partial override but don't want the original init function to run, you need to use programmatic alteration to mask the original init function. This is explained in the last paragraph of the next section.

[title="3"]Programmatic alteration[/title]

Sometimes you want to override something in the middle of a function and thus there is no neat way to do it without copy&pasting the whole function.

In theory, good software architecture (modularity etc) is meant to prevent this situation happening, but in practice:
 - its completely impossible for an original programmer to predict what changes someone might want to make to their code
 - programming languages have no inbuilt features to work around problems stemming from this lack of foresight (even the most heralded OOP techniques cannot do it)
There are 3 ways this problem could be solved:
1) Alter the original Composr code. This is a [b]very bad idea[/b] because you then have a very hard time identifying your changes, and performing even patch upgrades
2) Override whole functions. This is a [b]bad idea[/b] for non-trivial functions because it makes feature/major upgrades much more problematic
3) Use a mechanism that goes beyond what programming languages can normally do

We took approach '3', and thus have written a special feature into Composr for it. Its admittedly a bit messy but in practical terms it works almost flawlessly.

In Composr it works as thus:
1) First you create a [tt]sources_custom[/tt] file
2) Next you define an init function of this file. If you were overriding [tt]sources/example.php[/tt] you would define a [tt]init__example[/tt] function. If you were overriding [tt]sources/forum/example.php[/tt] you would define a [tt]init__forum__example[/tt] function (i.e. any slashes get changed to [tt]__[/tt] in the function name)
3) The init function should take a single parameter, and return something based upon that parameter. The value of this parameter will be the string value of the code you're overriding, after any function/class renaming has happened (see 'Replacing/supplementing a file' above). i.e. your function is taking a huge lump of PHP code as its parameter. In-between taking the parameter and returning it you can perform any changes you like. You can use any string functions like [tt]preg_replace[/tt] or [tt]strpos[/tt]; or use the handy Composr [tt]get_function_hash / insert_code_before__by_linenum / insert_code_after__by_linenum / insert_code_before__by_command / insert_code_after__by_command / remove_code[/tt] functions

[media thumb="0" framed="0" float="right"]data_custom/images/docs/dont.png[/media]
There is one important rule when it comes to programmatic alteration: you are not allowed to call [tt]non_overridded__init__<whatever>[/tt] from your [tt]init__<whatever>[/tt] function. You cannot do this because the PHP code containing that function has not been evaluated at that point and thus the function is not yet defined. If you try and do it then Composr will disable programmatic alteration and hence revert to the more basic 'Replacing/supplementing a file' technique. Composr will automatically call [tt]non_overridded__init__<whatever>[/tt] as soon as it becomes available so you do not need to copy&paste its contents to your own function. If you do not want [tt]non_overridded__init__<whatever>[/tt] to be automatically called then you need to rename it in your own init function so that Composr cannot find it.

[title="2"]Exporting addons[/title]

[surround]
[media width="150" description="Exporting an addon (2)" float="right"]data_custom/images/docs/tut_framework/framework_export_2.png[/media]
[media width="150" description="Exporting an addon (1)" float="right"]data_custom/images/docs/tut_framework/framework_export_1.png[/media]
{!addons:DOC_ADDONS}
[/surround]

[surround]
[media width="150" description="Importing an addon (2)" float="right"]data_custom/images/docs/tut_framework/framework_import_2.png[/media]
[media width="150" description="Importing an addon (1)" float="right"]data_custom/images/docs/tut_framework/framework_import_1.png[/media]
You will only be able to export files into an addon from directories that are 'allowed' to contain new or modified files. For example, the [tt]sources[/tt] directory should not be modified, but the [tt]sources_custom[/tt] directory may. This is part of the file override system Composr employs: modified versions of old files or entirely new files should be placed in the custom version of a directory so that it is clear they are non-original, and will not be automatically overwritten during upgrade. There are a few directories that have no [tt]_custom[/tt] equivalent, and therefore you may export files to a mod from these.
Overridden PHP files may override on a per-function/per-class level. In other words, if you overrode a PHP file then you could make your [tt]sources_custom[/tt] file such that the only functions/classes it contains are the ones that you changed.

Addon TAR files contain an [tt]addon.inf[/tt] file that specifies the metadata for an addon. Addons bundled in the Composr git repository use [tt]addon_registry[/tt] files instead, which is a bit cleaner, and also presents the possibility of install/uninstall code directly attached to an addon rather than an addon's blocks or modules (if it even has any). If you want to manage your addon using a registry file then when you choose to export your addon select only that registry file: the metadata will be taken from that file, as well as auto-selecting all the files of the addon. Once an addon is installed the registry file takes precedence of any metadata stored in the database.

The date/time of the exported addon TAR file will be the date/time of the most recent file within it.
[/surround]

[title="2"]The Code Editor[/title]

[surround]
[media width="150" description="Using the code editor" float="right"]data_custom/images/docs/tut_framework/framework_code_editor_3.png[/media]
[media width="150" description="Choosing a code file to edit" float="right"]data_custom/images/docs/tut_framework/framework_code_editor_2.png[/media]
[media width="150" description="A password is obviously needed to use the code editor" float="right"]data_custom/images/docs/tut_framework/framework_code_editor_1.png[/media]
Composr provides a very simple code editor for editing of existing Composr code files, or creation of new files. The code editor has inbuilt, automated, support for the Composr file override system: editing an original Composr file will save the edited version in the equivalent [tt]_custom[/tt] suffixed directory where possible.

Access the code editor from Admin Zone > Tools > Code editor.

The code editor is very useful for making ad hoc changes to a live-site, but is not intended as a full development environment.
[/surround]

[title="2"]PHP programming help[/title]

[surround]
[media width="150" description="PHP has an excellent reference manual" float="right"]data_custom/images/docs/tut_framework/framework_phphelp.png[/media]
It is beyond the scope of the Composr documentation to explain how to program in PHP (although we do have a stab at it in the [page="_SEARCH:tut_programming"]Introduction to programming tutorial[/page]), or other languages that are used such as SQL or HTML. PHP includes an excellent reference guide, and there are many good tutorials on the web for HTML. Composr uses a very minimalistic form of SQL, and usually code does not need to use any directly, due to our database abstraction functions, so this should not be a problem.

The Composr API guide does actually include a PHP reference that defines a subset of PHP that we allow ourselves to use in Composr. The subset is specially limited so as to avoid PHP version conflicts, and the need for PHP extensions that may not be installed.
[/surround]

[title="2"]Other advantages to our framework[/title]

[media thumb="0" framed="0" float="right"]data_custom/images/docs/advantage.png[/media]
If you still are not convinced that Composr is the right choice for you, consider some of these:
[list]
 [*] There are many frameworks for creating web applications available (such as Typo3 or Ruby-On-Rails), but few true frameworks like Composr are also 'out of the box' systems.
 [*] In addition to the above, few pure frameworks provide the dimensions of functionality that Composr can provide.
 [*] Composr's framework has excellent security. For example,[list]
  [*] the database abstraction system allows relational databases to be accessed without concern of SQL-injection;
  [*] The template system is written to make XSS injection virtually impossible (where the vast majority of programmers write code that is full of XSS vulnerabilities, without even knowing what they are).
 [/list]
 [*] Composr's framework is of professional quality, managed by a single company that keeps every aspect of it to high standards, and compatible with each other. If you opt for frameworks which are incomplete, and end up using addon libraries to achieve additional functionality, you will soon realise, both immediately and after-time, that the lack of central control results in:[list="1"]
  [*] major compatibility problems;
  [*] messy feature overlap;
  [*] inconsistent philosophies for code;
  [*] inconsistent philosophies for documentation;
  [*] a large number of agents to contact for different kinds of problem;
  [*] no central authority for you to agree licensing with, should you need to do so (and this is not unlikely, as many projects flower to unexpected ends);
  [*] orphaned projects that die
 [/list]
[/list]

[concepts
 1_key="API"      1_value="Application Programming Interface: functions in libraries (in Composr's case, files under sources/) intended for common use by other code."
 2_key="phpdoc"   2_value="A system for documenting function APIs, based on Javadoc"
]Concepts[/concepts]

[title="2"]See also[/title]

 - [url="PHP documentation"]http://www.php.net/docs.php[/url]
 - [url="MySQL documentation"]http://dev.mysql.com/doc/mysql/en/[/url]
 - [page="_SEARCH:tut_programming"]Introduction to programming[/page]
 - [url="API guide"]{$BRAND_BASE_URL}/docs/api/[/url]
 - [page="_SEARCH:codebook"]Composr Code Book[/page]
 - [url="PHP website"]http://www.php.net[/url]

{$SET,tutorial_tags,core_addon_management,code_editor,Development,PHP,expert}{$SET,tutorial_add_date,Aug 2008}{$SET,tutorial_summary,Composr is not just a web application, but also a programming framework. Find out how the puzzle pieces fit together.}[block]main_tutorial_rating[/block]
