Macro Documentation Wiki

[Azhrei]

In general, it's always better to use JSON.

Seriously, as MT goes towards javascript as the macro language of choice, the use of JSON in token properties will be a huge benefit...

[Merkuri]

I like to use JSONs whenever possible, but sometimes it doesn't look like there's a choice. For example, it looks like dialogs (dialog() function) only return string property lists. I learned this after I had already planned out a big dialog to input an "attack" object. For the attack and damage bonuses I was going to request that users input a string property list, like this: "bonus1=3; bonus2=-2; bonus3=0", figuring that format was easy enough for users to understand and would be easier for me to script. Then I realized that the output of the form WAS a string property list and that this probably wouldn't work because you can't nest string property lists inside of string property lists (that's one of the huge bonuses of JSONs - the ability to nest things).

So, unless there's a way to do it that I'm missing (which I really hope is the case ), the output of dialogs always has to be a string property list, so that's one case where you'd use string property lists instead of JSONs.

[Rumble]

I like to use JSONs whenever possible, but sometimes it doesn't look like there's a choice. For example, it looks like dialogs (dialog() function) only return string property lists. I learned this after I had already planned out a big dialog to input an "attack" object. For the attack and damage bonuses I was going to request that users input a string property list, like this: "bonus1=3; bonus2=-2; bonus3=0", figuring that format was easy enough for users to understand and would be easier for me to script. Then I realized that the output of the form WAS a string property list and that this probably wouldn't work because you can't nest string property lists inside of string property lists (that's one of the huge bonuses of JSONs - the ability to nest things).

So, unless there's a way to do it that I'm missing (which I really hope is the case ), the output of dialogs always has to be a string property list, so that's one case where you'd use string property lists instead of JSONs.

If you're using a form in a dialog, you can use method="json" to output the form's values in a JSON. So:

Code: Select all

<form name="someForm" method="json" action='[r:macroLinkText(whatever)]'>

The return value will be a JSON object with each form field as a key, and the associated value. Note that checkboxes will only be returned in the JSON if they are checked (checked boxes have the value "on") so you can just use json.contains() to see if a box is checked. Also, it looks like spaces in the key names are replaced by the "+" sign before the JSON is returned.

[Merkuri]

Sweet, I was hoping there was something like that!

Now, where would be the appropriate place to add that in the wiki, if it's not already there?

[Rumble]

Sweet, I was hoping there was something like that!

Now, where would be the appropriate place to add that in the wiki, if it's not already there?

Hm. In the dialog() function page would be a possibility, though it's not really the correct place. Maybe we need a page on MapTool's HTML Form Support? Or just HTML Support?

EDIT: Craig also has a tutorial on dialogs and frames, where it might already be mentioned. It's a relatively new feature, IIRC.

[zEal]

Perhaps a tutorial of sorts on how to get and use numeric and string input for macros, there are four ways that I know of; input(), dialog/frame forms, undeclared variables, and chat aliases that point to macros(or custom functions) that support arguments.

[Rumble]

Perhaps a tutorial of sorts on how to get and use numeric and string input for macros, there are four ways that I know of; input(), dialog/frame forms, undeclared variables, and chat aliases that point to macros(or custom functions) that support arguments.

That's a good idea. I could write tutorial stuff on input() and forms, but not so much on the other two - I don't use them, and haven't dug into them much.

[Miar]

Frustration, I'm still going through wiki docs and trying to figure things out. I've been going through the basic frame/dialog intro. The first part goes well but after a certain point it becomes mush. Soon as you hit the html stuff it leaves you confused. You get to stuff like "create a new XXXX paste the following code". This is really unhelpful (at least to me). If I understood the code I wouldn't need to be told to paste it I would just write it, If I don't understand it telling me to put in the code doesn't help me much. That section feels like it should be you can also do XXX in a frame if you want to learn how go somewhere else. If someone has a general idea of what all the html commands are this is not a bad example. In that case though they are probably looking at examples which have explained everything to begin with.

I think all the html/JSON commands etc. used within the wiki in examples should have a cheat sheet it would make it much easier for people trying to figure it out.

Anyway I keep hacking and I figure what I want to do is find out how to make the "main" and "weapons" buttons. I search around the only thing I can find is the line that says "Where it says Main and Weapons on the top, they are links". Eventually I take a guess that they are in the "CharSheetHeader@this". I search through some more, the "CharSheetHeader@this" is not in the wiki example. I look some more and find the "campaign" file. Great I think I grab that, and there it is the "CharSheetHeader@this". But when I try to use the Main/Weapons buttons on the character sheet I get errors.

A couple of other things I've been thinking about ...

Where do I make requests now for documentation? In threads for the wiki? or as a general post? Documentation is now in two places.

Posts like "A (long) MapTool macro tutorial" are good but they go back to StrProps but JSON is now being used. I went back to reread it and while it's still good, for a new user it would be even more confusing. It teaches with StrProps and then are told not to use them but use JSON instead. Things like this really should be redone at some point.

All this is probably coming out rather harsh but just want you to understand the frustration of someone going through this stuff. Attach some smiles to everything I say.

edit: also it's late and I'm fairly fuzzy from taking cold medicine

[Rumble]

I can't offer much help, but I understand the frustration with macro writing!

The thing is, the wiki is not an official (as in, formally part of RPTools.net) documentation source so it doesn't have an official set of contributors / editors responsible for keeping it updated. I work on it, as does zEaL, and Craig, along with a couple other community members, as time becomes available.

With regard to the specific question about all of the functions being used, they are all listed in the "List of Functions" page - however, they are given in a "programmer's reference" style rather than a tutorial style. Perhaps each tutorial example could say something afterwards like "Functions used in the above code: json.get(), listAppend(), eval()" and they can be linked to their definitions.

As far as requesting documentation, I don't know that there's a formal process at all, and as bleak as it sounds, I am not willing to guarantee that a request for documentation will be fulfilled even if made - again, the wiki is all done in community member's free time. However, here, the wiki, or in the MapTool forum (especially the macros subforum) are all reasonable places to make a request.

[Miar]

I do understand all that and I'm really happy about all the time all of you put in. That said having the people who are using it do a little commentary when they run into problems I think is a good thing. Hopefully it will highlight areas that need work for when you do choose to put in time. I don't think people have the right to continuously complain about something they are getting for free, the line between polite commentary and complaints can get a little blurry at times though (or is at least slightly different for different people)

I do think that putting in links to references to commands used would be one of the biggest helps. One of the things I seem to spend the most time doing is going through things trying to track down what the commands in the examples actually do. Then I forget and have to go looking again

[bobthedog]

Well, since Real Life looks like it'll give me a quick break for a while, I've created an account for the wiki and I'll try to add stuff (mostly examples and commentary).

And let's hope this lasts for a few weeks... I got terribly outdated with all these shiny new features...

[zEal]

Well, since Real Life looks like it'll give me a quick break for a while, I've created an account for the wiki and I'll try to add stuff (mostly examples and commentary).

And let's hope this lasts for a few weeks... I got terribly outdated with all these shiny new features...

Hi Bob, thanks for taking the time to look at how the other functions were formatted before working on one. When did getName have the id parameter added to it? I don't recall seeing that in any release notes.

[bobthedog]

Well, since Real Life looks like it'll give me a quick break for a while, I've created an account for the wiki and I'll try to add stuff (mostly examples and commentary).

And let's hope this lasts for a few weeks... I got terribly outdated with all these shiny new features...

Hi Bob, thanks for taking the time to look at how the other functions were formatted before working on one. When did getName have the id parameter added to it? I don't recall seeing that in any release notes.

Not sure when. I assumed it was in b51, when all the other getBlah() functions seem to have gotten it. I actually found that out by myself, since I could find no other practical way to get the names of a list of tokens. I tried getName(Target), and voilà it worked...

[zEal]

Not sure when. I assumed it was in b51, when all the other getBlah() functions seem to have gotten it. I actually found that out by myself, since I could find no other practical way to get the names of a list of tokens. I tried getName(Target), and voilà it worked...

Yeah, looking at the source it seems both getName() and setName() had the id parameter added. A whole lot of functions got it at the same time, so it's understandable that it was accidentally omitted from the release notes.

[zEal]

The wiki just hit 301 functions. That should be all the current(including some upcoming 1.3b55 changes) functions accessible via macros.

I guess Craig was right when I suggested bumping the amount of pages a category would list up to 300, and he said that probably wouldn't be enough.