Skip navigation

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
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)
CEDI 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

This section lays out all the tags available to you. 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.

Tags shown in red are only usable for those with permission to use dangerous tags.
Tags shown in orange are restricted based on HTML filtering permissions.

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.

Tag	Purpose	Parameters	Embeds
list	Show a list (alternative to direct syntax). Use it if you are making use of the of 'param', or want list elements to span multiple lines. Beware that this tag isn't entirely cache-safe, so any links in it won't propagate 'keep_' parameters properly.	param=1\|a\|i\| (defaults to blank, meaning a normal list) '1' means 'numeric list' 'a' means 'alphabetical list' 'i' means 'Roman numerals' 'x' means 'No list symbol'	List elements, separated by [] (which is not a proper Comcode tag, as it has no [/] closing tag.
indent	Indent.	param – indentation (defaults to 10)	Wrapped Comcode.
ins	Mark some text as inserted by a modification (this is intended to express meaning, rather than style).	cite – a URL that explains the change (optional – most people will never use this) datetime – date of change, in `YYYY-MM-DDThh:mm:ssTZD` format (optional – most people will never use this)	Wrapped Comcode.
del	Mark some text as deleted by a modification.	cite – a URL that explains the change (optional – most people will never use this) datetime – date of change, in `YYYY-MM-DDThh:mm:ssTZD` format (optional – most people will never use this)	Wrapped Comcode.
b	Embolden. This creates an XHTML `strong` tag, which is 'semantic'.	/	Wrapped Comcode.
u	Underline.	/	Wrapped Comcode.
i	Italicise. This creates an XHTML `em` tag, which is 'semantic'.	/	Wrapped Comcode.
s	Strike-through.	/	Wrapped Comcode.
sup	Make superscript (used in mathematics to 'raise to the power of', e.g. x²).	/	Wrapped Comcode.
sub	Make subscript (used in mathematics to 'distinguish variables', e.g. x₂).	/	Wrapped Comcode.
size	Change size. Short-hand for using 'font' with a 'size'.	param – a size number	Wrapped Comcode.
color	Change colour. Short-hand for using 'font' with a 'color'.	param – an HTML/CSS colour code	Wrapped Comcode.
highlight	Highlight text.	/	Wrapped Comcode.
font	Change font.	param – the font face name color – the colour size – the size	Wrapped Comcode.
align	Change the justification of text (not XHTML block elements, and thus most ocPortal blocks).	param=left\|center\|right\|justify	Wrapped Comcode.
left	The same as using 'align' with 'left'.	/	Wrapped Comcode.
center	The same as using 'align' with 'center'. Note it can only center text, not XHTML block elements (like most ocPortal blocks). To center blocks you need to use CSS centering like, `[semihtml]<div style="margin: 0 auto; width: 300px;">[block]main_iotd[/block]</div>[/semihtml]`. In old versions of HTML centering was easy but that support was dropped, and unfortunately this more complex hand-coded CSS needs using nowadays to be standards-compliant.	/	Wrapped Comcode.
right	The same as using 'align' with 'right'.	/	Wrapped Comcode.
abbr	Create a special abbreviation.	param – the full version	The abbreviation (i.e. short version).
box	Show the wrapped Comcode inside an ocPortal 'standard box'. Most standard boxes may have a title. If you look at an ocPortal page, you will likely see a number of standard boxes of various configuration: basically, boxed content. (Some box types support 'meta' and 'link' content, that attach inside the box in a special way. These aren't supported in Comcode for security reasons, and the BOX tempcode directive must be used instead. It is rare that these would be wanted outside templates, and these are only supported for use by administrators).	float=left\|right (defaults to right) dimensions=width\|"width\|height" (default: 100%) – the width/heights are given in CSS units - examples: "100%" (100% width), "100%\|50px" (100% width, 50px height) type=classic\|panel\|med\|curved\|invisible\|light\|accordion (default: classic) – these represent different templates (STANDARDBOX_type.tpl). Classic - the default box Panel – a box for use in side-panels Med – a box with medium-sized borders Curved – a box with curved corners Light – a box with light borders Accordion – a box that expands, but contracts all other accordion boxes when it does Invisible – a box with no borders or background options – "\|"-separated options that may exist in custom themes. param – The title of the box. This field supports Comcode.	Wrapped Comcode.
quote	Quote somebody. The quote is itself Comcode, rendered in a special box.	param – who or what is being quoted (e.g. Wikipedia, or a username). saidless – set to '1' if you do not want the 'said' text to appear cite – a URL that explains the change (optional – most people will never use this)	Wrapped Comcode.

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 XHTML 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 XHTML. 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.

Tag	Purpose	Parameters	Embeds
cite	Make an inline citation (this is intended to express meaning, but will make little visual difference to your text, as it is designed to be read by search-engines).	/	Wrapped Comcode.
samp	Used for writing out computer code. We also have the 'tt' tag which is very similar (produces an XHTML `kbd` tag).	/	Wrapped Comcode.
q	Used for writing out an inline quotation. We also have the 'quote' tag which produces a block quotation.	/	Wrapped Comcode.
var	Used for writing out a computer variable. If you don't know what this means, you don't need this tag.	/	Wrapped Comcode.
dfn	Marks text as being a definition (this is intended to express meaning, but will make no visual differences to your text, as it is designed to be read by search-engines).	/	Wrapped Comcode.
address	Marks text as being an address (this is intended to express meaning, but will make no visual differences to your text, as it is designed to be read by search-engines).	/	Wrapped Comcode.

Structure/navigation tags

Tag	Purpose	Parameters	Embeds
title	Show a title. Note that a level 1 title will automatically affect the title in the page title bar, for purposes of search engine optimisation.	param=1\|2\|3 – the level of title (i.e. the first title would be level 1, and sub-titles of that, level 2) sub – the sub-text of the title (only applies to level 1, in default templates) number – set to a comma-separated list of list-style codes, as used by the contents tag: this will cause numbering to be placed before titles (defaults to no numbering, and a blank value may be used for default numbering) base – the minimum level this title will be numbered against (default 2)	Wrapped Comcode.
contents	Automatically generate a table of contents from the title tags in the Comcode	files – a prefix for selecting which files to search in to gather Comcode titles (defaults to only searching the current Comcode page). These titles will form the contents-list. zone – the zone to search in for the Comcode pages if we are doing a file search (defaults to the zone that the Comcode page containing this tag is in) levels – the maximum depth of Title-tag levels to put in (defaults to all) base – the Title-tag level to begin titling from	A comma-separated list of CSS list style codes. Or nothing at all.
include	Include the full contents of a Comcode page at this point in the Comcode. It goes without saying (but we will!) that you should not create an include that includes the including Comcode page (a loop). It is advisable to name your included page beginning with a '_' symbol, as pages named like this will not show in the site-map.	param – the zone to include from (default is to search)	The Comcode page name.
concepts	Show a concepts table and store the concepts so that the 'concept' tag may link to them from any other Comcode.	x_key – concept name (where 'x' is any identifier you wish to create). x_value – the explanation of the concept (where 'x' is the same identifier as you created for 'x_key'). This parameter supports Comcode. You may create multiple concepts within the same tag, replacing the 'x' identifiers with different values. For example: `[concepts 1_key="Concept name" 1_value="The explanation of the concept" 2_key="Concept name 2" 2_value="The explanation of the concept 2"]The title of the concepts table[/concepts]`	The title of the concepts table.
concept	Show a concept, and if it is known, a link to the concept table that defines it.	param – text to display for definition (will display instead of linking) (defaults to blank, which will link to a stored concept if it exists)	Name of the concept.
staff_note	A note available for any one who is viewing the Comcode source (usually, staff, validating a resource). It is a comment, and not ever rendered.	/	The note.
menu	Display a Comcode menu (not a menu editor style menu). (This is a dangerous because it can confuse the layout and break menu expansion via conflicting name).	param – menu name type – menu type (defaults to tree, and only types available that have a template set for them) The menu tag and its usage is covered on the 'Advanced Custom pages of information (via Comcode)' tutorial	The menu syntax.
surround	Place an XHTML `div` tag around the embedded Comcode. By default this tag has a CSS class that will lock its contents from leaking out (useful for tieing floated attachments to paragraphs). It can also be useful for inserting class names into your output so that you can apply CSS rules that override using the new class name as an anchor.	param – CSS class, or multiple separated by spaces	The locked-in Comcode.

Code tags (for displaying code)

Tag	Purpose	Parameters	Embeds
php	This is equivalent to using the 'code' tag with the 'param' parameter as 'php'. Note that it does not execute PHP code, it displays it nicely.	Those as for the 'code' tag, except 'param'.	The code to show.
codebox	This is equivalent to using the 'code' tag with the 'scroll' parameter as '1'.	Those as for the 'code' tag, except 'scroll'.	The code to show.
sql	This is equivalent to using the 'code' tag with the 'param' parameter as 'sql'. Note that it does not execute SQL code, it displays it nicely.	Those as for the 'code' tag, except 'param'.	The code to show.
code	This displays code in a box and monospaced font, with possible syntax highlighting (depending on code type – at the time of writing only PHP supports this). Note that it does not execute or extract code, it only displays it.	param – the language to highlight for: doesn't have to be supported, so you may be specific in case it is supported in the future scroll=0\|1 – whether to show the code in a nice scrollable box (defaults to 1 if the length exceeds 1000, otherwise defaults to 0) numbers=0\|1 – whether to show line numbers, when possible (defaults to 0). Note: this requires the GeSHi library installed into ocPortal: see the 'Advanced Custom pages of information (via Comcode)' tutorial.	The code to show.
tt	Show as teletyped. (Written like it was done on a typewriter, so as to make it stand out as something to type). Comcode in 'tt' is not scanned for automatic link checking, amongst other things. 'tt' creates an XHTML `kbd` tag, which is 'semantic'.	/	Wrapped Comcode.
no_parse	Do not parse the contents of the tag, but otherwise display as normal.	/	Wrapped Comcode.

Code tags (for executing code in standard formats)

Tag	Purpose	Parameters	Embeds
semihtml	Treat the embedded text as freely mixed Comcode tags and HTML. This is used by the WYSIWYG editor. This tag is particularly handy if you're using complex Comcode (e.g. Tempcode directives or the `if_in_group` tag) and you want to be able to use white-space to layout your code (semihtml does not have 'hard white-space' -- if you do want spaces, use the XHTML `br` tag and the `nbsp` entity). Note that this tag does not work in the WYSIWYG editor: to enter HTML in the WYSIWYG editor use the 'View source' feature and paste it in directly. Also note that purely textual syntaxes like emoticons will not work from inside semihtml for stability reasons, only HTML and Comcode tags work.	/	Comcode and HTML mixed freely.
html	Treat the embedded text as HTML. Note that this tag does not work in the WYSIWYG editor: to enter HTML in the WYSIWYG editor use the 'View source' feature and paste it in directly.	/	HTML.

Dynamic (front-end) tags

Tag	Purpose	Parameters	Embeds
overlay	Produce an overlay. This is like a popup window, but it's not a real popup. (Note: the placement of the tag within the Comcode page will have no effect on the positioning of the overlay.)	param – an identifier for the overlay. If this is provided, the user may permanently dismiss all overlays with the same identifier. x – the left-hand offset to place the overlay at (in pixels, defaults to 100) y – the screen-top offset to place the overlay at (in pixels, defaults to 100) width – the width of the overlay (in pixels, defaults to 300) height – the height of the overlay (in pixels, defaults to 300) timein – the number of milliseconds until the overlay is displayed (defaults to 0) timeout – the number of milliseconds until the overlay is hidden, measured from the timein (defaults to -1, which means there is no timeout)	Wrapped Comcode. The contents of the overlay.
random	Show a random choice from a number of possibilities. A random number is picked, and then it is linked to a string by what range it fits within. (This is a a dangerous tag because it could be used to hide things like random obscenities from staff). Usage example: Code `[random 1=1 2=2 3="Three" 10="TeN"]20[/random]`	X – the string to show if our random number is between our X and the next highest X. Supports Comcode. Where there may be any number of Xs, which are all numbers. The first X should be 0 (zero). For example: [tt][random 0="Zero to Three" 4="Four to Seven"]7[/random][/tt]	No meaning.
pulse	Show a wave of colour moving through some text.	param – the speed, in milliseconds per frame (e.g. 500) min – the minimum colour in the pulse as a hexadecimal colour (e.g. FF00EE) max – the maximum colour in the pulse as a hexadecimal colour (e.g. EE00FF)	Wrapped Comcode.
ticker	Show a scrolling marquee. You should not use this site on a page that is meant to meet accessibility guidelines.	param – the width in pixels speed – a multiplier for the default speed	Wrapped Comcode.
shocker	Jump between a number of string pairs, showing coupled facts (typically statements with figures). It includes colour pulsing and fading. You should not use this site on a page that is meant to meet accessibility guidelines. Usage example: Code `[shocker left_1="A" right_1="a" left_2="B" right_2="b"]1000[/shocker]`	Any number of parameters that start 'left_', and matching parameters that start 'right_'. For example, 'left_1' and 'right_1'. Supports Comcode. min – the minimum colour in the pulse as a hexadecimal colour (e.g. FF00EE) max – the maximum colour in the pulse as a hexadecimal colour (e.g. EE00FF)	The number of milliseconds between jumps.
jumping	Jump between a number of strings. You should not use this site on a page that is meant to meet accessibility guidelines. Usage example: Code `[jumping a="A" b="B" c="C"]1000[/jumping]`	Any number of strings given any name (names are ignored, only values are used). Supports Comcode.	The number of milliseconds between jumps.
section	Define an embedded 'section', for content spread across embedded 'sections'.	param – the name of the section (required) default – set this to 1 if the section is the default section (otherwise leave it out, or set it to 0). There should only be one default section (or none), unless multiple sections should be opened initially.	Wrapped Comcode.
section_controller	Provides the interface to move between sections. Note that this does not surround `section` tags, it follows them. The contents of this tag are a list of the names of sections it controls. Usage example: Code `[section="1"] Section 1 [/section] [section="2"] Section 2 [/section] [section="3"] Section 3 [/section] [section_controller]1,2,3[/section_controller]`		A comma-separated list of section names, which will be shown in the order given.
big_tab	Define an embedded 'big tab', for content spread across 'big tabs'. These are often used on front pages.	param – the name of the big tab (required) default – set this to 1 if the big tab is the 1st big tab (otherwise leave it out, or set it to 0). It should only ever be set on the 1st big tab in the document.	Wrapped Comcode.
big_tab_controller	Provides the interface to move between big tabs. Note that this does not surround `big_tab` tags, it follows them. The contents of this tag are a list of the names of big tabs it controls. Usage example: Code `[surround] [big_tab_controller]A,B,C,D[/big_tab_controller] [big_tab="A" default="1"] ...a [/big_tab] [big_tab="B"] ...b [/big_tab] [big_tab="C"] ...c [/big_tab] [big_tab="D"] ...d [/big_tab] [/surround]`	switch_time – the number of milliseconds between automatic big tab cycling. The default is 6000.	A comma-separated list of big tab names, which will be shown in the order given.
tab	Define an embedded 'tab', for content spread across embedded 'tabs'.	param – the title of the table (required) default – set this to 1 if the tab is the default tab (otherwise leave it out, or set it to 0). There should only be one default tab (or none), unless multiple tabs should be opened initially.	Wrapped Comcode.
tabs	Provides the interface to move between sections. Note that this does not surround `section` tags, it follows them. The contents of this tag are a list of the names of sections it controls. Usage example: Code `[tabs="A,B,C"][tab="A" default="1"]a[/tab][tab="B"]b[/tab][tab="C"]c[/tab][/tabs]`	param – a comma-separated list of tab titles (must be consistent with the titles given to the embedded tabs).	Comcode composed solely of `tab` tags.
carousel	A horizontal scroller for content.	param – the amount of pixels to scroll per scroll click.	Wrapped Comcode.
hide	Hide some text such that it needs to be consciously expanded to see what it is. This is useful for giving warnings before viewing. For those without Javascript enabled, the text will be expanded by default.	param – the warning (defaults to a translated 'Expand' string). Supports Comcode.	Wrapped Comcode.
tooltip	Display a tooltip over the wrapped Comcode. The tooltip should be not be used to display critical information when accessibility is required as it depends on Javascript being enabled and cannot work on touch screen systems (e.g. the iPhone).	param – The tooltip	Wrapped Comcode.

Dynamic (back-end) tags

Tag	Purpose	Parameters	Embeds
currency	Perform an automated currency conversion.	param – the currency the amount is in (see Wikipedia for a list of active currency codes). bracket=0\|1 – rather than perform a hidden conversion, show the conversion in brackets after the source value	The money amount.
block	Insert a dynamic block (described in the 'Advanced Custom Pages of Information (via Comcode)' tutorial.	Whatever the block takes.	The block name.
if_in_group	Only present the wrapped text if the current member is in one of the usergroups. (This is a dangerous tag because it could be used to pass secret messages that moderators do not see).	param=filter of usergroups (either IDs or names) in [concept]ocFilter[/concept] format. type=\|primary\|secondary (if non blank limits to given usergroup membership type)	Wrapped Comcode.

Tag

Purpose

Parameters

Embeds

currency

Perform an automated currency conversion.

param – the currency the amount is in (see Wikipedia for a list of active currency codes).

bracket=0|1 – rather than perform a hidden conversion, show the conversion in brackets after the source value

The money amount.

block

Insert a dynamic block (described in the 'Advanced Custom Pages of Information (via Comcode)' tutorial.

Whatever the block takes.

The block name.

if_in_group

Only present the wrapped text if the current member is in one of the usergroups.

(This is a dangerous tag because it could be used to pass secret messages that moderators do not see).

param=filter of usergroups (either IDs or names) in [concept]ocFilter[/concept] format.

type=|primary|secondary (if non blank limits to given usergroup membership type)

Wrapped Comcode.

Media linking tags

Tag	Purpose	Parameters	Embeds
flash	Display an inline flash file (SWF or FLV). You may wish to use a flash attachment instead.	param – resolution (defaults to "300x300")	Wrapped Comcode.
attachment	Show an attachment. Normally you do not type this tag directly, but rather use the posting forms attachment functionality to have it added for you. You might also choose to copy&paste these automatically-made attachment tags. The one case where this would be typed directly is if you are creating an attachment from a URL. This is a rare case and should be avoided, as external URLs may cease to be valid over time. Downloading and then uploading the file is better. Note that the thumb tag provides similar functionality to using an image attachment by URL, and the url tag provides similar functionality to using a download attachment, and the flash tag, a flash attachment. Embedded attachments are also supported, but these are only created by and for use by Comcode pages. To create a Comcode page with embedded attachments you must use the export feature in the editor. Once an embedded attachment is found, it is extracted, and the Comcode is rewritten to reference the extracted file. This tag is tightly controlled for security.	description – description for the attachment, shown inside a box. Use '/' to say not to put an image in a box. Note that for new uploads, descriptions are addable in the attachment editor, and automatically moved them into the tag after form submission. Supports Comcode. filename – the file-name to have the attachment downloaded under. type=auto\|island\|inline\|download\|code\|hyperlink\|mail – what type of attachment display should be used (default is auto). For auto, ocPortal detects what the file is from file extension, and uses appropriate templates to tie to relevant XHTML tags or plugins. 'mail' only applies to Comcode included in an e-mail and takes the attachment out-of-context, running it into a real e-mail attachment. width – width, if appropriate height – height, if appropriate align – alignment float=left\|right – Float the tag to the left/right. Normally this parameter would not be given.	This can be many things, and determined how the attachment works. If it is 'new_X' then ocPortal will look for an attached file to the posted form. If it is a number, it will tie to that numbered attachment. If it is 'url_URL' it will make an attachment from that URL. If it is something else, it will be interpreted as an encoded file.
attachment_safe	Do an attachment that is WYSIWYG editable (essentially the attachment will not be deleted if you change the XHTML in the WYSIWYG editor, whilst for the 'attachment' tag this would result in a disassociation and the now-unreferenced attachment would be automatically deleted).	As for 'attachment'	As for 'attachment'
img	Place an image specified by URL.	align – CSS alignment code to show how the image aligns to other Comcode near it (`top`\|`middle`\|`bottom`). float=`left`\|`right` (defaults to blank, meaning it will not be floated) param – the textual equivalent to the image (the alt attribute, needed for accessibility reasons), also shown as the image mouse-over caption if no title is given. Supports Comcode. title – the tooltip. May be blank. Supports Comcode. rollover – alternative image to show when the mouse hovers over. refresh_time – the number of milliseconds between image refreshes (leave it out unless you want the image to reload, e.g. to show a webcam feed).	The URL.
upload	Provide a link to an uploaded file. It is not recommended that you use this tag, as it was created before the attachment system existed and is very much inferior to it.	type – the uploads directory to link to a file in param – the link caption. Supports Comcode.	The file-name to link to.
exp_thumb	Show a thumbnail to a special 'example' image. Intended for putting thumbnails into Comcode documents without using the attachment system (which relies on DB entries or exported documents).	float=left\|right (defaults to right)	The image code. The image is stored in data/images/<zone>/<code>.<ext> e.g. 'foo' would typically be 'data/images/docs/foo.png'.
exp_ref	Similar to exp_thumb, but shows a link rather than a thumbnail. Useful for putting a link in-line to the text to pinpoint what is also shown as a thumbnail.	param – The text to show (defaults to a translated 'Example' string)	The image code as with exp_thumb.
thumb	Show and cache an automatically generated thumbnail to a URL. The thumbnail width is that of the configuration options specification.	align – CSS alignment code to show how the image aligns to other Comcode near it. param – a local relative URL to a thumbnail to forcibly use. Normally this parameter would not be given. caption – a caption shown as a tooltip. float=left\|right – Float the tag to the left/right. Normally this parameter would not be given.	The URL.

Linking tags

Tag	Purpose	Parameters	Embeds
url	Place a link. Because this tag has the URL and text opposite to in BBCode, Comcode supports them to be reversed via auto-detection. Comcode does it differently as it is designed policy to make the embedded text the most critical piece, which is naturally the URL (doing it the other way favours wrapping, but many Comcode tags aren't wrapped anyway). Search engines are instructed not to follow links unless the Comcode maker has special permission to allow them to do it. This is a utilitarian act of participation between web developers and search engine developers to help massively disincentive spam-bots. Where possible, use the 'page' tag rather than the 'url' tag. It is much less sensitive to changes in ocPortal structure that would leave URLs broken.	param – the link text. Defaults to the link itself, but shortened. Supports Comcode. title – the tooltip. target=_blank\|_self (defaults to _blank for an external link). Links that open in a new window will be marked as doing so on mouse-over, for accessibility reasons.	The URL.
email	Place an e-mail link, with anti-spam obfuscation. Like the URL tag, the embedded text and caption may be switched around if you so choose.	param – caption. Supports Comcode. title – the tooltip. subject – the default subject for the new email. body – the default body for the new email.	The e-mail address.
reference	Show a reference. This tag is rarely used, but is designed for citations.	type=url (URL is the only specific type at the moment – if it is not a URL, leave this parameter out) param – the reference title (only give if different from the reference code). Supports Comcode.	The reference code (e.g. “Webster's encyclopaedia”)
page	Show a link to an ocPortal page. It is much preferable to use this rather than the 'url' tag, because it is more resistant to architectural changes (for example, if suddenly ocPortal was written in something other than PHP, URLs to index.php would no longer work, but page links would; if the domain name was changed the links would also continue to work). This tag has two very distinct usage patterns, where parameters/embed-text are interpreted differently. If only a 'param' parameter and embed-text is given, then the embed-text becomes the caption, and 'param' becomes a page-link . The other usage pattern is as described on the right.	param – the zone the page is in caption – the link caption. Supports Comcode. ignore_if_hidden – whether to skip the link if it is broken Other parameters are actual parameters to place inside the URL. For instance 'type' and 'id' are likely to be used, as these are very commonly found in ocPortal URLs.	The page name
Examples: `[page="site:downloads:misc:2:foo=bar"]Downloads[/page]` `[page="site" type="misc" id="2" foo="bar" caption="Downloads"]downloads[/page]`
snapback	Link to a forum post, with specific graphics. This is used automatically across forum posts (when using ocPortal's own forum), but its manual usage is somewhat limited at this time.	param – the title to give for the link forum – the forum to look in (unneeded for most forum drivers)	The ID of the forum post.
post	Link to a forum post.	param – the title to give for the link forum – the forum to look in (unneeded for most forum drivers)	The ID of the forum post.
topic (alias: thread)	Link to a forum topic.	param – the title to give for the link forum – the forum to look in (unneeded for most forum drivers)	The ID of the forum topic.

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

Is this tutorial insufficient?

If you think this tutorial needs work (maybe we didn't explain things well enough?) please let us know.

Keyboard shortcuts

Mozilla, you screwed upWhat we do with feedbackAn online booking engineHow to debug an infinite recursionIt's good to be challenged

Privacy · Feedback · Web Hosting Services provided by eLief

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

Structure/navigation tags

Code tags (for displaying code)

Code tags (for executing code in standard formats)

Dynamic (front-end) tags

Code

Code

Code

Code

Code

Code

Dynamic (back-end) tags

Media linking tags

Linking tags

Attachments

Important note

Concepts

See also

Is this tutorial insufficient?