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

ocPortal Developer's Guide: Comcode

» Return to Contents



Although there aren't many functions for processing Comcode, there is a lot of code…we advise you NOT to tweak sources/comcode.php!

Comcode gets compiled to tempcode upon submission, and is stored in the database as 'serialised tempcode'.

sources/comcode.php

Global_functions_comcode.php

Function summary

void init__comcode ()
string comcode_escape (string in)
LONG_TEXT html_to_comcode (LONG_TEXT html)
string apply_emoticons (string text)
mixed do_emoticon (array imgcode)
tempcode comcode_to_tempcode (LONG_TEXT comcode, ?MEMBER source_member, boolean as_admin, ?integer wrap_pos, ?string pass_id, ?object connection, boolean semiparse_mode, boolean preparse_mode, boolean is_all_semihtml, boolean structure_sweep, boolean check_only, ?array highlight_bits, ?MEMBER on_behalf_of_member)
string strip_comcode (string text)

void init__comcode()

Standard code module initialisation function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

string comcode_escape(string in)

Make text usable inside a string inside comcode

Parameters…

Name in
Description Raw text
Type string

Returns…

Description Escaped text
Type string

Return to the function index for this class Expand: View the source code to this function

LONG_TEXT html_to_comcode(LONG_TEXT html)

Convert (X)HTML into comcode

Parameters…

Name html
Description The HTML to converted
Type LONG_TEXT

Returns…

Description The equivalent comcode
Type LONG_TEXT

Return to the function index for this class Expand: View the source code to this function

string apply_emoticons(string text)

Get the text with all the smilie codes replaced with the correct XHTML. Smiles are determined by your forum system.This is not used in the normal comcode chain - it's for non-comcode things that require smilies (actually in reality it is used in the Comcode chain if the optimiser sees that a full parse is not needed)

Parameters…

Name text
Description The text to add smilies to (assumption: that this is XHTML)
Type string

Returns…

Description The XHTML with the image-substitution of smilies
Type string

Return to the function index for this class Expand: View the source code to this function

mixed do_emoticon(array imgcode)

Turn a triple of emoticon parameters into some actual tempcode.

Parameters…

Name imgcode
Description Parameter triple(template,src,code)
Type array

Returns…

Description Either a tempcode result, or a string result, depending on $evaluate
Type mixed

Return to the function index for this class Expand: View the source code to this function

tempcode comcode_to_tempcode(LONG_TEXT comcode, ?MEMBER source_member, boolean as_admin, ?integer wrap_pos, ?string pass_id, ?object connection, boolean semiparse_mode, boolean preparse_mode, boolean is_all_semihtml, boolean structure_sweep, boolean check_only, ?array highlight_bits, ?MEMBER on_behalf_of_member)

Convert the specified comcode (unknown format) into a tempcode tree. You shouldn't output the tempcode tree to the browser, as it looks really horrible. If you are in a rare case where you need to output directly (not through templates), you should call the evaluate method on the tempcode object, to convert it into a string.

Parameters…

Name comcode
Description The comcode to convert
Type LONG_TEXT

Name source_member
Description The member the evaluation is running as. This is a security issue, and you should only run as an administrator if you have considered where the comcode came from carefully (NULL: current member)
Default value
Type ?MEMBER

Name as_admin
Description Whether to explicitly execute this with admin rights. There are a few rare situations where this should be done, for data you know didn't come from a member, but is being evaluated by one. Note that if this is passed false, and $source_member is an admin, it will be parsed using admin privileges anyway.
Default value boolean-false
Type boolean

Name wrap_pos
Description The position to conduct wordwrapping at (NULL: do not conduct word-wrapping)
Default value 60
Type ?integer

Name pass_id
Description A special identifier that can identify this resource in a sea of our resources of this class; usually this can be ignored, but may be used to provide a binding between Javascript in evaluated comcode, and the surrounding environment (NULL: no explicit binding)
Default value
Type ?string

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name semiparse_mode
Description Whether to parse so as to create something that would fit inside a semihtml tag. It means we generate HTML, with Comcode written into it where the tag could never be reverse-converted (e.g. a block).
Default value boolean-false
Type boolean

Name preparse_mode
Description Whether this is being pre-parsed, to pick up errors before row insertion.
Default value boolean-false
Type boolean

Name is_all_semihtml
Description Whether to treat this whole thing as being wrapped in semihtml, but apply normal security otherwise.
Default value boolean-false
Type boolean

Name structure_sweep
Description Whether we are only doing this parse to find the title structure
Default value boolean-false
Type boolean

Name check_only
Description Whether to only check the Comcode. It's best to use the check_comcode function which will in turn use this parameter.
Default value boolean-false
Type boolean

Name highlight_bits
Description A list of words to highlight (NULL: none)
Default value
Type ?array

Name on_behalf_of_member
Description The member we are running on behalf of, with respect to how attachments are handled; we may use this members attachments that are already within this post, and our new attachments will be handed to this member (NULL: member evaluating)
Default value
Type ?MEMBER

Returns…

Description The tempcode generated
Type tempcode

Return to the function index for this class Expand: View the source code to this function

string strip_comcode(string text)

Strip out any Comcode from this "plain text". Useful for semantic text is wanted but where Comcode is used as "the next best thing" we have.

Parameters…

Name text
Description Plain-text/Comcode
Type string

Returns…

Description Purified plain-text
Type string

Return to the function index for this class Expand: View the source code to this function

sources/comcode_text.php

Global_functions_comcode_text.php

Function summary

void init__comcode_text ()
tempcode comcode_text_to_tempcode (LONG_TEXT comcode, MEMBER source_member, boolean as_admin, ?integer wrap_pos, ?string pass_id, object connection, boolean semiparse_mode, boolean preparse_mode, boolean is_all_semihtml, boolean structure_sweep, boolean check_only, ?array highlight_bits, ?MEMBER on_behalf_of_member)
boolean in_tag_stack (array tag_stack, array tags)
array detect_link (string comcode, integer pos)
array _opened_tag (boolean mindless_mode, boolean as_admin, MEMBER source_member, array attribute_map, string current_tag, integer pos, boolean comcode_dangerous, boolean comcode_dangerous_html, boolean in_separate_parse_section, boolean in_html, boolean in_semihtml, boolean close, integer len, LONG_TEXT comcode)
void filter_html (boolean as_admin, MEMBER source_member, integer pos, integer len, LONG_TEXT comcode, boolean in_html, boolean in_semihtml)
array _close_open_lists (integer list_indent, string list_type)
array parse_single_comcode_tag (string data, string tag)

void init__comcode_text()

Standard code module initialisation function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

tempcode comcode_text_to_tempcode(LONG_TEXT comcode, MEMBER source_member, boolean as_admin, ?integer wrap_pos, ?string pass_id, object connection, boolean semiparse_mode, boolean preparse_mode, boolean is_all_semihtml, boolean structure_sweep, boolean check_only, ?array highlight_bits, ?MEMBER on_behalf_of_member)

Convert the specified comcode (text format) into a tempcode tree. You shouldn't output the tempcode tree to the browser, as it looks really horrible. If you are in a rare case where you need to output directly (not through templates), you should call the evaluate method on the tempcode object, to convert it into a string.

Parameters…

Name comcode
Description The comcode to convert
Type LONG_TEXT

Name source_member
Description The member the evaluation is running as. This is a security issue, and you should only run as an administrator if you have considered where the comcode came from carefully
Type MEMBER

Name as_admin
Description Whether to explicitly execute this with admin rights. There are a few rare situations where this should be done, for data you know didn't come from a member, but is being evaluated by one.
Type boolean

Name wrap_pos
Description The position to conduct wordwrapping at (NULL: do not conduct word-wrapping)
Type ?integer

Name pass_id
Description A special identifier that can identify this resource in a sea of our resources of this class; usually this can be ignored, but may be used to provide a binding between Javascript in evaluated comcode, and the surrounding environment (NULL: no explicit binding)
Type ?string

Name connection
Description The database connection to use
Type object

Name semiparse_mode
Description Whether to parse so as to create something that would fit inside a semihtml tag. It means we generate HTML, with Comcode written into it where the tag could never be reverse-converted (e.g. a block).
Type boolean

Name preparse_mode
Description Whether this is being pre-parsed, to pick up errors before row insertion.
Type boolean

Name is_all_semihtml
Description Whether to treat this whole thing as being wrapped in semihtml, but apply normal security otherwise.
Type boolean

Name structure_sweep
Description Whether we are only doing this parse to find the title structure
Type boolean

Name check_only
Description Whether to only check the Comcode. It's best to use the check_comcode function which will in turn use this parameter.
Type boolean

Name highlight_bits
Description A list of words to highlight (NULL: none)
Default value
Type ?array

Name on_behalf_of_member
Description The member we are running on behalf of, with respect to how attachments are handled; we may use this members attachments that are already within this post, and our new attachments will be handed to this member (NULL: member evaluating)
Default value
Type ?MEMBER

Returns…

Description The tempcode generated
Type tempcode

Return to the function index for this class Expand: View the source code to this function

boolean in_tag_stack(array tag_stack, array tags)

Find if any of some tags are in the stack.

Parameters…

Name tag_stack
Description The tag stack
Type array

Name tags
Description The tags
Type array

Returns…

Description Whether one is present
Type boolean

Return to the function index for this class Expand: View the source code to this function

array detect_link(string comcode, integer pos)

Detect a link in some text.

Parameters…

Name comcode
Description The text
Type string

Name pos
Description Search position
Type integer

Returns…

Description A pair: where the link ends in the text, the URL
Type array

Return to the function index for this class Expand: View the source code to this function

array _opened_tag(boolean mindless_mode, boolean as_admin, MEMBER source_member, array attribute_map, string current_tag, integer pos, boolean comcode_dangerous, boolean comcode_dangerous_html, boolean in_separate_parse_section, boolean in_html, boolean in_semihtml, boolean close, integer len, LONG_TEXT comcode)

Helper function for setting up and juggling variables after reaching a new Comcode tag.

Parameters…

Name mindless_mode
Description Whether we are not considering parsing properly.
Type boolean

Name as_admin
Description Whether to explicitly execute this with admin rights. There are a few rare situations where this should be done, for data you know didn't come from a member, but is being evaluated by one.
Type boolean

Name source_member
Description The member the evaluation is running as. This is a security issue, and you should only run as an administrator if you have considered where the comcode came from carefully
Type MEMBER

Name attribute_map
Description The attribute map of the tag
Type array

Name current_tag
Description The identifier for the tag
Type string

Name pos
Description The offset of the tag in the Comcode
Type integer

Name comcode_dangerous
Description Whether the parser allows dangerous Comcode
Type boolean

Name comcode_dangerous_html
Description Whether the parser allows dangerous HTML
Type boolean

Name in_separate_parse_section
Description Whether the parser is/was in a separate parse section (e.g. a 'code' tag)
Type boolean

Name in_html
Description Whether the parser is/was in an HTML region
Type boolean

Name in_semihtml
Description Whether the parser is/was in a Semi-HTML region
Type boolean

Name close
Description Whether the tag is a closing tag
Type boolean

Name len
Description The length of the Comcode
Type integer

Name comcode
Description The Comcode being parsed
Type LONG_TEXT

Returns…

Description A tuple of new parser settings.
Type array

Return to the function index for this class Expand: View the source code to this function

void filter_html(boolean as_admin, MEMBER source_member, integer pos, integer len, LONG_TEXT comcode, boolean in_html, boolean in_semihtml)

Filter HTML for safety.

Parameters…

Name as_admin
Description Whether to explicitly execute this with admin rights. There are a few rare situations where this should be done, for data you know didn't come from a member, but is being evaluated by one.
Type boolean

Name source_member
Description The member the evaluation is running as. This is a security issue, and you should only run as an administrator if you have considered where the comcode came from carefully
Type MEMBER

Name pos
Description The offset of the tag in the Comcode
Type integer

Name len
Description The length of the Comcode
Type integer

Name comcode
Description The Comcode being parsed
Type LONG_TEXT

Name in_html
Description Whether the parser is/was in an HTML region
Type boolean

Name in_semihtml
Description Whether the parser is/was in a Semi-HTML region
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

array _close_open_lists(integer list_indent, string list_type)

Get HTML to close any open lists.

Parameters…

Name list_indent
Description The depth level of lists that we need to close
Type integer

Name list_type
Description List-type code
Type string
Values restricted to ul a 1

Returns…

Description The output needed to close the lists, and the new list indentation (always zero). Done like this so we can use 'list' to set both at once in the main parser.
Type array

Return to the function index for this class Expand: View the source code to this function

array parse_single_comcode_tag(string data, string tag)

Parse a single tag. For use separately, not used by main parser.

Parameters…

Name data
Description The data being parsed
Type string

Name tag
Description The tag we're expecting to see here / a regexp
Default value \w+
Type string

Returns…

Description A map of parsed attributes
Type array

Return to the function index for this class Expand: View the source code to this function

Tutorial - Adding a Comcode Tag


To add comcode tags, you will need some templates, and some code:

  1. Open up root/sources/comcode.php in an editor.
  2. Find line 44
  3. In this tutorial, we are going to be adding a sample tag: align, so change line 47 from:

Code (php)

                          'quote'=>1,'block'=>1,'html'=>1);

To:

Code (php)

                          'quote'=>1,'block'=>1,'html'=>1,'align'=>1);

4) Now, go to line 627, which should look like this:

Code (php)

         break;

5) After this line, enter the following code:

Code (php)

        case 'align':
                switch ($attributes['param'])
                {
                        case 'center':
               $align='center';
                                        break;
                        case 'right':
                              $align='right';
                                        break;
                        default:
                           $align='left';
                                        break;
                }
         $temp_tpl=do_template('COMCODE_ALIGN',array('ALIGN'=>$align,'CONTENT'=>$embed));
         break;

  1. Now that is done, we need to add the template, so create a new file entitled 'COMCODE_ALIGN.tpl' in your root/themes/themename/templates_custom/ folder.
  2. Open up this file in an editor, and insert the following:

Code (php)

<div align="{ALIGN}">
   {CONTENT}
</div>

8) Create a new comcode page, and test your new custom comcode tag!




At the time of writing, the following ocPortal attributes support comcode:
  • authors.skills
  • authors.description
  • banners.caption
  • cached_comcode_pages.string_index
  • catalogue_entry_field_values_* (if it is encoding text)
  • catalogues.c_description
  • catalogue_categories.cc_description
  • chargelog.reason
  • download_categories.description
  • download_downloads.comments
  • download_downloads.description
  • galleries.description
  • gifts.reason
  • images.comments
  • iotd.caption
  • news.news
  • news.news_article
  • news.title
  • poll.option1
  • poll.option2
  • poll.option3
  • poll.option4
  • poll.option5
  • poll.question
  • seedy_pages.description
  • seedy_posts.the_message
  • text.the_message

The following ocPortal input fields (that aren't attributes) support comcode:
  • chat messages
  • comment input: message, title
  • newsletter input: message, title