Code Book, contents and introduction

The Code Book contains documentation to teach experienced developers how to program for Composr. This page of the Codebook is mostly for sign-posting to the deeper pages of the book.

This guide is not a substitute for learning PHP, HTML, CSS, or other languages. Some introductory material for learning web development is available in our main set of tutorials. There is an excellent PHP book available for free online.

To learn Composr's API, see the phpdoc comments in the source files. The source files are logically named, so it should be relatively easy to get a handle on it all. Alternatively, view the auto-generated documentation.

Technology overview

Composr file structure

Composr's file system is basically split up into:

• Zones (the root directory itself, the site directory, the adminzone directory, the cms directory, the forum directory, and in a way the data directory). Zones contain entry scripts (such as index.php) and page sets. Zones are basically just subdirectories that group pages, making them convenient for creating different 'sections' of the website. Pages may be:
  • Modules (.php files matching a certain class interface). Modules provide a set of related screens; e.g. all the screens for the user portion of the downloads addon are in the downloads module.
  • Comcode (.txt files)
  • HTML (.htm files)
• sources which contain code to be included
• sources/hooks which contain hooks that tie addons together so they can interoperate
• sources/blocks and sources/miniblocks which contain block files. Blocks are plugable units that are can be included within Comcode pages and templates (other software may use the term 'widgets'). They are usually displayed as a box, e.g. a menu, or a list of recent forum discussions.
• themes which contain images, CSS and templates.
• lang which contains language strings.

Composr structure

Composr template briefing

Page output is displayed  by wrapping the primary page output within  the GLOBAL template, prefixed with the HEADER template, and followed by the FOOTER template. The GLOBAL template references panels, and if those panels exist, they will also be included. Typically zones will include a panel_left and a panel_right, so any pages within said zone will be surrounded by these panels.

Composr framework (in-depth)

An introduction to the Composr framework:

• The Composr programming framework
• Manually editing your database with phpMyAdmin (see the "Composr database structure" section which contains details of the directory structure, and database system)

Back-end (more about 'models' and 'sub-controllers')

» See Back-end document (a).
» See Back-end document (b).

Front-end (more about 'views')

» See Front-end document.

Composr addons

In addition to this Code Book, we also have some tutorials with worked examples of making addons:

• Making an addon (part 1)
• Making an addon (part 2)
• Making an addon (part 3)

and information about integrating third-party code:

• Integration of Composr and other installed scripts/applications

Composr terms

Here is a glossary of some of the terms that are used to describe Composr concepts:

• Addon, A defined set of Composr files that work together towards a common purpose. Many addons come with Composr, and even the 'core' of the system is considered to consist of non-optional addons.
• CRUD module, (Create/Edit/Delete module) a module that inherits from the CRUD base class, in order to abstract away standard content management interfaces, speeding implementation and improving consistency. Most content management modules are CRUD module. The CRUD module base class is very rich and provides a lot of optional functionality that CRUD modules can choose to inherit.
• Block, A self-contained section of output that can be used repeatedly by a Comcode or module page. e.g. Poll, or RSS/Atom Feed. By convention, a block could be either a "main block" or a "side block" or a "bottom block", but this doesn't cause Composr to use it differently (it is to help webmasters identify where blocks were designed to be placed).
• Catalogue, A high-level abstraction of a collection of categorised entries. From within Composr you can create these catalogues as you need them. In many respects it is similar to a database with separate "tables", designed to allow non-programmers do what traditionally programmers would have to. The Composr webmaster determines the field names and field types that the entries in the collection (the 'catalogue') will hold. There is no limit for the number of catalogues or catalogue entries which a site may have. The catalogues entries can be organised either in a tree or in a flat-category structure. Often developers have to make a choice of whether to configure and customise a catalogue, or whether to create a new module. It comes down really to whether new interactions, functionality, and/or complex layouts are required – if they are, a new module should probably be written.
• Comcode, A simple mark-up language, for use within Composr. Similar in use and format to 'BBCode'.
• Content, Custom data within the system; the term is used in most contexts as data specifically designed for viewing (as opposed to a member profile, for example, which is automatically updated and is more of a gateway to other information).
• Custom Profile Field (CPFs), A custom field for members. Such fields are supported by some forum/member software including our own Conversr. In Conversr CPFs can be assigned to individual usergroups. CPFs are an important tool on most websites, as it is very common to need to assign extra data to members that is specific to an individual website. CPF data is always entered manually, either by the member themselves, or by staff.
• Do-next manager, An full-screen icon-based menu interface that lays out the available/suggested routes a user may take.
• Emoticons, Little images of faces to represent emotions.
• Entry points, See 'Page-links'.
• Entry scripts, Scripts such as site/dload.php or index.php that are launched directly by URL. These might be called 'front controllers' by some programmers.
• Feedback, A system for collecting and returning feedback from any Composr resource (e.g. rating and posting comments on a download).
• Forum, A place where forum topics sit (and posts site within the topics). Forums may be organised in a tree structure. We do not use the term 'board'  that some software uses.
• Forum Driver, A piece of code that allows Composr to integrate with third-party forum software.
• Fractional Edit, The process of editing a piece of data (usually a title), by interactively modifying it at its point of display.
• Hooks, Elements (special objects) that plug into a module/block to provide different implementations of functionality for that module/block. For example, the stats block calls upon other module's hooks (such as downloads) in order to generate each kind of stat; and the search blocks calls on other hooks to search each kind of content. By using hooks, modularity can be maintained and functionality extended by addition of hooks, not modification of existing code.
• Join, the process of becoming a member.
• Member, a user with an account.Note that in occasional contexts we may refer to members, when actually the member is using the "guest account" – the key point here is that a member is identifiable in at least some way, even if it's just identified to the guest account
• Conversr, the Composr forum/member system (optional).
• Pages, These are just pages a user might wish to view; they can be:
  • 'Comcode pages' – written in Comcode
  • 'HTML pages' – written in HTML
  • modules pages – pages, that belong to a modules.
• Panels, These are pages (usually Comcode pages) that are named with the prefix panel_. They may be referenced in the templates using the 'LOAD_PANEL' symbol. The default Composr templates automatically place panels named panel_left or panel_right.
• Page-link, These are paths formatted like zone:page:screentype:id:param=value(:...) that Composr uses for detailing links. They are like URLs, but local to a Composr website. Page-links are converted to URLs and this conversion sometimes adds extra URL parameters (for instance, any parameters prefixed keep_ are propagated across screens). Entry points are a special case of page-link – entry points are the page-links to screens that modules provide regardless of the current state of the modules content (e.g. the catalogue index will always be there – it is a stable entry point into the system).
• Personal post, a post either within a private topic or within a normal topic, that can only be seen by the sender, the recipient, and administration staff
• Private topic, a topic only seen by a select group of members (currently, the initiator and target members)
• Points, Members of a site can earn 'points' by participating in site activities. The site administrator can adjust the value of different activities. Members can then gift these points to each other or redeem them at the Point Store.
• Point Store, The place where members can spend hard-earned points on gifts such as e-mail addresses or community billboard messages
• Standard box, The type of box that wraps most Composr content, like side-blocks (e.g. 'Site statistics', 'Users online', 'Shoutbox', etc.). There are different styles of standard box.
• System, A large aspect of Composr that has an influence spanning multiple files (e.g. Point Store system, Addon system, Award system). This is an informal term – addon is used more formerly and refers to a defined set of files.
• Tempcode, An intermediary format between Comcode and XHTML, used for transmission and storage of screens in Composr. Also, the written programming language used in templates. The two things are different representations of the same thing.
• Theme, A set of templates, images and CSS style-sheets that can be used on a website to completely change the layout, look and feel of the website. Different themes can be used concurrently by many members, with no impact on the system
• Notifications, The process of tracking content for reply via e-mail notification. In other words: you can mark topics for notification and when a new reply is posted, you will be notified by e-mail of its presence.
• User, Someone visiting a Composr site, that may or may not be a member.
• Usergroup, sometimes called a group, this is a group of members and is how roles are implemented. Each usergroup is configured with its own permissions and nothing is hard-coded. Usergroups may be configured as 'Super administrators' which have full access to everything, bypassing permissions. Members may be in multiple usergroups, and receive the best combined permissions from all of them.
• Whisper, the process of creating a personal post embedded within a public topic (this is used to carry on entirely private conversations, and allow members to whisper secret messages to each other inside a public topic)
• Zones, Different areas of a website, each with its own security levels, layout and feel. e.g. The Admin Zone is a different zone to the Site Zone. They are separated into a subdirectories of the main site (like subdirectory site for the 'Site' zone and the subdirectory adminzone for the "Admin Zone" zone). For the special "root" zone, called the "Welcome Zone", the files are stored in the main directory.

The following Composr concepts are used to describe content:

• Category. Categories hold entries, or sometimes, other categories, or both; they themselves tend to be designed for organisation or navigation rather than direct viewing. Galleries, forums and forum groups, are all kinds of categories; even a topic is a category in some contexts, as it holds posts.
• Entry. An entry is a piece of content.
• Resource. A resource is a very general term that may mean anything from entries to categories to files.

'resource' is often used loosely, and 'category' and 'entry' are used differently depending on the context. This is not a design flaw, but merely indicative of the diversity of context in Composr and the difficulty of being consistent across different contexts (e.g. a topic is a category for posts, but really we would usually consider the categories of the forum system to be the actual forums).

We use the formal term content type to refer to a type of content (obviously). Examples: download, image, video. We also use the term resource type when being more broad. Typically particular addons will provide different content/resource types – but there's no formal link. An addon could provide no new content/resource types, or more than one.

There are many other terms in Composr that belong to certain addons (such as 'Download' or 'Wiki+'), but these won't be explained here.

Feature architecting standards, and implementation notes

Composr contains many "cross-cutting" features that are often present in different areas of the system. These need to be individually implemented/referenced all throughout the code. These features are:

• CRUD/CMS functionality (this will be provided to you when you write your CMS module to inherit from the standard CRUD module code. Most Composr CMS modules are CRUD module)
• SEO metadata keywords/description (instructions for implementation provided in this book)
• Feedback: rating, commenting, trackbacks (instructions for implementation provided in this book)
• Permissions (instructions for implementation provided in this book)
• Virtual roots (see how breadcrumb code for the news addon handles virtual roots – it provides the capability to define them, and also applies them in the way it decides the root of a breadcrumb trail)
• Edit lists (filtered according to what the logged-in user can actually see) (just define a create_selection_list_whatever function like other similar functions)
• Do-next interface (instructions for implementation provided in this book)
• Blocking guests trying to edit something owned by Guest (a bug if it isn't, but it would be good to try and abstract this)
• Ditto blocking editing interface for something you don't have category access to
• Attachments, Comcode, Multi-language support (instructions for implementation provided in this book)
• Validation, validation-required e-mails, Non-validated warnings, and permissions to determine who may view non-validated content, and a hook to identify all non-validated resources (see how it's done in existing modules, it's quite straight-forward – just identify the lines of code that involve validation and basically copy&paste them to the right spots in your own code)
• Control actions links (see the {+START,INCLUDE,STAFF_ACTIONS} code in DOWNLOAD_SCREEN.tpl)
• Logging (use the log_it function in your model code, for adding, editing, and deleting)
• Mass action, and policy for deletion of categories (implementation varies, but consider what happens to a categories entry when you delete that category)
• View counts and edit dates (implementation varies, but you should track them in your tables and pass them into templates)
• Newsletter "added since" hooks (just implement a hook)
• Importing (define an import-type in the admin_import module code, and implement code for this import-type in all the import hooks hook)
• Search (just implement a hook)
• Preview support (just implement a hook)
• AJAX fractional-edit support where appropriate (see how CMS CRUD module's use INTEGER_MAGIC_NULL and STRING_MAGIC_NULL, and how their view templates use the FRACTIONAL_EDITABLE directive)
• Rep-images (implementation varies, but basically these are icons for a module's categories)
• RSS (just implement a hook, and call set_feed_url in the code when viewing what the RSS feed subscribes to)
• Awards (just implement a content-meta-aware hook)
• Possible others I've forgotten to list

General approach to coding standards

If you bought a watch, and the watch wasn't quite a perfect circle, this would impact your perception of its quality, even if the watch worked perfectly. Or, if you opened it up to do some maintenance, and it looked messy inside, you'd lose your respect for the skills of the watchmaker.

This is why we insist that core Composr programmers make everything (attainably close-to / within-reason) perfect, even at the code level. That is, applying sufficient care and attention to detail when coding such that your code looks almost poetic, guided by an inbuilt sense for quality, tidiness, and consistency. It doesn't really have to take any longer to code like this – it's more that if you wrote something that didn't have and continue beauty, you'd be instinctively repulsed by that code you wrote.

This applies to maintaining consistent code formatting, correct English spelling and grammar, and general consistency over-all, so that everything flows cleanly.

On a practical level:

• This makes the code nicer for all programmers to work in, it all flows really smoothly – they can very quickly scan over the code and pick up immediate sub-conscious cues from how things are formatted, without having to work out what the rules of styling are (or worse, the rules of English grammar are) for particular spots of the code-base.
• Other programmers who have built up this automatic repulsion for ugliness (in order to refine what they expect from themselves) will require you to also maintain similar standards, lest they feel repulsed.
• It also helps the programmer put even more care into things the user does end up seeing. It's unrealistic for a human programmer to make things good in some places and bad in hidden places – the badness will just start leaking everywhere – it's better just to make it good, period.

You can hear it from Steve Jobs too (taken from his official auto-biography by Walter Isaacson)…

Walter Isaacson said

One of the most extreme-and telling-implementations of that philosophy came when he scrutinized the printed circuit board that would hold the chips and other components deep inside the Macintosh. No consumer would ever see it, but Jobs began critiquing it on aesthetic grounds. "That part's really pretty," he said. "But look at the memory chips. That's ugly. The lines are too close together."

One of the new engineers interrupted and asked why it mattered. "The only thing that's important is how well it works. Nobody is going to see the PC board."

Jobs reacted typically. "I want it to be as beautiful as possible, even if it's inside the box. A great carpenter isn't going to use lousy wood for the back of a cabinet, even though nobody's going to see it."

You may be used to a culture of working with a lower level of quality. If so, don't be pulled down by the standards of programmers around you. Be better than them and set an example. Be really proud of the beauty of your own code, and make sure you can be really proud of the code of others on the same project – know that by writing beautiful code you are a true artisan programmer, not just a code hacker. It shouldn't really be possible to quickly say "this code was written by Bob, you can see his style in the way it is laid out", the project should feel as one cohesive beautiful thing.

You may or may not agree with the particular current coding standards within Composr. Programmers never agree on these things. However, the mature thing to do is to adapt to whatever the agreed standard is, and if you think it should change, make a case, rather than just ignoring pre-existing standards. Composr coding standards are certainly subject to review, but at any point in time should be met absolutely.

Of course, with all things, a sense of balance is important. An instinct/habit for quality should not need to come at the cost of maintaining a productivity. And, all things that are engineered have to be subject to trade-off of competing concerns, rather than rigid standards that may not be appropriate in certain very specific situations.

Troubleshooting

» See Final document.

Tips

» See Final document.

Advanced deployment and customisation

» See Final document.

Conclusion

» See Final document.

Resources

The documentation and tools on the Composr website may be out of date between Composr versions.
For the latest resources, see our repositories and work tools:

• GitLab (contains Composr, unit tests, all unbundled addons and support tools)
• Tracker

Feedback

Have a suggestion? Report an issue on the tracker.