@@ -3,9 +3,9 @@
ActionAuthoring can be roughly divided into three steps: A) Placing a new Action in the menu-hierarchy, B) Describing the looks and behavior of the Action-GUI and C) Defining, how R-code is to be generated from the settings, the user makes in the GUI. Those will be dealt with in turn.
!!! A) Creating a new Action and placing it in the menu-structure
-For now, all Actions are kept in a single directory-tree. Each level in the menu-hierarchy has its own sub-directory, and every single action is also kept in it's own sub-directory. Every (sub-)directory, then, contains a file calle
"description.xml", which is a very short XML-file that keeps just enough information to place the action (or menu-level) in the menu-hierarchy. Here's what a "description.xml"-file looks like:
+For now, all Actions are kept in a single directory-tree. Each level in the menu-hierarchy has its own sub-directory, and every single action is also kept in it's own sub-directory. Every (sub-)directory, then, contains a file called
"description.xml", which is a very short XML-file that keeps just enough information to place the action (or menu-level) in the menu-hierarchy. Here's what a "description.xml"-file looks like:
1) for a directory:
<document>
@@ -22,13 +22,61 @@ <entry caption="cool bogus test"/>
<action filename="empty.action"/>
</document>
-Here the content-tpye
is "entry", hence this directory is taken to contain a single action. Subdirectories of this directory are ignored. The entry-tag is the same as for directores. For actions, however, one further tag is expected: "action" with the attribute filename.
+Here the content-type
is "entry", hence this directory is taken to contain a single action. Subdirectories of this directory are ignored. The entry-tag is the same as for directores. For actions, however, one further tag is expected: "action" with the attribute filename.
-The filename to specify is that of the more detailed description of the Action in XML-format, which will be described below. That file is parsed every time, the Action is selected form
the menu. Note, that this file _should_ reside in the same directory as the description.xml. While you may specify a relative or absolute path to a file in a different directory, that may not be very portable across platforms, and should therefore be avoided.
+The filename to specify is that of the more detailed description of the Action in XML-format, which will be described below. That file is parsed every time, the Action is selected from
the menu. Note, that this file _should_ reside in the same directory as the description.xml. While you may specify a relative or absolute path to a file in a different directory, that may not be very portable across platforms, and should therefore be avoided.
If you add new Actions at run-time, you will have to get Obversive to regenerate the menu-structure. Currently the only way to do so (besides restarting obversive), is to select a different actions-directory in Preferences->Actions, and then set the correct one, again.
+
+{DSP: I need an example that is a bit more concrete to get this. Let me indicate what I do (or don't) understand up to this point through the use of an example. Assume we wanted to create access to a set of regression tools through the use of a menu bar pull-down called "Regression", one of the options within this menu would be "Logistic Regression", which would then have sub-options (using a cascading menu) of "Logit" and "Probit". My understanding that to implement what I've indicated thus far would result in the following XML code (placed in a file called "description.xml", but I'm not sure where this file would live):
+
+ <document>
+ <content type="dir"/>
+ <entry caption="Regression"/>
+ <document>
+ <content type="dir"/>
+ <entry caption="Logistic"/>
+ <document>
+ <content type="entry"/>
+ <entry caption="Logit"/>
+ <action filename="logit.action"/>
+ </document>
+ <document>
+ <content type="entry"/>
+ <entry caption="Probit"/>
+ <action filename="probit.action"/>
+ </document>
+ </document>
+ </document>
+
+The only thing that seems potentially wrong to me in the code above is the nested "dir" tags related to the "Logistic Regression" menu entry. It seems to me that it would more naturally lend itself to a <content type="entry"/> tag, but it doesn't really have an action script to go with it.
+
+The other thing I'm really unclear about is what is the nature of the file directory structure that goes with this. Let's assume that obveRsive lives in /usr/local/obversive (or on a windows box in C:\Program Files\obversive). Would the implied directory structure then be:
+
+/usr/local/obversive (C:\Program Files\obversive)
+ /usr/local/obversive/Regression (C:\Program Files\obversive\Regression)
+ /usr/local/obversive/Regression/Logistic (C:\Program Files\obversive\Regression\Logistic)
+ logit.action probit.action logit.tpt probit.tpt
+
+or would it be:
+
+/usr/local/obversive (C:\Program Files\obversive)
+ /usr/local/obversive/Regression (C:\Program Files\obversive\Regression)
+ /usr/local/obversive/Regression/Logistic (C:\Program Files\obversive\Regression\Logistic)
+ /usr/local/obversive/Regression/Logistic/Logit (C:\Program Files\obversive\Regression\Logistic\Logit
+ logit.action logit.tpt
+ /usr/local/obversive/Regression/Logistic/Probit (C:\Program Files\obversive\Regression\Logistic\Probit
+ probit.action probit.tpt
+
+or am I completely clueless about the directory structure? I could imagine that obversive has no explicit directory structure, so that the action author is free to do what s/he likes in this regard. For example the author would just provide a path to the file using an action tag that looked like:
+
+<action filename="/home/username/Regression/Logistic/logit.action"/>
+
+I understand that this results in complete chaos, so we may require all actions to live in a single directory (say /usr/local/obversive/actions) with the possibility of action authors creating sub-directories under this main actions directory.
+
+If the structure is more along the lines of my first two examples, then the question I have is how is the needed directory structure created? Does an action author need to explicitly create the needed directory structure, or is it created automatically by obveRsive?}
!!! B) Defining the Action
So now you have a new Action placed in the obversive menu-structure. Next you'll have to define the action in the file you specified in description.xml. Below is the code of the "Test Action" with explanations in between:
