textorum

Advanced, validating, structured text (XML) editing component. Part of the Annotum project.

Project Layout

• src/ - .coffee and .js

• vendor/ - .coffee and .js, third party

• lib/ - compiled to .js

• test/ - qunit tests in .coffee and related support

  • specs/ - pavlov specfiles in .coffee
  • lib/ - compiled tests and specs

• build/ - support files and configurations for project building

  • textorum.build.js - r.js file (probably gets subsumed into Cakefile)
  • fragments/ - javascript fragments / templates for building

• dist/ - Production-compiled output

• Cakefile - cake (coffeescript make) automation

• package.json - dependencies, npm install to install

Installation Instructions

Clone this repository to a web-accessible directory. The instructions below assume textorum is being installed in a webroot; tinymce.html may need to be edited to reflect the location of tinymce and similar otherwise.

Using OS X:

brew install node

Otherwise:

• Install node.js (v0.8.16 or later is known to work) and npm (v1.1.70 or later is known to work), using a package manager or from the download page
• Use the commands from this page to install Node via a package manager (Ubuntu, etc.)
• Install node.js and npm (using a package manager or from the download page)
• Use the commands from this page to install Node via a package manager (Ubuntu, etc.)
• Install Ruby (1.9.3-p194 is known to work; later patchlevels may have problems) and RubyGems (using a package manager or from ruby, rubygems)

In the textorum dir:

npm install -g grunt-cli
npm install
bundle install

In the webroot (if tinymce.html is unmodified):

Install jstree v.pre1.0

From an archive:

curl -LO https://github.com/vakata/jstree/archive/v.pre1.0.zip
unzip v.pre1.0.zip
mv jstree-v.pre1.0 jstree

Or from git:

Known good revision: 9c41e435d5aee9647e26500200e30b359bb96ae0; tracking v.pre1.0 release branch in development

git clone -b v.pre1.0 https://github.com/vakata/jstree.git
cd jstree
git checkout 9c41e435d5aee9647e26500200e30b359bb96ae0

Install tinymce

From an archive:

curl -LO http://github.com/downloads/tinymce/tinymce/tinymce_3.5.8.zip
unzip tinymce_3.5.8.zip

Or from git (tracking master branch until Textorum release):

git clone https://github.com/tinymce/tinymce.git
cd tinymce
ant
cd ..

To compile the SASS and CoffeeScript to CSS and JavaScript:

grunt

To watch (continually compile) the SASS and CoffeeScript:

grunt watch

To build the distribution (for use with Annotum):

grunt dist

Ubuntu Cheat Sheet for Dev

cd ~/Web/wordpress/wp-content
sudo rm -rf themes
git clone git@github.com:Annotum/Annotum.git themes
cd themes
git checkout textorum-integration
git submodule update --init
cd annotum-base/js/textorum/
git checkout develop
sudo npm install -g grunt-cli
sudo npm install
sudo gem install bundler #if not already installed
sudo bundle install
grunt dist

Example instructions

• Open http://textorum.example.com/tinymce.html (adjusted for where you installed Textorum)
• Enter an absolute or relative path to a Textorum-compatible XML document in the input box and click Load
• Toggling source view or pressing "Save" will submit the re-assembled XML to a test script that echos it back

Tested to work in Chrome. Probably works in Firefox; known not to work in IE.

Dependencies

Textorum depends on several external javascript libraries, including:

• TinyMCE
• jQuery
• jQuery UI
• JSTree

With the goal of tracking compatibility with (and potentially dependence on) the same versions as WordPress uses. For development purposes, they will track WordPress trunk; releases will target versions available with the then-current WordPress release.

Caveats

Many. This is currently a very incomplete

(this space intentionally left blank)

XML implementation

The XML namespace handling is relatively naive: all namespaces are assumed to be global, and no scoping rules are used. Therefore, a document which depends on complex or overlapping namespaces or namespace resets may be mishandled. A simple example:

<foo xmlns:a="http://example.com/a">
  <bar xmlns:a="http://example.com/b">
  	<a:baz/>
  </bar>
</foo>

may be treated as though a:baz is either in the /a or the /b namespace (depending on the browser's XSLT behavior), rather than certainly being in the /b namespace by correct XML parsing.

As a workaround, documents can be passed through a namespace normalizer (such as http://lenzconsulting.com/namespace-normalizer/ or https://github.com/wendellpiez/XMLNamespaceFixup/blob/master/XSLT/namespace-cleanup.xsl) before loading. Unfortunately, neither one is effectively compatible with running in current browsers; the first produces inconsistent and sometimes empty results, and the second is XSLT 2.0, which is not commonly supported.