Current development on JAMWiki is primarily focused on maintenance rather than new features due to a lack of developer availability. If you are interested in working on JAMWiki please join the jamwiki-devel mailing list.

Help:Tag extensions

ktip.png Tag extensions are fully supported only for JAMWiki 1.2 and later, and only work with the default JFlex parser. In addition, this capability is still under development, so usage may change significantly between major releases.

Starting with JAMWiki 1.2, the default JFlex parser can be configured to support extensions to the base wiki syntax. For example, sites that wish to allow Facebook "like" buttons can do so by enabling the <facebook /> tag.

Contents

Usage[edit]

There are several steps that must be taken to use parser extensions:

  1. Parser extensions only work with the default JFlex parser, which can be selected from the "Parser Settings" tab of the Special:Admin page.
  2. Several extensions are included in the default JAMWiki distribution in the jamwiki-jflex-parser-tags JAR file. If you wish to use an extension tag from another library then the required JAR file must be copied to your application server's class path.
  3. To enable an extension tag, modify the /resources/jamwiki-configuration.xml file in the JAMWiki file system directory (this directory is specified at startup and displayed as the first entry on the Special:Admin page) to include the tag class name and (optionally) the tag name by updating the jflex-parser-custom-tag section by adding a new custom-tag entry as follows:
      <jflex-parser-custom-tags>
        <custom-tag>
          <class>org.jamwiki.parser.jflex.addon.FacebookTag</class>
          <key>facebook</key> <!-- key is optional, defaults if not specified -->
        </custom-tag>
      </jflex-parser-custom-tags>
    
  4. Restart your wiki instance.
  5. The extension tag can now be included in wiki syntax as <tag_name />, where tag_name is either the default tag name or the name configured in step #3.

If the custom tag does not appear to be working you can verify that it is properly configured by changing your log level to "INFO" and verifying that is is initialized at startup. The log entry will look like the following, with a class matching the <class> configuration value:

2012-06-19 13:11:53,905 INFO org.jamwiki.parser.jflex.AbstractJAMWikiCustomTagLexer - Initializing custom parser tag: org.jamwiki.parser.jflex.GalleryTag

FAQ[edit]

Are there security concerns when using extension tags?[edit]

Many tags are implemented as extensions because they do have security concerns. For example, the iframe tag can be easily exploited by malicious users to implement a Cross-site scripting attack. In many cases such issues may not be a concern, for example when using the tag on an internal wiki, and in other cases security concerns can be mitigated by being vigilant about how the tags are used, or by implementing limitations on tag usage with tools such as the spam filter to prevent end users from utilizing the tag. See each tag description for a list of specific security issues to be aware of.

Tags included with JAMWiki by default[edit]

<facebook />[edit]

The facebook tag allows implementation of Facebook like / recommend buttons. See http://developers.facebook.com/docs/reference/plugins/like/ for additional details.

Syntax[edit]

  <facebook data-href="http://www.example.com" />
data-href
The full URL of the page to like/recommend on Facebook. Defaults to the current page URL.
data-send
Either true or false, depending on whether to include a "Send" button. Defaults to false.
data-layout
The like/recommend button's layout style. Must be one of "button_count", "standard" or "box_count", with the default being "standard".
data-width
The width in pixels of the generate like/recommend box. Must be specified as an integer, with the default being 450.
data-show-faces
Either true or false, depending on whether to include profile pictures. Defaults to false.
data-action
Tag attribute name for the verb to use - either "like" or "recommend". Defaults to "like".
app-id
The Facebook application ID to tie the like/recommend to. Defaults empty.
locale
Locale used by the Facebook button, useful for localizing button text. Only locales that are supported by Facebook are valid. Example "en_GB". Defaults to "en_US".

Configuration[edit]

  <jflex-parser-custom-tags>
    <custom-tag>
      <class>org.jamwiki.parser.jflex.addon.FacebookTag</class>
    </custom-tag>
  </jflex-parser-custom-tags>

Security concerns[edit]

By enabling this tag malicious users could implement "like" buttons that reference sites other than the current site. Administrators should monitor usage of this tag carefully.

<iframe />[edit]

The iframe tag allows use of HTML IFrames in wiki pages. The syntax is exactly the same as a normal HTML iframe tag.

Syntax[edit]

  <iframe src="http://www.example.com" id="iframe_id" scrolling="yes"></iframe>

Configuration[edit]

  <jflex-parser-custom-tags>
    <custom-tag>
      <class>org.jamwiki.parser.jflex.addon.IFrameTag</class>
    </custom-tag>
  </jflex-parser-custom-tags>

Security concerns[edit]

Enabling iframes allows malicious users to implement cross-site scripting attacks, whereby the iframe is used to load an external page that can be used to fool users into entering password or other sensitive information.

<twitter />[edit]

The twitter tag allows implementation of Twitter "tweet" buttons. See http://twitter.com/about/resources/buttons#tweet for additional details.

Syntax[edit]

  <twitter data-href="http://www.example.com" />
data-href
The full URL of the page being Tweeted. Defaults to the current page URL.
data-count
The "count" layout for the button. One of "horizontal", "vertical" or "none", with "horizontal" being the default.

Configuration[edit]

  <jflex-parser-custom-tags>
    <custom-tag>
      <class>org.jamwiki.parser.jflex.addon.TwitterTag</class>
    </custom-tag>
  </jflex-parser-custom-tags>

Security concerns[edit]

By enabling this tag malicious users could implement "Tweet" buttons that reference sites other than the current site. Administrators should monitor usage of this tag carefully.

Third-party tags[edit]

<source>[edit]

Author: shar

The source tag will automatically highlight programming language syntax.

Syntax[edit]

  <source lang="java">
  void main(){
     int i;
  }
  </source>

Configuration[edit]

  <jflex-parser-custom-tags>
    <custom-tag>
      <class>org.jamwiki.parser.jflex.addon.SourceTag</class>
    </custom-tag>
  </jflex-parser-custom-tags>

The following JAR files must be in the classpath for this code to work:

Source code can be found at Jhighlight or downloaded directly as jhighlight src.zip

Security concerns[edit]

None.


<asciishape>[edit]

Author: cab

The asciishape tag allows the include the drawing directly into the page and defined it as text. For more information including Syntax reference, Manual and Examples follow the link.

Syntax[edit]

  <asciishape  width="120" height="120" box="0,0,135,135" align="left">
    (250,250?200 0 180)-O;-B:0;-A:1
    (O@B)#
    (O.B)-B';-B'':.4
    (O.A)-A';-A'':.4
    (B'@O)#white/#
    (A'@O)/#
    (B'@B'')
    (A'@A'')#white
  </asciishape>

Configuration[edit]

  <jflex-parser-custom-tags>
    <custom-tag>
      <class>com.helpchoice.wiki.asciishape.jamwiki.AsciiShape</class>
    </custom-tag>
  </jflex-parser-custom-tags>

The following JAR files must be in the classpath for this code to work:

Source code is not available yet. I didn't decide to go Open Source route yet. License?

Security concerns[edit]

None.