User_Notes_joomla

joomla portal platform integration

A joomla based site can integrate the pgn4web chessboard in either of two ways:

  • through the pgn4web joomla plugin embedchessboard
  • through a generic plugin enabling iframes

See for instance the pgn4web test joomla site (this is a test site, things might occasionally be broken), or look at the users sites gallery.

using the pgn4web embedchessboard plugin

The pgn4web joomla plugin embedchessboard is available from the pgn4web downloads; it is also featured in the official joomla extensions directory.

The plugin implements the joomla auto update functionality; plugin updates can be detected and installed from the update tab of the admin extension manager pages.

screenshot

integration guidelines

The following instructions refer to the latest version of the plugin, please check the download section.

Recommended installation method is from the plugins section of the administration pages of your site, searching for the "EmbedChessboard" plugin. After installing the plugin, don't forget to activate it.

The plugin allows displaying chess games by entering the following tag within the content of your article:

[pgn parameter=value ...] 
... chess games in PGN format ...
[/pgn]

Tag parameters:

  • layout=horizontal|vertical
  • height=auto|number
  • showMoves=figurine|text|puzzle|hidden
  • initialGame=first|last|random|number
  • initialVariation=number
  • initialHalfmove=start|end|random|comment|number
  • autoplayMode=game|loop|none

Example:

[pgn initialHalfmove=16 autoplayMode=none]

[Event "World championship"]
[Site "Moscow URS"]
[Date "1985.10.15"]
[Round "16"]
[White "Karpov"]
[Black "Kasparov"]
[Result "0-1"]

1. e4 c5 2. Nf3 e6 3. d4 cxd4 4. Nxd4 Nc6 5. Nb5 d6 6. c4 Nf6 7. N1c3 a6 8.
Na3 d5 9. cxd5 exd5 10. exd5 Nb4 11. Be2 Bc5 12. O-O O-O 13. Bf3 Bf5 14.
Bg5 Re8 15. Qd2 b5 16. Rad1 Nd3 17. Nab1 h6 18. Bh4 b4 19. Na4 Bd6 20. Bg3
Rc8 21. b3 g5 22. Bxd6 Qxd6 23. g3 Nd7 24. Bg2 Qf6 25. a3 a5 26. axb4 axb4
27. Qa2 Bg6 28. d6 g4 29. Qd2 Kg7 30. f3 Qxd6 31. fxg4 Qd4+ 32. Kh1 Nf6 33.
Rf4 Ne4 34. Qxd3 Nf2+ 35. Rxf2 Bxd3 36. Rfd2 Qe3 37. Rxd3 Rc1 38. Nb2 Qf2
39. Nd2 Rxd1+ 40. Nxd1 Re1+ 0-1

[/pgn]

Keep in mind the graphical editor of joomla might add spurious HTML codes to your PGN data. While the plugin should be able to accomodate with that, you might want to clean your PGN input using the HTML view from the editor (some users reported an easier game entering by disabling the TinyMCE editor in the joomla global configuation).

The extension allows for plugin options for the site administrator to configure the horizontal or vertical position of the header/moves text respect to the chessboard, to blend the chessboard colors with the site template and to control the game autostart behavior at page load. To revert to default values simply leave options blank.

Other chessboard settings have been fixed in the plugin; if you really need to change those settings, the plugin code needs to be modified, look in file embedchessboard.php at the parameters passed to board.html and refer to the board widget instructions wiki page or ask for support. Please also note the plugin package has only one set of bitmaps, if you want to change bitmaps type/size you can find the whole set in the main pgn4web package.

advanced parameters

The settings of the advanced parameters section of the plugin should normally be left blank, improper values will break the chessboard display.

Please note that the joomla template might alter the appearance of the pgn4web board widget, in particular the width of the chessboard. If this happens, the advanced parameter section provides the option of setting the CSS style for the HTML DIV container of the plugin frame. The content of this parameter is directly copied in the style attribute of the DIV container and must comply with the CSS syntax. For instance, to force a fixed width to the chessboard frame, the CSS style for the HTML DIV container could be set to:

width:500px;

Please leave the advanced parameter blank unless you have a problem with the template and you know what you are doing.

In addition, the chessboard object is controlled using the chessboard-wrapper css style that as a last resort you can tweak to your needs.

caveats

  • HTML tags are stripped from the PGN data, removing all text between < and > characters; please make sure your PGN data does not contain < and > characters.
  • some site administrator reported the occasional need to clear the joomla cache while upgrading/reconfiguring the embedchessboard plugin. See the joomla administration page, tools menu.

support for older versions of joomla

The latest version of the pgn4web joomla plugin embedchessboard requires joomla version 1.6 or later. Limited support for older versions of joomla is available:

  • an earlier version of the plugin supports joomla 1.5. Some of the features of the latest version of the plugin might not be supported by the plugin for joomla 1.5
  • a backport for joomla 1.0 has been developed by a pgn4web user (rocholz(at)directbox.com). Some of the features of the latest version of the plugin might not be supported by the backport of the plugin for joomla 1.0. The backport has NOT been prepared and fully checked by the pgn4web project, use at your own risk.

using a generic plugin enabling iframes

Several plugin enabling iframes are available, such as the mosiframe plugin. For instance, the mosiframe plugin could be used in a blog post with the URL from the pgn4web board generator tool as the iframe URL. This is a less straightforward (requires using the board generator tool) but more flexible option (easier to modify colors and layout).


Related

Wiki: BoardWidget_instructions
Wiki: Contribute
Wiki: Features_Limitations_Bugs
Wiki: Index
Wiki: User_Notes_Web_Platforms
Wiki: User_Sites

Discussion

  • Comment has been marked as spam. 
    Undo

    You can see all pending comments posted by this user  here

    Anonymous - 2011-10-09

    Originally posted by: pa...@casaschi.net

    FAQ: how to display a larger chessboard with the plugin?

    see similar instruction for the wordpress plugin.

     
  • Comment has been marked as spam. 
    Undo

    You can see all pending comments posted by this user  here

    Anonymous - 2011-12-30

    Originally posted by: pa...@casaschi.net

    FAQ: how to use the plugin for a live games broadcast?

    see similar instruction for the wordpress plugin.

     
  • Comment has been marked as spam. 
    Undo

    You can see all pending comments posted by this user  here

    Anonymous - 2012-01-07

    Originally posted by: pa...@casaschi.net

    FAQ: how to use the plugin with PGN files?

    see similar instruction for the wordpress plugin.

     
  • Comment has been marked as spam. 
    Undo

    You can see all pending comments posted by this user  here

    Anonymous - 2013-06-09

    Originally posted by: knoir...@gmail.com

    If anyone has installed Kunena 3 recently, know that the fix for Kunena 2.x works with this new version, the only difference being that the file 'bbcode.php' is now in 'joomla/libraries/kunena/bbcode'.

     
    Last edit: Anonymous 2017-04-15
  • Comment has been marked as spam. 
    Undo

    You can see all pending comments posted by this user  here

    Anonymous - 2014-01-07

    Originally posted by: pa...@casaschi.net

    using the kunena forum joomla component

    Once the embedchessboard plugin is installed in joomla, it is possible to extend the usage of the pgn tag to the optional kunena forum component as well.

    Different integration guidelines are provided for different older versions of kunena.

    Due to the pace of change of the kunena software and the limited demand for pgn4web integration, the integration guidelines have not been updated since kunena 2.x and will not work directly on more recent version of kunena. Those guidelines however should be considered as a reference for creating similar patches for more recent version of kunena.

    kunena 2.x

    Manual editing of a kunena system file is required. Warning: manually editing a Kunena file might leave your forum unusable with your browser/server reporting errors; always make a copy of any file you manually edit to be able to restore a working forum in case of manual errors. Any kunena forum updates will likely override the manual modification that would need to be reapplied.

    First locate the file joomla/administrator/components/com_kunena/libraries/bbcode/bbcode.php and make a backup copy.

    Then edit the file, two modifications are required.

    first modification

    At the end of the var $default_tag_rules array definition, after the code:

    'terminal' => array(
            'mode' => BBCODE_MODE_LIBRARY,
            'method' => 'DoTerminal',
            'allow_in' => array('listitem', 'block', 'columns'),
            'class' => 'block',
            'allow' => array( 'colortext' => '/^[\w\d.-_]*$/' ),
            'content' => BBCODE_PROHIBIT
    ),
    

    add the array element:

    'pgn' => array(
            'mode' => BBCODE_MODE_LIBRARY,
            'method' => 'DoPgn',
            'allow_in' => array('listitem', 'block', 'columns'),
            'class' => 'block',
            'allow' => array( 'colortext' => '/^[\w\d.-_]*$/' ),
            'content' => BBCODE_PROHIBIT
    ),
    

    second modification

    At the end of the class KunenaBbcode definition, after the code:

    function DoTerminal($bbcode, $action, $name, $default, $params, $content) {
            if ($action == BBCODE_CHECK)
                    return true;
    
            if ( !isset($params ["colortext"])) $colortext = '#ffffff';
            else $colortext = $params ["colortext"];
    
            return "<div class=\"highlight\"><pre style=\"font-family:monospace;background-color:#444444;\"><span style=\"color:{$colortext};\">{$content}</span></pre></div>";
    }
    

    add the function:

    function DoPgn($bbcode, $action, $name, $default, $params, $content) {
            if ($action == BBCODE_CHECK)
                    return true;
    
            $tag_new = '';
            $pgn4webPath = JURI::root(true) . "/plugins/content/embedchessboard/pgn4web";
            $pgnText = preg_replace("/<br \/>/", " ", html_entity_decode($content));
            $height = 268;
            $multiGamesRegexp = '/\s*\[\s*\w+\s*"[^"]*"\s*\]\s*[^\s\[\]]+[\s\S]*\[\s*\w+\s*"[^"]*"\s*\]\s*/';
            if (preg_match($multiGamesRegexp, $pgnText) > 0) { $height += 34; }
            $pgnId = "pgn4web_" . dechex(crc32($pgnText));
            $tag_new .= "<textarea id='" . $pgnId . "' style='display:none'>" . $pgnText . "</textarea>";
            $tag_new .= "<iframe src='" . $pgn4webPath . "/board.html?am=l&amp;d=3000&amp;ss=26&amp;ps=d&amp;pf=d&amp;lcs=Y_uS&amp;dcs=QISv&amp;bbcs=QISv&amp;hm=b&amp;hcs=zq2a&amp;bd=c&amp;cbcs=UJGG&amp;ctcs=l4It&amp;hd=j&amp;md=f&amp;tm=13&amp;fhcs=$$$$&amp;fhs=14&amp;fmcs=$$$$&amp;fccs=v71$&amp;hmcs=QISv&amp;fms=14&amp;fcs=m&amp;cd=i&amp;bcs=Y_uS&amp;fp=13&amp;hl=t&amp;fh=b&amp;fw=p&amp;pi=" . $pgnId . "' ";
            $tag_new .= "frameborder=0 width=100% height=" . $height . " scrolling='no' marginheight='0' marginwidth='0'>your web browser and/or your host do not support iframes as required to display the chessboard</iframe>";
            return $tag_new;
    }
    

    This allows adding chessboards to kunena forum posts using the same pgn? tag used for joomla articles, however the tag parameters will be ignored.

    Based on new capabilities introduced in kunena 2.0, it might be possible to enhance the embedchessboard plugin to work within kunena posts with all tag parameters and configuration options; documentation from joomla/kunena is very poor at the moment, any support is welcome investigating this option or, even better, providing actual code.

    kunena 1.6.x and 1.7.x

    Manual editing of a kunena system file is required. Warning: manually editing a Kunena file might leave your forum unusable with your browser/server reporting errors; always make a copy of any file you manually edit to be able to restore a working forum in case of manual errors. Any kunena forum updates will likely override the manual modification that would need to be reapplied.

    First locate the file joomla/components/com_kunena/lib/kunena.parser.php and make a backup copy.

    Then edit the file, locating the function TagExtended(&$tag_new, &$task, $tag, $between) and at the end of the function, after

    case 'spoilerlight':
      ...
      break;
    add an additional case statement dealing with the pgn tag:
    
    case 'pgn':
      $tag_new = '';
      $pgn4webPath = JURI::root(true) . "/plugins/content/embedchessboard/pgn4web";
      $pgnText = preg_replace("/\r\n/", " ", html_entity_decode($between));
      $height = 268;
      $multiGamesRegexp = '/\s*\[\s*\w+\s*"[^"]*"\s*\]\s*[^\s\[\]]+[\s\S]*\[\s*\w+\s*"[^"]*"\s*\]\s*/';
      if (preg_match($multiGamesRegexp, $pgnText) > 0) { $height += 34; }
      $pgnId = "pgn4web_" . dechex(crc32($pgnText));
      $tag_new .= "<textarea id='" . $pgnId . "' style='display:none'>" . $pgnText . "</textarea>";
      $tag_new .= "<iframe src='" . $pgn4webPath . "/board.html?am=l&amp;d=3000&amp;ss=26&amp;ps=d&amp;pf=d&amp;lcs=Y_uS&amp;dcs=QISv&amp;bbcs=QISv&amp;hm=b&amp;hcs=zq2a&amp;bd=c&amp;cbcs=UJGG&amp;ctcs=l4It&amp;hd=j&amp;md=f&amp;tm=13&amp;fhcs=$$$$&amp;fhs=14&amp;fmcs=$$$$&amp;fccs=v71$&amp;hmcs=QISv&amp;fms=14&amp;fcs=m&amp;cd=i&amp;bcs=Y_uS&amp;fp=13&amp;hl=t&amp;fh=b&amp;fw=p&amp;pi=" . $pgnId . "' ";
      $tag_new .= "frameborder=0 width=100% height=" . $height . " scrolling='no' marginheight='0' marginwidth='0'>your web browser and/or your host do not support iframes as required to display the chessboard</iframe>";
      return TAGPARSER_RET_REPLACED;
      break;
    

    This allows adding chessboards to kunena forum posts using the same pgn tag used for joomla articles, however the tag parameters will be ignored.

     
    Last edit: Anonymous 2017-09-21

Log in to post a comment.