How to add an AppionLoop GUI page¶

See feature #2634 for more information on the code that supports these directions.

1. Add a wiki page to the Appion User Guide describing how to use this feature
2. Add a publication reference for the package you are using
    
   1. Edit /myami/myamiweb/processing/inc/publicationList.inc to include an entry for any references you need to add to your launch page.
       
3. Create a new form class for your feature
    
   • Create a new file in myami/myamiweb/processing/inc/forms. Call it coolFeatureForm.inc.
   • Create a class in this file that extends the BasicLoopForm class like this:
     

     require_once "basicLoopForm.inc";
     
     class AutoMaskForm extends BasicLoopForm
     {
     ...
     

   • Examples are available in autoMaskForm.inc and makeDDstackForm.inc
      
4. Set parameters needed by the BasicLoopForm class in the constructor
    
   

   //------ Set Parameters for the parent class, BasicLoopForm (general Appion params) -----//
   
   // Set the publications to be references on the web pages
   $pubList = array('appion'); // The publication reference key that you added to publicationList.inc
   $this->setPublications( $pubList );
   
   // Job Type should be unique to Appion. Used in the database to determine the type of job being run.
   $this->setJobType( 'maskmaker' ); 
   
   // The name of the folder that all runs of this job type will be stored in.
   $this->setOutputDirectory( 'mask' );  
   
   // 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.
   $this->setBaseRunName( 'maskrun' ); 
   
   // The title on the web page for this feature.
   $this->setTitle( 'Auto Masking Launcher' ); 
   
   // The Heading on the web page for this feature.
   $this->setHeading( 'Automated Masking with EM Hole Finder' ); 
   
   // 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.
   $this->setExeFile( 'automasker.py' );
   
   // A URL corresponding to a wiki page in the Appion User Guide with information on running this feature.  
   $this->setGuideURL( "http://emg.nysbc.org/projects/appion/wiki/Appion_Processing" );
   
   // True to activate "test single image" field of Appion Loop parameters.
   $this->setTestable( True ); 
   
   // The output directory will be created in the Appion run directory rather than Leginon.
   $this->setUseLegOutDir( False );
   
   // Flag to hide the description field of the run parameters. True enables the description field.
   $this->setShowDesc( False ); 
   

   
    
5. Take an inventory of the parameters that are specific to your new feature and are passed into your python executable file
   • Make a list of all the parameters that your GUI needs to expose to the user. For each parameter decide on:
     1. 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.
     2. default value
     3. 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)
     4. help text A longer description of the parameter and tips for what a user should set it to.
     5. 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?
         
6. Add your parameters help text to myami/myamiweb/processing/js/help.js
    
   • Open myami/myamiweb/processing/js/help.js
   • Add a new namespace for your form, you can copy the 'simple' section. Don't forget any commas.
   • add a help string for each of the parameter keys in your form
      
7. Add your parameters to your form class
    
   • Back in the class that you created to extend BasicLoopForm, add your parameters.
   • First set the help section using the namespace that you just added to help.js.
     

     // Get an instance of the form parameters associated with this class
     $params = $this->getFormParams();
     
     // The help section corresponds to the array key for these parameters found in help.js for popup help.
     $params->setHelpSection( "em_hole_finder" );
     

   • Add a line for each of the parameters in your form
     

     $params->addParam( "downsample", $downsample, "Downsample" );
     $params->addParam( "compsizethresh", $compsizethresh, "Component size thresholding" );