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

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.


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


Thumbnail: The example in action

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

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.

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

/

Wrapped Comcode.

del

Mark some text as deleted by a modification.

/

Wrapped Comcode.

b

Embolden.

/

Wrapped Comcode.

u

Underline.

/

Wrapped Comcode.

i

Italicise.

/

Wrapped Comcode.

s

Strike-through.

/

Wrapped Comcode.

sup

Make superscript (used in mathematics to 'raise to the power of', e.g. x2).

/

Wrapped Comcode.

sub

Make subscript (used in mathematics to 'distinguish variables', e.g. x2).

/

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 HTML block elements, and thus most ocPortal blocks).

param=left|center|right

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 (X)HTML 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|light (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

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

Wrapped Comcode.



Semantic tags

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.

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.

/

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

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]

The maximum value for our random number.

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

jumping

Jump between a number of strings.

You should not use this site on a page that is meant to meet accessibility guidelines.

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.

A comma-separated list of section names, which will be shown in the order given.

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.

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. You may also filter against members by prepending their member ID with an exclamation mark (e.g. "!6").

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 – 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 HTML tags or plugins.

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

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

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 formally here.

param – the zone the page is in

caption – the link caption. Supports Comcode.

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

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

Thumbnail: Adding an attachment

Adding an attachment

Thumbnail: Editing 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

See also

Is this tutorial insufficient?

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