ocPortal Tutorial: Advanced Comcode
Written by Chris Graham, ocProducts
This tutorial will explain some of the more advanced aspects of the Comcode system.Table of contents
Bulk media upload
The Bulk-Upload assistant |
Custom Comcode
Adding a custom Comcode tag |
To add a custom tag, do as follows:
- Enter the Admin Zone
- In the Setup section, go to "Custom Comcode"
- Choose "Add custom Comcode tag"
- Choose the tag codename you would like to use, a title for the tag, a description, and an example of how the tag would be used.
- Tick the various check boxes as necessary.
- Place the HTML you wish to use inside the 'Replacement text' field, and put "{content}" at the place where you wish for the tag content to be (the text that sits between the opening of the Comcode tag and the closing of the Comcode tag).
- If you have additional parameters for the tag, list your chosen codenames, separated by commas, in the 'Parameters' field. Then place the codenames in the 'Replacement text' field, in a similar way to as you did for "{content}".
- Click the "Add custom Comcode tag" button
Semi-HTML
The [semihtml] tag is a special tag that allows Comcode and HTML to be naturally mixed together. Primarily, the tag is used so that the WYSIWYG editor, which is an HTML editor, may have Comcode placed within it that is not visual, and thus could not be edited in a WYSIWYG fashion.The [semihtml] tag is also useful if you are writing some content that has very tight formatting, so it involves a lot of HTML, but also includes elements of Comcode, such as blocks. Without the [semihtml] tag, it would be necessary to keep opening and closing [html] tags to achieve the same effect.
BBCode compatibility
Comcode, at the time of writing, can be considered an extension of BBCode , which is popular among standalone forum systems (some derivatives of 'BBCode' include 'vbCode', and 'BBCode' is itself originally based on 'UBB Code'). In actual fact, Comcode was created as an amalgamation of a number of pre-ocPortal syntaxes, and was not intentionally designed to be like BBCode at all; after time, we consciously moved it to appear more like BBCode, for compatibility reasons.Comcode can now support all major features of all the major BBCode-like languages, and lax syntax (for example, missing quotation symbols) as is often allowed in BBCode (mainly, so that importers and forum drivers do not have to convert from BBCode dialects to Comcode to display the data). However, BBCode implementations do not support a lot of the functionality of Comcode, such as the 'block' tag and our list syntax; in addition, the Comcode implementation is that of a fully parsed language, with a well-defined syntax, whilst BBCode is almost always implemented as an adhoc language to be turned into HTML via regular expressions.
Wiki-Code compatibility
One of the original syntaxes that came before Comcode was similar to that of WIKI-Code , in that it was not a text-formatting based language, rather than a tag based language. The Comcode list and ruled-line syntaxes are examples of this.Since version 3 of ocPortal we have made a conscious decision to support a few other WIKI-Code conventions, in a way that is most similar to that of MediaWIKI. We have opted to maintain most similarity to BBCode though, and have not provided WIKI-Code syntax that there was already supported by some alternative already in Comcode.
Comcode-XML
The form of Comcode that is documented and primarily used is now formally known as 'Comcode-Text'.Since version 3 of ocPortal we have introduced support for Comcode-XML. This is a formally specified XML language that is a bit harder to write, but is easier to integrate with other systems because a parser can be written using standard XML technology. If you do not know what XML is then you do not need to know about Comcode-XML because it won't provide any benefits to you.
We do not intend to document Comcode-XML separately even though the set of tags and attributes is not exactly the same as Comcode-Text.
Instead, we provide a schema that is available at http://ocportal.com/data/comcode3.xsd
The following is an example of Comcode-XML:
Code
<comcode>
Please leave us some product feedback.<br /><br />
<block>main_feedback<blockParam key="param" value="product_feedback" /></block>
</comcode>
Code
Please leave us some product feedback.
[block="product_feedback"]main_feedback[/block]
The enterprise version of ocPortal contains a REST web service that can convert Comcode-Text into Comcode-XML, in preparation for integration.
Semantics and accessibility
Comcode is designed to be a language that is easy to use, versatile, rich, indistinguishable from plain-text in the simple case, and usable in very small quantities. It is not designed to be a 'semantic' language, with any kind of special separation between visual coding (such as a font tag) and structural coding (such as a block tag, or arguably a ticker tag). Whilst the separation of concerns is appropriate for a website, where often they are worked upon by different people, and where the mark-up is complex and detailed enough to warrant a separation, it is not appropriate for Comcode.It is worth noting that the 'tag contents' of certain tags is of no visual significance what-so-ever (such as the block tag, where it has the codename of a block placed there, which is not itself displayed). This fact could be used to argue that Comcode is not a pure mark-up language.
There are some accessibility concerns with usage of Comcode, and these are described in the "Helping improve site accessibility for disabled users" tutorial.