|
Advanced authors may find it desirable to modify the way that jsMath operates and feel the need to adjust some of the functions that are part of the jsMath package. It is important, however, not to modify the Overriding jsMath Functions with Your Own Versions
jsMath.js
file itself; jsMath provides other means for managing its functions and default values. While it may seem easier to just edit the code directly, in the long run this will make it more difficult for you to upgrade jsMath in the future. The procedure described below will allow you to keep your modifications separate from the original jsMath code, which will make it much easier for you to check the changes you have made when you install a new version of jsMath.
Changing jsMath before it is loaded
All the values and code for jsMath are collected in an object stored in a global variablejsMath
. WhenjsMath.js
is first loaded, it looks to see if there is already a variable calledjsMath
, and if so, it uses the values stored there to override the standard values fromjsMath.js
. This is why the customization examples suggest setting thejsMath
variable.The
jsMath
variable contains not just values (e.g., the default style definitions), but also all the code used by jsMath, so you can override functions as easily as you can values. Some functions have been designed to be overridden by the author (e.g., the one that creates the font warning messages), but most have not, so be careful about replacing them; you can cause jsMath to fail quite easily by replacing the wrong thing.After jsMath has set up its own version of the
jsMath
variable, it copies any values from your version ofjsMath
into its own, thereby replacing the defaults with your modifications. It is also possible to add new functions or values to jsMath in this way (some of the plugins do this, for example).Some of the routines and data stored in jsMath are collected into sub-objects within the
jsMath
object. For example, all the setup code is in thejsMath.Setup
object. You could override one of these values by settingjsMath = {Setup: {name: value}}where name is the item to be overridden, and value is its new value. The way this works is that jsMath will replace the items injsMath
with your values unless the value is an object, in which case it will merge the contents of your object into the existing one (not replace it). So in the example above,Setup
will not be replaced by an object with only one entry; instead, that entry will be added to the defaultSetup
object. This merging is done recursively, so you can insert entries into objects at any level of thejsMath
hierarchy.You will, of course, need to look through the
jsMath.js
file in order to see what routines or data you want to replace; however, this file is compressed so that it can be downloaded faster, so you will need to look at the copy in theuncompressed
folder instead.If you are using
easy/load.js
, you can include changes to thejsMath
variable there as well. In fact, the options set in that file are stored injsMath.Easy
, and you could modify other settings in a similar way.
Changing jsMath after it is loaded
The process described above allows you to modify jsMath by defining values before you load thejsMath.js
file. You can also modify jsMath after loadingjsMath.js
by simply setting the values in thejsMath
variable directly. For example, you could replace thejsMath.Process()
function by settingjsMath.Process = function () {your code here}after loadingjsMath.js
. (You might want to save the old function first, for examplejsMath.OldProcess = jsMath.Process
, so you can call the original from your new version.) Note, however, that afterjsMath.js
has been loaded, some processing has already been done, so your changes might be made too late to have their intended effect. For example, the font warning message will have been created already, so settingjsMath.Font.Message
after loadingjsMath.js
will not have the desired effect.Changes made to
jsMath
after loadingjsMath.js
are best used for additions to jsMath; overriding the values injsMath
is best handled by settingjsMath
before loadingjsMath.js
.As of version 3.0, there may be synchronization issues that you need to be aware of when you make modifications to jsMath after it is loaded. For example, even when a
SCRIPT
follows the one that loadsjsMath.js
, it may be that jsMath is not yet fully loaded and set up (e.g., a fallback file could be loading asynchronously). So if you plan to modify jsMath after loading it, you should be sure to usejsMath.Synchronize()
to make sure that your modifications coordinate with the jsMath event queue properly. The same applies to calling any jsMath function other than the ones specifically designed to be called by the user (such asjsMath.Process()
,jsMath.ConcertTeX()
,jsMath.Setup.Script()
andjsMath.Setup.Styles()
). See the documentation on synchronizing with jsMath for more details.
Inserting your code into the initialization sequence
The initialization sequence for jsMath is rather complex, and involves a number of checks (to see what fonts are available, for example), and may include loading of browser-specific code, or fallback support code. The initialization inserts some HTML into the document (e.g., the floating jsMath button) and sets up the styles needed for jsMath.There are three main phases of initialization: setting up the
jsMath
variable (which contains all the data and code used by jsMath, and can be done in either the HEAD or the BODY of the document), initializing the BODY elements needed by jsMath (which must be done after the BODY is available), and checking for the TeX fonts and loading the fallback method if necessary (which must be performed after the other initialization is complete).The first of these is done by loading the
jsMath.js
file, and the second and third are performed byjsMath.Setup.Body()
. WhenjsMath.js
is loaded in the BODY of the document,jsMath.Setup.Body()
is called automatically, but when it is loaded in the HEAD, this is put off until the first call tojsMath.Process()
orjsMath.ProcessBeforeShowing()
. If you need to do processing between loading jsMath and the body setup function, be sure to loadjsMath.js
in the document HEAD, and then do your processing, and finally make a call tojsMath.Setup.Body()
yourself (or letjsMath.Process()
take care of it). This allows you to insert processing between the first two phases of initialization.It is possible to insert your own code between the second and third phases as well, even though they are part of the same routine, by overriding the definition of
jsMath.Setup.UserEvent
object. This object holds functions that are called at particular times in the initialization process. ThejsMath.Setup.UserEvent["pre-font"]
function is called after the BODY has been set up but before the font check is performed, and is initially empty (i.e., it does nothing). When this routine is called, thejsMath.BBoxFor()
routine (but notjsMath.EmBoxFor()
) is be available, the user's browser has been determined and any browser-specific code has been loaded, the cookie values have been read, and the styles have been set.If you need to run code after the browser-specific code has been loaded but before the font check, you can use
jsMath = {Setup: {UserEvent: { "pre-font": function () { your-code-here } }}}to accomplish this.Three is also a user event called
onload
that is called afterjsMath.js
has loaded and finished running. So if you need to do some processing after you are sure jsMath.js is loaded and ready to go, you can usejsMath = {Setup: {UserEvent: { onload: function () { your-code-here } }}}to perform your code.Additional user events may be defined in future releases of jsMath.
|
|