Interacting with PCProfiler
There are three ways which your template can interact with the PCProfiler engine. You needn't use any of them: a template that doesn't use any of the tricks outlined in this section of the tutorial is still a valid template.
AutoCalc Features
Whether your template has any kind of AutoCalc features is entirely up to you. Furthermore, what these autocalc features are must be defined by you: PCProfiler has absolutely no idea what its going to find in a template, and such, it pretty much leaves the template alone. So, you may find it handy to include various scripts that make using your template easier. The 3ED&D General Extended does just this, the 100 kB or so of template file is supported with over 30 kB of scripts.
Scripts can make your sheet very user-friendly. However, they can also render your template useless. Say, for example, the end-user has a very slow computer. Executing a huge script whenever a skill is changed, for example, may slow down the program for a second or two. Even worse, the program may cease to be responsive for a while. Or what if the user has a set of house rules that are so different from the standard rules, that the AutoCalc features are more of a pain than they are good?
In general, you should provide the means to disable any scripting support you add to your template. You can do this though a button, checkbox, or other element on your sheet, or you could have it hidden away nicely and let PCProfiler handle it. In PCProfiler's Template menu, you'll find a command called Disable AutoCalc Features. How does this command work?
Simple, PCProfiler scans your template for a hidden input, with the name disableAutoCalc (case sensitive).
<INPUT type=hidden name=disableAutoCalc>
If the element is not found, the menu item will be disabled (greyed out). If the disableAutoCalc element is found (and it's the correct type), the menu item will be enabled. The value of the disableAutoCalc element determines if the item is bullted: a value of 1 enables the bullet, otherwise, no bullet appears.
When the user selects the disable feature from the menu, the value of the disableAutoCalc element is set to either 1 or 0 depending on what it's value was when the command was clicked. Similarly, your scripts should recognize the value of the element, and only perform AutoCalc features when appropriate:
function AutoCalc()
{
if (document.all.disableAutoCalc.value == "1")
return;
// Do autocalc operations...
}
You can programatically enable or disable the AutoCalc features and the PCProfiler menu will stay in sinc:
function MyLongImporScript()
{
// ... after doing alot of things, it may be best to disable
// the autocalc, so do so.
document.all.disableAutoCalc.value = 1;
}
After the above function returns, the menu item will be bulleted, and everything will still be in sync.
Import Options
PCProfiler can handle up to 16 import scripts for each template. Import scripts appear in the File >> Import submenu. You instruct PCProfiler to add an item to this menu through a META tag, which belongs in the template's HEAD element:
<HEAD>
<META name=PCPImpM content="menuTitle; functionName; fileDialog;">
<!-- Rest of header definition... -->
</HEAD>
The PCPImpM command tells PCProfiler that this META tag describes an Import Map script, and the value of the content member tell PCProfiler exactly what to do:
- menuTitle
- Becomes the text that is inserted into the menu.
- functionName
- The name of the function that is called when the command is selected, which will drive the whole import process. This function must be defined in one of your scripts.
- fileDialog
- Set this to 1 to trigger an Open File dialog when the menu item is clicked. The contents of the file are then passed to your function through its first argument as a string. Set to 0 if you do not wish to open a file, and don't want anything passed to your import function.
So, the META tag for the d20 Standard Statblock import of the 3ED&D General extended template looks like this:
<META name=PCPImpM content="d20 Standard Statblock; d20Imp; 0;">
The menu item title becomes "d20 Standard Statblock", and when clicked, the function d20Imp is called. No Open File dialog is created, and no data is passed to the function, because the third argument has been set to zero.
Alternatively, you can handle your import options yourself through buttons placed directly in your script.
Export Options
Export options work much like the import options. PCProfiler will handle up to 16 export commands. The syntax for Export Maps is somewhat simpler though, since no File Dialog can be called:
<HEAD>
<META name=PCPExpM content="menuTitle; functionName;">
<!-- Rest of header definition... -->
</HEAD>
The meanings of the two arguments are the same as for the Import Maps. Note though, that only the first two arguments are used for export maps.