ocPortal Tutorial: Comcode and the attachment system

Written by Chris Graham, ocProducts

Comcode is the ocPortal 'mark-up language'. Using Comcode you can add rich text to your website with minimal effort, but with maximum control. Unlike HTML, you do not need to use any complex syntax unless you wish to create special formatting effects, or embed dynamic elements. Comcode does a great deal of work itself to make things so easy for you – behind a simple, intuitive, and easy to use set of syntaxes is a very sophisticated 'parsing' (parsing is the name for the technique of conversion of one language into a much more 'finicky' lower level language, HTML in this case) system. Comcode adds a lot of power that HTML cannot itself provide; for example, with Comcode you can easily add an automatically-generated table of contents, or draw on the power from any of our pre-designed dynamic 'blocks' (blocks are described in our 'Advanced Pages of information (via Comcode)' tutorial).

Many fields in ocPortal support Comcode, and 'Comcode pages' may be used to layout pages and menus of your site without having to do complex template editing, and without needing to use a restrictive layout editor. The front pages and panels of ocPortal are, by default, Comcode pages.

Those familiar with forum systems may see that Comcode is similar to BBCode in some respects.

Table of contents

ocPortal Tutorial: Comcode and the attachment system

Syntax

Comcode is written and laid out as plain-text. Within this plain text certain syntaxes can be used to make changes or additions:

emoticon codes may be used (for OCF, these are listed in the 'The ocPortal emoticon system' tutorial)
Comcode tags may be used to change content, such as [b]text[/b] to make some text bold
Comcode tags may be used to add content, such as [block]main_feedback[/block] to add a dynamic comments box
horizontal lines may be added by placing a few '-'s on their own line
HTML style entities can be use to place special characters inside the text
member profile links can be placed by typing {{username-goes-here}}, or {{?username-goes-here}} to show extra details when the mouse is hovered over (OCF only)
Wiki+ page-links can be placed by typing [[pagename-goes-here]], or [[pagename-goes-here#anchor]]
table syntax (described in separate section)
list syntax (described in separate section)
Tempcode symbols and directives may be used, such as {$USERNAME} to display the username of the current user (described in separate section)
certain shortcuts may be used, such as (c) for © (described in separate section)

The following functions are also performed automatically by the Comcode parser:

Hyperlinks may be written directly, and are automatically detected
Long text is forcibly word-wrapped if it would break layout

There is also an XML version of Comcode, which is described in further detail in the 'Advanced Comcode' tutorial.

Table syntax

Table syntax is written as in the following examples…

Code


{| This is the table summary
! Header 1, row 1
! Header 2, row 1
|-
| Cell 1, row 1
| Cell 2, row 1
|-
| Cell 1, row 2
| Cell 2, row 2
|}

or in reduced form,

Code


{| This is the table summary
! Header 1, row 1 !! Header 2, row 1
|-
| Cell 1, row 1 || Cell 2, row 1
|-
| Cell 1, row 2 || Cell 2, row 2
|}

List syntax

The example in action

To create a list, you just need to start typing elements of the list using the list syntax. A line that is in the first level of a list is identified by the line starting with ' - '. Subsequent lines that have the same prefix are shown as subsequent items in the same list. If you wish to extend the list to a second level, just add the first line of the second level with two spaces before the hyphen, so that the line starts with ' - '; of course, you should start a second level of a list somewhere within the first level. Your list may have as many levels as you like, just by adding extra spaces in the lines at a certain depth. Be careful to not jump from, for instance, a depth of 1 straight to a depth of 3, as this will result in a Comcode error. This all sounds more complex than it is, so I will give an example to show how in fact, it is really very easy to do:

Code


- 1
 - 2
  - 2.1
   - 2.1.1
  - 2.2
 - 3
  - 3.1

See how simple it is: the number of spaces before the hyphen identifies the list level, the hyphen identifies it is a list, and then after a space (to make it look better when writing it) comes the actual line of the list.

You can also create ordered lists…

Code


Easy as:
a) a
b) bee
c) sea

Easy as:
1) one
2) two
3) three

If you need a list element to span multiple lines, you'll need to use the Comcode 'list' tag instead.

Shortcuts

There are some short-cuts for use to use:

(c) for ©
(r) for ®
-- for –
--- for —

Symbols and directives

Symbols and directives from Tempcode may also be used in Comcode. For a list of symbols/directives, see the 'Tempcode programming' tutorial. It is rare that you will want to include these as they are primarily designed for usage from templates. However, sometimes they can be useful.

Tag syntax

Tags are written as in a way similar to HTML, except using the '[]' brackets instead of the '<>' brackets, and a slightly more user-friendly notation.
All tags have an opening tag, written [tag], and a closing tag, written [/tag]. The text between the tags is either:

something the tags modify
an otherwise critical parameter for the tags; for example, for the 'block' tag, it is the name of the block

Tags may also take other parameters rather than the tag 'contents' (what the tag has 'embedded'). These are written in like as follows:
[tag a="a-value" b="b-value"]contents[/tag], where 'a' and 'b' are merely examples of named parameters, of which there can be any number. Often tags have a special parameter that is of critical importance, that we name 'param'. A short-hand for writing:

Code


[tag param="value"]contents[/tag]

is writing:

Code


[tag="value"]contents[/tag]

This only applies to the 'param' parameter, and does not need to be used if you do not want to.

If a tag is referenced that does not actually exist, then it won't be read as a tag: it'll just display as plain text.

If you need to include the " symbol inside a tag parameter, you can put it in as \" (e.g. [quote="Mr \"Happy\""][/quote]).
Also, if you need to literally display a tag without it being parsed, you may type \[ for the opening bracket (e.g. \[i do not want this as italics]).

WYSIWYG

ocPortal provides a WYSIWYG editor for those who would rather not type Comcode directly. You may mix in raw Comcode with the normal formatted text of the WYSIWYG editor if you wish; this is necessary if you need to insert things that don't have a regular appearance, such as blocks.

The HTML produced by the WYSIWYG editor is normally automatically converted back into Comcode (unless the "Convert HTML to Comcode" option is disabled). However, if a full conversion is not possible, the Comcode 'semihtml' tag is used in order to allow a partial conversion. If this is the case, the remaining HTML would then be subjected to the whitelist/blacklist filter (see the "Security" section of the "Advanced Comcode" tutorial), unless the Comcode was submitted by staff in which case it would not be filtered.

Tag reference

Tags may be easily added via the "Comcode Tag Assistant" feature in ocPortal, which lists all tags and provides an input mechanism for each. In addition, new tags may be created (discussed in the 'Advanced Comcode' tutorial).

Notes

When only certain parameters are allowed they are shown as, param=option1|option2(|…) for brevity. In that example it means you could choose to use either "option1" or "option2" as values for the "param" parameter.

When a tag is said to 'wrap' Comcode, it essentially adds on properties. For example:

Code


[b][i]text[/i][/b]

The 'text' is both emboldened and italicised.

A 'string' is just a length of text. That text may be a number written as text, or any other form of text.

For tags where it makes no sense for certain syntaxes to be interpreted within the embedded contents of the tag, the syntaxes will not be interpreted. For example, the 'code' and 'html' tags naturally do not actually parse Comcode within them.

For tags that would add their own blank lines (visually speaking) after them (e.g. title), blank lines in Comcode after them are skipped in order to allow the Comcode itself to be attractive without affecting layout.

Some parameter values actually support Comcode themselves. To use this, you will need to use the " escaping syntax described in the 'Tag syntax' section if you need to quote parameter values.

Few tags really need parameters (i.e. most parameters are optional). Often giving parameters will greatly improve the usefulness of a tag though: for example, without a 'param' parameter, the quote tag does virtually nothing except put something in a box.

Formatting tags

These tags define formatting, but some also have semantic meaning (meaning that is interpreted by computers, to give cues to search engines or accessibility devices). Try to think in terms of making your styling have combined presentational and semantic meaning, for accessibility as well as making your writing intuitive.

Semantic tags

These are 'semantic' tags, meaning they do very few (if any) display changes, but code up extra meanings into your documents.
Comcode has excellent support for semantics, but there is just one small area where it isn't able to support them, which is paragraphs. In Comcode the XHTML5 is created using XHTML <kbd>br</kbd> (line break) tags to separate lines. This has few practical ramifications known to us, and it is by necessity to make sure Comcode produces validating and consistent XHTML5. However if you want to use 'p' tags, you should use the Comcode 'semihtml' tag so that you have full control over how whitespace will display.

Attachments

Adding an attachment

Editing an attachment

ocPortal has a powerful attachment system that is integrated into Comcode, with a number of content types support attachments, such as news articles and OCF forum posts.
Using them couldn't be easier: you just choose a file (or many files) from your computer, and ocPortal will automatically add an 'attachment' tag into the Comcode you are writing. You may then move that tag to any location you want, for placement of the actual attachment when the content is viewed. There is special built in support for in-line display of various media forms, and support of download of other types of file; any file can be added so long as the file type is in the allowed list of file types defined in the Admin Zone (see the security tutorial for a discussion on this).

Attachments may be given special captions, which are usually displayed as a part of the attachment box.
Images have automatically generated and cached thumbnails.

Important note

Be careful when placing attachment tags in a Comcode spot that does not support attachments natively. This is supported, but the attachment will be deleted if its original content is deleted, as non-native Comcode spots have no way of recording that they have used it. In addition, if a viewer does not have access to the attachment's original content, they won't have access to your copy&pasted usage to a non-native Comcode spot.

If you go back to edit the content with your attachment, you will see that it has been given a number, whereas it as just marked as 'new' when being added. You may actually copy and paste the attachment tag into any other area of Comcode, so as to re-use the attachment. Anyone with permission to access any of the attachment supporting content locations that the attachment is placed in will be able to view/download it. The attachment will remain in the system until all content that using it is edited to stop using it, or deleted.

Concepts

Mark-up language: A language designed so that text may be laid out by surrounding special elements around portions of the text to define meta-properties (such as font)
Comcode: ocPortal's mark-up language for the creation of formatted text and inclusion of dynamic elements
Attachment: A file attached to Comcode via a 'posting page' supporting Comcode field; attachments have special support for rich media
Semi-HTML: HTML and Comcode mixed freely together
WYSIWYG: What-You-See-Is-What-You-Get: the name of the type of interactive editing interface used for formatting text in many programs, including modern word processors

ocPortal Tutorial: Comcode and the attachment system

Syntax

Table syntax

Code

Code

List syntax

Code

Code

Shortcuts

Symbols and directives

Tag syntax

Code

Code

WYSIWYG

Tag reference

Notes

Code

Formatting tags

Semantic tags

Attachments

Important note

Concepts

See also