HOW TOs (Automation)

Associated Product: MathTools 2.0

Last change: Mar 14, 2015

HOW TO Safely roundtrip MathTool V2 data in IDML workflows

• be sure latest MTV2 READER is installed on any InDesign, InCopy, and InDesignServer in your workflow. It is needed to handle all MathTools V2 data in the IDML, because InDesign - by design - silently strips off all 3rd party data in the IDML, unless handled by the 3rd party plug-in!
• be sure to NOT mix V1 and V2 installations. With MTV1 installed, InDesign silently strips off all V2 features on IDML import, including V2 MathStyles, MathZones. As a result, MathStyled expressions will become unusable.

HOW TO Identify MathTools V2 Scripting DOM elements

All MathTools V2 Scripting properties and methods share prefix 'mt'.

Most of them require a MathTools V2 EE (Enterprise Edition) license. However, if the edition column in the table below lists READER, the property or method is generally available; the intention is to help integrators to deal with MathZones in documents.

Script Element	MTV2 property/method	Type	Edition
Application
	mtLicenseInfo	string	READER
	mtVersion	string	READER
	mtGenerateLicenseReport()	string	READER
Document
	mtAllMathZones	Array of Text	EE
	mtDocVersion	number	READER
	mtIsMathEnabled	bool	READER
	mtConvertDocToMathToolsV2()		EE
	mtConvertImageToMathZone()	varies	EE
	mtEnableMathToolsOnDocument()		EE
Text, Paragraph, Line, Word, Character, InsertionPoint
	mtAllMathZones	Array of Text	EE
	mtConvertImageToMathZone()	varies	EE
	mtConvertToMathZone()	Text	EE
	mtExportMathZoneAsMathML()	string	EE
	mtFixMathZoneSpacing(settings)		EE
	mtGetFirstMathZone()	Text	EE
	mtGetLastMathZone()	Text	EE
	mtGetNextMathZone(refMZ : Text)	Text	EE
	mtGetPrevMathZone(refMZ : Text)	Text	EE
	mtGetMathZone()	Text	READER
	mtGetMathZoneBBox()	Array of number	EE
	mtPlaceMathMLAsMathZone(mathML:string)	Text	EE
	mtRefreshMathZones()	number	EE
	mtRevertMathZone()	Text	EE
	mtUnwrapMathZoneInlineFrames()		EE
	mtWrapMathZoneInlineFrames()	Text	EE
InsertionPoint, Character
	mtIsMathZone	bool	READER
InsertionPoint
	mtIsMath()	number	EE
Table, Cell
	mtAllMathZones	Array of Text	EE
	mtConvertImageToMathZone()	varies	EE
	mtFixMathZoneSpacing(settings)		EE
	mtGetFirstMathZone()	Text	EE
	mtGetLastMathZone()	Text	EE
	mtGetNextMathZone(refMZ : Text)	Text	EE
	mtGetPrevMathZone(refMZ : Text)	Text	EE
	mtRefreshMathZones()	number	EE
	mtRevertMathZone()	Text	EE
	mtUnwrapMathZoneInlineFrames()		EE
	mtWrapMathZoneInlineFrames()	Text	EE

HOW TO Get MathTools V2 version info

• app.mtVersion
• returns version string, e.g. 2.1.3_556

HOW TO Get MathTools V2 license status

• perform app.mtLicenseInfo
• returns MT or READER

HOW TO Create a License Report

• perform app.mtGenerateLicenseReport()
• returns path to generated license report

HOW TO Detect whether document is Math Enabled

• perform doc.mtIsMathEnabled
• returns true or false

HOW TO Enable MathTools for a document

• perform doc.mtEnableMathToolsOnDocument()
• equivalent to Math > Enable Math for Current Document

HOW TO Detect whether document uses MathTools V2

• perform doc.mtDocVersion

• returns 0, 1, or 2

• this is the version number, MathStyles panel shows in its upper right corner.

HOW TO Convert a mt.editor V1 document to V2

• perform doc.mtConvertDocToMathToolsV2()
• equivalent to action Math > Support > Convert mt.editor V1 doc

HOW TO Figure out whether a TextIndex is a MathZone

• perform insertionPoint.mtIsMathZone
• returns true or false

HOW TO Identify beginning and end marker of a MathZone

• use insertionPoint.mtIsMath
• returns
  • 0 if not a MathZone,
  • 1 for MathZone start marker,
  • 2 for MathZone end marker and
  • 3 for any text index inside a MathZone.

HOW TO Get a complete MathZone

• perform insertionPoint.mtGetMathZone()
• returns a Text object representing the text range of the MathZone

HOW TO Get a all MathZones in a range

• perform range.mtAllMathZones
• returns an array of Text objects representing the text ranges of the MathZones

HOW TO Recompose MathZones

• perform parent.mtRefreshMathZones() with parent being a text range, a table, a cell, or the document

HOW TO Modify MathZones

• MathZones are text. Text modification is allowed for most parts of the MathZone. However, some parts are protected and can't be deleted or changed. So, expect to see some scripting actions to fail. For example, it is not possible to delete a character used for a fraction-bar. Or the radical sign. Any attempt to delete, modify or replace those protected characters will silently fail. Moreover, any attempt to delete, modify or replace partial expressions will fail to avoid inconsistencies.

• Be careful with text delete, replace, and insert operations and check the results. A delete or replace operation affecting a protected character will fail. An attempt to insert a character into a protected text range will fail as well.

• Be careful to not corrupt MathZones by deleting parts of a MathZone or by inserting text! Always keep a copy of your document before running scripts or operations that directly affect MathZone text ranges!

MathML

HOW TO Place MathML

• perform insertionPoint.mtPlaceMathMLAsMathZone(mathMLString)
• returns the Text object representing the resulting MathZone

HOW TO Convert a MathZone to MathML

• perform mzText.mtExportMathZoneAsMathML()
• returns resulting MathML string

HOW TO Export MathML for MathZones during XML export

Native InDesign XML export:

• ID/IC: done in background if licensed. PRO edition is sufficient
• IDS: done in background if licensed. PRO edition for IDS is sufficient

3rd party XML export:

Requires to convert each MathZone to MathML using mzText.mtExportMathZoneAsMathML() and do the needful with 3rd party API to stream the resulting MathML into the 3rd party XML export stream.

HOW TO Import MathML as MathZones during XML import

Native InDesign XML export:

• ID/IC: done in background if licensed. PRO edition is sufficient
• IDS: done in background if licensed. PRO edition for IDS is sufficient

3rd party XML import:

Requires to place incoming MathML as MathZone using insertionPoint.mtPlaceMathMLAsMathZone(mathMLString).

HOW TO How to place a MathType EPS as a MathZone

• first place the EPS as an inlined image at textIndex ti
• for the Character following ti, perform c.mtConvertImageToMathZone()

HOW TO Convert a single inlined MathType EPS to a MathZone

• for the Character representing the inline EPS, perform c.mtConvertImageToMathZone()
• returns a Text object representing the resulting MathZone

HOW TO Convert any inlined MathType EPS in a text range to a MathZone

• perform range.mtConvertImageToMathZone()

HOW TO Convert any inlined MathType EPS in the document to a MathZone

• perform doc.mtConvertImageToMathZone()