How to Properly Understand FormFunction

Question

So I am trying to use Mathematica to design a DnD alignment "editor" if you will. The input I want to be provided locally via a FormFunction and will be <|"Character"->"String" , "Shift" -> {Integer , Integer} , "Reason" -> "String"|>. I am certain I misformatted the "Shift" key, but I'm trying to portray a List of 2 Integer elements.

In trying to understand FormFunction, I tried to play around with it. After a couple hours of reading and testing, I only made the following progress:

FormFunction["Test Input" -> "String" , k = Key["Test Input"]]

Typing "Test Word" into the generated form outputs:

But when I try to see the value in k, I get the output:

Key[Test Input]

And so I am here completely clueless how FormFunction can be used. The end goal I wish to get at is to use FormFunction to get inputs, and apply them to Append such that:

data = Append[data,{CHARACTER_NAME , SHIFT_LIST , REASON}]

Apologies if my question is vague, but I feel like a 5-year old trying to read Principia Mathematica with how little I understand FormFunction and Key.

PS: Here is my current code that I wish to integrate all that I have stated into:

SetDirectory[NotebookDirectory[]]

ifFileExists := (data = Import['alignment.xlsx'][[1]]);

ifFileNotExists := (Export["alignment.xlsx","Character","XLSX"] ; data = Import["alignment.xlsx"][[1]]; data = Append[data,{"Shift"}]; data = Append[data,{"Reason"}]; data = Transpose[data]; Export["alignment.xlsx",data,"XLSX"];);

If[FileExistsQ["alignment.xlsx"] , ifFileExists , ifFileNotExists]

Where data is a $n \times 3$ matrix, first row being dedicated to labels.

Answer 1

This is actually a big question. It's taken me quite awhile to wrap my head around form function. I don't think I can provide a sufficient explanation as a SE answer, but I can give a few pointers to start with and maybe we can proceed from there.

First, FormFunction is named with "Function" for a reason (or at least that's what I've concluded). If you want to interact with a particular instance of FormFunction, you'll want to apply it. In the typical case (i.e. the case with no initialization) this means putting [] after it:

FormFunction["Test Input" -> "String", k = Key["Test Input"]][]

Next, you're expected to give a function as the second argument, and that function operates on the data generated by the form when the user clicks submit. That data will be an Association. So, your function, k = Key["Test Input"] isn't actually operating on the data, it's just setting k to Key["Test Input"], regardless of the data provided by the form, and that's probably not what you want. You probably want something like this:

FormFunction["Test Input" -> "String", (k = #["Test Input"]) &]

(That's just the function, again, apply it to [] to interract interract with it.)

Interestingly, if you provide no function, you'll just see the raw data:

FormFunction["Test Input" -> "String"][]
(* <|"Test Input" -> "this is what I wrote"|> *)

At this point, we could do a deep dive into how to specify controls for your form, and that will eventually lead to FormObject. But, I'm not sure this is the path you want to follow at all. Sorry, probably should have led with that.

I don't see much utility in using FormFunction locally. I think what you probably want is CreateDialog and/or any of the related functions for getting user input (http://reference.wolfram.com/language/tutorial/CreatingDialogBoxes.html, http://reference.wolfram.com/language/guide/CustomInterfaceConstruction.html).

Check out those resources, and if you have questions about those (as opposed to FormFunction) update your question.