How to add an AppionLoop GUI page » History » Version 41
Amber Herold, 08/06/2014 12:22 PM
1 | 38 | Amber Herold | h1. How to add an Appion GUI job launch page |
---|---|---|---|
2 | 1 | Amber Herold | |
3 | 37 | Amber Herold | See feature #2634 and #2841 for more information on the code that supports these directions. |
4 | 1 | Amber Herold | |
5 | # *Add a wiki page to the [[Appion_Processing|Appion User Guide]] describing how to use this feature* |
||
6 | 9 | Amber Herold | |
7 | 10 | Amber Herold | ** You can just add a shell and a description of what it does to start. You can add screen shots and parameter details after adding the GUI completely. You just need to have the URL available for subsequent steps in this guide. If you are at a total loss, just link to the main table of contents: [[Appion Processing]] |
8 | |
||
9 | 1 | Amber Herold | # *Add a publication reference for the package you are using* |
10 | |
||
11 | 15 | Amber Herold | ## Edit source:/trunk/myamiweb/processing/inc/publicationList.inc to include an entry for any references you need to add to your launch page. |
12 | 40 | Amber Herold | ## Adding the publication info here will also automatically take care of various ways of formatting the reference and make sure it is properly added to the list of sources available at index.php which provides the user with references they can copy and paste into their publications. It is important to test this and make sure your new publication shows up correctly in the index page as this is a very useful feature of Appion. |
13 | 1 | Amber Herold | |
14 | # *Create a new form class for your feature* |
||
15 | 2 | Amber Herold | |
16 | 1 | Amber Herold | ** Create a new file in myami/myamiweb/processing/inc/forms. Call it coolFeatureForm.inc. |
17 | 22 | Amber Herold | ** Decide which Basic Form class you will be using as a base class. |
18 | ### If you are adding a GUI to launch a python script that is based on the appionLoop class that is found in appionLoop2.py, you will base your GUI class on the BasicLoopForm. |
||
19 | **** Create a class in this file that extends the BasicLoopForm class like this: |
||
20 | 1 | Amber Herold | <pre> |
21 | require_once "basicLoopForm.inc"; |
||
22 | |||
23 | 11 | Amber Herold | class CoolFeatureForm extends BasicLoopForm |
24 | 1 | Amber Herold | { |
25 | ... |
||
26 | </pre> |
||
27 | 22 | Amber Herold | **** Examples are available in source:/trunk/myamiweb/processing/inc/forms/autoMaskForm.inc and source:trunk/myamiweb/processing/inc/forms/makeDDStackForm.inc |
28 | |
||
29 | --OR-- |
||
30 | ### If you are not using the appionLoop python script, base your new GUI form on the basicLayoutForm class (source:trunk/myamiweb/processing/inc/forms/basicLayoutForm.inc) |
||
31 | **** Create a class in this file that extends the BasicLayoutForm class like this: |
||
32 | 20 | Amber Herold | <pre> |
33 | 1 | Amber Herold | require_once "basicLayoutForm.inc"; |
34 | 20 | Amber Herold | |
35 | class CoolFeatureForm extends BasicLayoutForm |
||
36 | { |
||
37 | ... |
||
38 | </pre> |
||
39 | 22 | Amber Herold | **** Example: source:trunk/myamiweb/processing/inc/forms/uploadExternalRefine.inc |
40 | 12 | Amber Herold | ** Use the following class diagram as reference |
41 | !guiclassdiagram.jpg! |
||
42 | 2 | Amber Herold | |
43 | 25 | Amber Herold | # *Set parameters needed by the Basic Form classes in the constructor* |
44 | 1 | Amber Herold | |
45 | <pre> |
||
46 | 27 | Amber Herold | class CoolFeatureForm extends BasicLayoutForm |
47 | { |
||
48 | |||
49 | 28 | Amber Herold | // This is the constructor function. It is called as soon as this class is |
50 | // instantiated with a line like: $form = new CoolFeatureForm($expId, $extraHTML). |
||
51 | // The first 2 parameters are needed for the BasicLayoutForm class that this class extends from. |
||
52 | // The rest of the parameters are specific to this form. |
||
53 | |||
54 | function __construct( $expId, $extraHTML='', $stackid='', $modelid='', $uploadIterations='', $mass='', $apix='', $box='') |
||
55 | 27 | Amber Herold | { |
56 | // You must first call the parent class(BasicLayoutForm) constructor. |
||
57 | // Pass it the $expId and $extraHTML variables. Errors and test results are passed through $extraHTML. |
||
58 | 28 | Amber Herold | |
59 | 27 | Amber Herold | parent::__construct($expId, $extraHTML); |
60 | |||
61 | //------ Set Parameters for the parent class, BasicLoopForm or BasicLayoutForm (general Appion params) -----// |
||
62 | 1 | Amber Herold | |
63 | 27 | Amber Herold | // Set the publications to be references on the web pages |
64 | $pubList = array('appion'); // The publication reference key that you added to publicationList.inc |
||
65 | $this->setPublications( $pubList ); |
||
66 | 1 | Amber Herold | |
67 | 27 | Amber Herold | // Job Type should be unique to Appion. Used in the database to determine the type of job being run. |
68 | $this->setJobType( 'maskmaker' ); |
||
69 | 1 | Amber Herold | |
70 | 27 | Amber Herold | // The name of the folder that all runs of this job type will be stored in. |
71 | $this->setOutputDirectory( 'mask' ); |
||
72 | 1 | Amber Herold | |
73 | 27 | Amber Herold | // A portion of the run name that will be common (by default) to all runs of this job type. A unique number is appended to individual run names. |
74 | $this->setBaseRunName( 'maskrun' ); |
||
75 | 2 | Amber Herold | |
76 | 27 | Amber Herold | // The title on the web page for this feature. |
77 | $this->setTitle( 'Auto Masking Launcher' ); |
||
78 | 2 | Amber Herold | |
79 | 27 | Amber Herold | // The Heading on the web page for this feature. |
80 | $this->setHeading( 'Automated Masking with EM Hole Finder' ); |
||
81 | 26 | Amber Herold | |
82 | 27 | Amber Herold | // The name of the python executable file that this GUI corresponds to. It should be based on the AppionLoop class and located in the myami/appion/bin folder. |
83 | $this->setExeFile( 'automasker.py' ); |
||
84 | 26 | Amber Herold | |
85 | 27 | Amber Herold | // A URL corresponding to a wiki page in the Appion User Guide with information on running this feature. |
86 | $this->setGuideURL( "http://emg.nysbc.org/projects/appion/wiki/Appion_Processing" ); |
||
87 | 3 | Amber Herold | |
88 | 27 | Amber Herold | // True to activate "test single image" field of Appion Loop parameters. |
89 | $this->setTestable( True ); |
||
90 | 3 | Amber Herold | |
91 | 27 | Amber Herold | // The output directory will be created in the Appion run directory rather than Leginon. |
92 | $this->setUseLegOutDir( False ); |
||
93 | 3 | Amber Herold | |
94 | 27 | Amber Herold | // Flag to hide the description field of the run parameters. True enables the description field. |
95 | $this->setShowDesc( False ); |
||
96 | 3 | Amber Herold | |
97 | 27 | Amber Herold | // Flag to use the cluster parameter form rather than the run parameter form. |
98 | // Reconstructions and remote jobs use the cluster parameters, generic single processor jobs use run parameters. |
||
99 | // Set to True to use Cluster Parameters |
||
100 | $this->setUseCluster( False ); |
||
101 | 3 | Amber Herold | </pre> |
102 | 5 | Amber Herold | |
103 | 3 | Amber Herold | # *Take an inventory of the parameters that are specific to your new feature and are passed into your python executable file* |
104 | ** Make a list of all the parameters that your GUI needs to expose to the user. For each parameter decide on: |
||
105 | 41 | Amber Herold | ### *id* I might also call it a parameter key or name. This should match the name of the parameter as it appears on the command line. So a flag in a command that looks like "--mycoolflag" should be named "mycoolflag" in this class. AVOID using names with hyphens like _max-iter_. Try using underscores instead if possible. |
106 | 3 | Amber Herold | ### *default value* |
107 | ### *label* This is the text that is actually shown to the user in the GUI next to the GUI element associated with it (check box, selection, text, etc) |
||
108 | ### *help text* A longer description of the parameter and tips for what a user should set it to. |
||
109 | ### *validations* Decide what should be considered valid values for this parameter. Is it required? Does it have to be a number or greater than zero? |
||
110 | |
||
111 | # *Add your parameters help text to myami/myamiweb/processing/js/help.js* |
||
112 | |
||
113 | 5 | Amber Herold | ** Open source:/trunk/myamiweb/processing/js/help.js |
114 | 3 | Amber Herold | ** Add a new namespace for your form, you can copy the 'simple' section. Don't forget any commas. |
115 | ** add a help string for each of the parameter keys in your form |
||
116 | 1 | Amber Herold | |
117 | # *Add your parameters to your form class constructor* |
||
118 | 5 | Amber Herold | |
119 | 29 | Amber Herold | ** Back in the constructor function of the class that you created to extend BasicLoopForm or BasicLayoutForm, add your parameters. |
120 | 5 | Amber Herold | ** First set the help section using the namespace that you just added to help.js. |
121 | <pre> |
||
122 | // Get an instance of the form parameters associated with this class |
||
123 | $params = $this->getFormParams(); |
||
124 | |||
125 | // The help section corresponds to the array key for these parameters found in help.js for popup help. |
||
126 | $params->setHelpSection( "em_hole_finder" ); |
||
127 | </pre> |
||
128 | ** Add a line for each of the parameters in your form. The first parameter of the addParam() function is the id of the param, followed by the default value (passed into the constructor), followed by the label (what is shown to the user in the GUI). |
||
129 | <pre> |
||
130 | $params->addParam( "downsample", $downsample, "Downsample" ); |
||
131 | 1 | Amber Herold | $params->addParam( "compsizethresh", $compsizethresh, "Component size thresholding" ); |
132 | 5 | Amber Herold | </pre> |
133 | ** Add any validation requirements that are needed for your parameters. Use the addValidation() function of the FormParameter class. The first field is the parameter id. The second field is a key word that corresponds to the type of validation needed. |
||
134 | <pre> |
||
135 | $params->addValidation( "numpart", "req" ); |
||
136 | </pre> |
||
137 | 34 | Amber Herold | ** Avaialble validation types are as follows, and updates can be found in formValidator.php (source:trunk/myamiweb/inc/formValidator.php) |
138 | 5 | Amber Herold | <pre> |
139 | // available validations, check formValidator.php for changes: |
||
140 | /* |
||
141 | * required : addValidation("variableName", "req"); |
||
142 | * MaxLengh : addValidation("variableName", "maxlen=10"); |
||
143 | 7 | Amber Herold | * MinLengh : addValidation("variableName", "mixlen=3"); |
144 | * Email : addValidation("variableName", "email"); |
||
145 | 6 | Amber Herold | * Numeric : addValidation("variableName", "num"); |
146 | * Alphabetic : addValidation("variableName", "alpha"); |
||
147 | * Alphabetic and spaces : addValidation("variableName", "alpha_s"); |
||
148 | * Alpha-numeric and spaces: addValidation("variableName", "alnum_s"); |
||
149 | * Float: addValidation("variableName", "float"); |
||
150 | * absolute path: path_exist: addValidation("variableName", "abs_path"); |
||
151 | * path existence : addValidation("variableName", "path_exist"); |
||
152 | * folder permission : addValidation("variableName", "folder_permission"); |
||
153 | * file existence : addValidation("variableName", "file_exist"); |
||
154 | * Float w/fixed decimal space: addValidation("variableName", "float_d=2"); |
||
155 | */ |
||
156 | </pre> |
||
157 | |
||
158 | # *Generate a form for the parameters that are specific to this program (not AppionLoop params)* |
||
159 | |
||
160 | 33 | Amber Herold | ** There are 2 places available for adding your own parameters to the GUI page. The most common place is to the Right Hand side of the Appion Loop parameters. To add your parameters to this section of the screen, override the function called *generateAdditionalFormRight()* in your form class extending BasicLoopForm. You may also add parameters to the space on the left directly below the Appion Loop parameters by overriding the function called *generateAdditionalFormLeft()*. If you are extending your class from BasicLayoutForm, anything added to generateAdditionalFormLeft() will show up directly below the Run or Cluster parameters at the top of your form. These functions return the HTML code required to display your parameter GUI elements to the user. You may add HTML here directly. |
161 | 32 | Amber Herold | |
162 | 33 | Amber Herold | ** To add the HTML code for an input element for your parameter, use one of the functions available in the FormParameters (source:trunk/myamiweb/inc/formParameters.inc) class. The first field of these functions is always the parameter id. |
163 | 30 | Amber Herold | Current functions available include: |
164 | 31 | Amber Herold | ### insertTextArea( $name, $rows=3, $cols=65, $note='', $helpkey='' ) |
165 | ### insertTextField( $name, $size=20, $note='', $helpkey='' ) |
||
166 | ### insertTextFieldInRow( $name, $size=20, $note='', $helpkey='' ) |
||
167 | ### insertStackedTextField( $name, $size=20, $note='', $helpkey='' ) |
||
168 | ### insertCheckboxField( $name, $note='', $helpkey='' ) |
||
169 | ### insertRadioField( $name, $value, $label, $note='', $helpkey='' ) |
||
170 | 30 | Amber Herold | ### insertSelectField( $name, $options, $note='', $helpkey='' ) |
171 | 1 | Amber Herold | ### insertStackedSelectField( $name, $options, $note='', $helpkey='' ) |
172 | 35 | Amber Herold | **** Options for the SelectField functions MUST be a dictionary, to allow a more descriptive string to be shown to the user for each option, if desired. If the option value and description should be the same, then that value should be both the key and the value. The key is what gets kept in the POST array.<pre>$options = array( "first" => "first description", "second" => "second description"...)</pre> |
173 | 36 | Amber Herold | |
174 | 6 | Amber Herold | <pre> |
175 | public function generateAdditionalFormRight() |
||
176 | { |
||
177 | 1 | Amber Herold | // Calling updateFormParams() will check the php $_POST array for any values that were previously set for the parameters in this form. |
178 | 7 | Amber Herold | $this->updateFormParams(); |
179 | $params = $this->getFormParams(); |
||
180 | |||
181 | $fieldSize = 3; |
||
182 | |||
183 | $html .= "<b>Make DD stack params:</b><br />\n"; |
||
184 | |||
185 | $html.= $params->insertCheckboxField( "align" ); |
||
186 | $html.= $params->insertCheckboxField( "defergpu" ); |
||
187 | 1 | Amber Herold | $html.= $params->insertCheckboxField( "no_keepstack" ); |
188 | $html.= $params->insertTextFieldInRow( "bin", $fieldSize ); |
||
189 | 7 | Amber Herold | |
190 | 29 | Amber Herold | // It is important to return the $html variable. This contains all the |
191 | // html code needed to display your parameters. |
||
192 | return $html; |
||
193 | 1 | Amber Herold | } |
194 | 7 | Amber Herold | </pre> |
195 | |
||
196 | 8 | Amber Herold | # *If you have implemented "test single image" on the python side, add code to display the test results in your class extending BasicLoopForm* |
197 | 7 | Amber Herold | |
198 | 29 | Amber Herold | ** You can use the getTestResults() function in autoMaskForm.inc (source:trunk/myamiweb/processing/inc/forms/autoMaskForm.inc) as an example. |
199 | 7 | Amber Herold | <pre> |
200 | // getTestResults() should return the HTML code needed to display test results any way this method |
||
201 | // prefers to have them displayed. The results will be placed below a printout of the test command and |
||
202 | // above the launch form. Note that an instance of this class is not required to use this function. |
||
203 | static public function getTestResults( $outdir, $runname, $testfilename ) |
||
204 | 1 | Amber Herold | { |
205 | 8 | Amber Herold | ... |
206 | 1 | Amber Herold | </pre> |
207 | 10 | Amber Herold | |
208 | # *Add a link to your page in the menuprocessing.php file or from another page* |
||
209 | |
||
210 | 7 | Amber Herold | ** The menuprocessing file is a bit tricky to work with.If you do not link to your page from there, look for the appropriate php page where your feature should launch from. |
211 | 1 | Amber Herold | ** You will add a link to runAppionLoop.php and pass the experiment ID and the name of your new form class in the URL. Here are a couple of examples with the MakeDDStackForm class and the AutoMaskForm Class: |
212 | <pre> |
||
213 | $ddStackform = "MakeDDStackForm"; |
||
214 | 'name'=>"<a href='runAppionLoop.php?expId=$sessionId&form=$ddStackform'>Create frame stack</a>", |
||
215 | </pre> |
||
216 | <pre> |
||
217 | $form = "AutoMaskForm"; |
||
218 | echo " <h3><a href='runAppionLoop.php?expId=$expId&form=$form'>Auto Masking</a></h3>\n"; |
||
219 | </pre> |
||
220 | ** Note that the name of the class MUST match the name of the PHP file that the class is defined in. So if you extended the BasicLoopForm to a class named CoolFeatureForm, the file where that class lives must be at myami/myamiweb/processing/inc/forms/coolFeatureForm.inc. |
||
221 | |
||
222 | # *Add installation instructions for any new 3rd party software required* |
||
223 | |
||
224 | ** If this feature requires 3rd party software on the python side on the processing host, add directions for installing this software now. It should have a new wiki page under the [[Processing Server Installation]] instructions. |
||
225 | |