Using the Upload Progress Meter in a Form Controller

If you are creating a Jamroom Module that will allow users the ability to Upload media files into Jamroom, it is helpful to use the Upload Progress Meter to allow the user to have a visual indicator of their upload progress.  Using the Upload Progress Meter in a module Form Controller is fairly easy.

Use the proper code in your Create/Modify form

The first step is to make sure you setup your Create or Modify item form properly to support the Jamroom Upload Progress Meter:

// Set our progress flag so we know to include the proper js
$GLOBALS['JR_PROGRESS_ENABLE'] = true;

jmHtmlBegin('File Upload');
$_args = array(
  'mode' => 'jrFileUpload.php|save_files'
);
jrProgressFormBegin('jrFileUpload.php',$_args);
jmSpanCell('File Upload','This is the Help',30,'html_modify.png');
jmInput('Select a File',"meter_file_1",'file');
jrProgressBarHtml();
jrFormSubmit('Upload File','undo changes',false,'admin.php',false,true,'media');
jmEndForm();
jmBodyEnd();
jmHtmlEnd();

For our example here where are using a VERY small form that simply shows a single File Upload form element - it will work to illustrate what is needed.

// Set our progress flag so we know to include the proper js
$GLOBALS['JR_PROGRESS_ENABLE'] = true;

In our first section, when need to set a special global "flag" to let Jamroom know you want to enable the Upload Progress Meter.  This ensures all of the supporting JavaScript files are setup properly and included on the page.  Failure to set the JR_PROGRESS_ENABLE flag to "true" will prevent the Upload Progress Meter from working.

$_args = array(
  'mode' => 'jrFileUpload.php|save_files'
);
jrProgressFormBegin('jrFileUpload.php',$_args);

The next important part is the call to "jrProgressFormBegin" - this MUST be used in place of the normal jmBeginForm() function.  It accepts 2 arguments - the first being the NAME of your Form Controller script, and the second an array that defines the "mode" that will be called in your Form Controller when the file(s) are finished uploading.  Note the special syntax:   Form_Controller|Mode - i.e. your Script name, then a pipe sign, then the "mode" that will be set in the $_POST call to your form controller.

jmInput('Select a File',"meter_file_1",'file');

Next we have our call to jmInput - this function actually creates the File Upload form element.  Note that we give the form element a name of "meter_file"1".  Your field name MUST be called "meter_file_#", where # is a unique number for the field.

jrProgressBarHtml();
jrFormSubmit('Upload File','undo changes',false,'admin.php',false,true,'media');

The final section that is needed that is different from a normal Control Panel form is the call to "jrProgressBarHtml" - wherever this function is called in relation to the form, that is where the meter will appear in the form.  Also note that the jrFormSubmit function call includes a "media" option for the 7th argument - this is needed to let Jamroom know it needs to submit the form to the progress meter.

That's it - once in place and working the uploaded file will appear in the $_post variable just as if it was uploaded without the progress meter.