hdocConverter.html 15.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://scenari.utc.fr/hdoc/schemas/xhtml/hdoc1-xhtml.rng" type="xml"
        ?>
<html xmlns:of="scpf.org:office"
      xmlns:sp="http://www.utc.fr/ics/scenari/v3/primitive"
      xmlns:sc="http://www.utc.fr/ics/scenari/v3/core"
      xmlns="http://www.utc.fr/ics/hdoc/xhtml">
   <head>
      <title>Hdoc Converter Portal</title>
      <meta charset="utf-8"/>
      <meta name="author" content=""/>
   </head>
   <body>
	     <section data-hdoc-type="unit-of-content">
         <header>
            <h1>Hdoc Converter Portal </h1>
         </header>
			      
				        
					          <div>
										                    <p>Hdoc Converter Portal is a web platform designed to convert as many types of files to and from the <em>hdoc</em> format. The main program is in<em> javascript/php</em> and it calls <em>ANT</em> scripts that, eventually, perform each conversion.</p>
									                  </div>
				        
			      
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Demo </h1>
            </header>
					          
						            <div>
		                   
			                     <h6>Hdoc Converter Portal (v0.2) Demo </h6>
		                   
35 36
		                   <img src="./re/screen1.png/screen1.png" alt=""/>
		                   <img src="./re/screen2.png/screen2.png" alt=""/>
37 38 39 40 41 42 43 44 45 46 47 48 49
	                 </div>
					          
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Download </h1>
            </header>
					          
						            
							              <div>
               <h6>Code </h6>
												                        <p>
50
                  <a href="./re/hdoc_converter.zip/hdoc_converter.zip">hdoc_converter.zip</a>
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
               </p>
											                      </div>
						            
					          
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>User documentation </h1>
            </header>
					          
						            
							              <div>
               <h6>Purpose </h6>
												                        <p>You should keep in mind the purpose of this tool, which is to allow you converting files from and to hdoc. Even if it offers options for file storage and organization, a good use of it is still to upload, convert, download and delete.</p>
											                      </div>
						            
						            
							              <div>
               <h6>How to </h6>
												                        <p>In order to get you file into an other format, you'll need to upload it on the server. To do so, just select a file using the right-top form and click "<em>upload</em>". The file will be uploaded on the server and the program will ask for a format. Just type the format name in uppercase and click "<em>ok</em>". Your file will be added to the list and will be considered as being formatted as you typed.</p>
												                        <p>When your file is on the server, you can select it. Its background will change color, indicating it is actually selected. You can select multiple files by pressing Ctrl while clicking. Pressing Ctrl will also allow you to deselect an item.</p>
												                        <p>You can now click on "<em>convert</em>". It will open a new list of selectable item. Select all the format you need (you should not need this functionality but it exists) and then click on "<em>run conversion</em>".</p>
												                        <p>The created files will be automatically added in the list.</p>
												                        <p>When you're done converting, you can use the "<em>Download</em>" menu to get all the selected files and then use the "<em>Delete</em>" menu to free the server' space.</p>
											                      </div>
						            
						            
							              <div>
               <h6>Good uses </h6>
												                        <p>Try not to download file with the same name and not the same content. Don't be greedy and do each operation one at a time, thinking to delete the files you're done with.</p>
												                        <p>If you don't want to get lost with all the files that have the same name and not the same format, download them and remove them from the server. It takes a certain time but it's much simpler.</p>
											                      </div>
						            
					          
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Techical documentation </h1>
            </header>
					          <section data-hdoc-type="unit-of-content">
               <header>
                  <h1>Client side (Javascript) </h1>
               </header>
							              
								                
									                  <div>
														                            <p>A huge part of the code is client sided. The interface itself, in its organization, has a meaning in the actual processing of the pieces of data it represents. There are two main files for the javascript code :</p>
														                            <p>- <em>menu.js</em> that contains all the behaviors for buttons.</p>
														                            <p>-<em> file.js</em> that define all the file-oriented functions.</p>
													                          </div>
								                
								                
									                  <div>
                  <h6>menu.js </h6>
														                            <p>Each function in menu.js start with the "menu_" prefix, making them easy to recognize.</p>
														                            <p>
                     <em>menu_setup</em>() : This function is called in the index file. It will prepare the interface (mainly its jquery stuffs initializing).</p>
														                            <p>
                     <em>menu_setupDelete</em>() : A sub function called by menu_setup() that focus on the Delete menu. </p>
														                            <p>
                     <em>menu_setupDownload</em>() : A sub function called by menu_setup() that focus on the Dowload menu.</p>
														                            <p>
                     <em>menu_setupConvert</em>() : A sub function called by menu_setup() that focus on the Convert menu (not yet ready).</p>
														                            <p>
                     <em>menu_log</em>(message, type, color) : A function to push log in the new log area (just under the upload form). It write a tag with "type" as content and then the message in the given color (usually red or green).</p>
														                            <p>var <em>known_formats</em> : This global variable is a list of couples like ["FORMAT","extension"] that describes all the known format (those are printed in the "meta/formatmeta.inf" file.</p>
													                          </div>
								                
								                
									                  <div>
                  <h6>file.js </h6>
														                            <p>Each function in the file.js file also start with a "file_" prefix.</p>
														                            <p>
                     <em>file_setup</em>() : This function is called in the index file. It will load the file list from the server and setup the upload form.</p>
														                            <p>
                     <em>file_removeFileBloc</em>(fb) : Remove a filebloc from the file list. It will only erase the metadata. This function is always call after an actual file deletion.</p>
														                            <p>
                     <em>file_checkMetaInf</em>() : Checks for each file if the metadata they have are still true (by checking for each file if it still exists).</p>
														                            <p>
                     <em>file_getSelected</em>() : Returns an array of each selected file in the list.</p>
														                            <p>
                     <em>file_loadUploadedFiles</em>() : Loads the list of already uploaded files (it is called in the file_setup() function).</p>
														                            <p>
                     <em>file_fileExists</em>(file) : Asks the server for the existence of the given file. Returns true or false.</p>
														                            <p>
                     <em>file_updateMetaInf</em>() : Quite the opposite of "file_checkMetaInf", this function will replace the current server metadata with the client metadata. This function is called after a successful file add or removal.</p>
														                            <p>
                     <em>file_setUploadedFileFormat</em>(format) : This function is called when a file has succesfully been uploaded and needs to be assigned to a format. It will tell the server which format the user chose and the server will move the file in the right folder.</p>
														                            <p>
                     <em>file_addFile</em>(name,formats) : Add a file to the list. If a filebloc with the given name already exists, the formats will be added to this bloc, if not a new bloc is created.</p>
														                            <p>
                     <em>file_uploadingSetup</em>() : Sets up the uploading forms. Called in the file_setup().</p>
														                            <p>There is also a class File.</p>
														                            <p>The meta-datas are stored as JSON arrays in the file.</p>
													                          </div>
								                
								                
									                  <div>
                  <h6>About the css </h6>
														                            <p>The css code is also separated in both file and menu files. There is however a specific class that is constantly used all over the javascript code, its the "activated" class. This is involved in the button behavior and the menus visibility. </p>
													                          </div>
								                
							              
						            </section>
				        
					          <section data-hdoc-type="unit-of-content">
               <header>
                  <h1>Server side (Php) </h1>
               </header>
							              
								                
									                  <div>
														                            <p>On php side you'll find several files specialized in some requests. All the php scripts are called by Ajax.</p>
														                            <p>The upload.php file can store a file in the "Unknown" directory and then move it to a new directory when called with a "setFormat" request. The "check_file" function is designed to determine automatically the file format. If several format are possible, the program will ask the user for choosing.</p>
														                            <p>The scandir.php reads the uploads directory and can also check the existence of a file if the action field is defined to "exists".</p>
														                            <p>The delete.php allows to remove a file from the server.</p>
														                            <p>The download.php file allows to download files from the server. You must pass a "mode" field with "zip" or "single". The single mode means each selected file will be downloaded separately whereas the zip mode will make an archive with the selection.</p>
														                            <p>The convert.php file is the core of the conversion program. It receive a list of files and formats (names "targets") and will call the "convert_file" function for each couple.</p>
														                            <p>The uploadmeta.php file manages the uploaded files metadata allowing to read and write the files.</p>
														                            <p>The formatmeta.php file allows to read the format list.</p>
													                          </div>
								                
							              
						            </section>
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Supported/Unsupported </h1>
            </header>
					          
						            
							              <div>
               <h6>Supported </h6>
												                        <p>- Upload</p>
												                        <p>- Download separately</p>
												                        <p>- Delete</p>
												                        <p>- Convert</p>
											                      </div>
						            
						            
							              <div>
               <h6>Unsupported </h6>
												                        <p>- Download zip</p>
											                      </div>
						            
					          
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Known bugs </h1>
            </header>
					          
						            
							              <div>
												                        <p>When performing the same conversion twice, a second file is added to the list (but there's no second file on the server, the problem lies within the meta-data).</p>
												                        <p>The upload procedure can't be performed twice at a time.</p>
												                        <p>The meta-data access is faulty. The local data are not updated when another user changes something on server. So only the last update of the meta-data is saved.</p>
												                        <p>When a file is added to a file bloc (for example when converting) the item is drawn out of the bloc (but is selectable anyway).</p>
											                      </div>
						            
					          
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Todo list </h1>
            </header>
					          
						            
							              <div>
												                        <p>The uploading user-checks (as if a file seems to already exists) need to be improved. So does the format detection (may need to create a new meta-data file that lists the extension which aren't ambiguous).</p>
												                        <p>Multi-user-proof. (Hint : Managing a list of request on server that will be processed one by one. The client should only get the current state of the server and never edit its data itself.)</p>
												                        <p>Upload of .zip for files with dependencies (such as latex file using images).</p>
											                      </div>
						            
					          
				        </section>
		    
			      <section data-hdoc-type="unit-of-content">
            <header>
               <h1>Capitalisation </h1>
            </header>
					          
						            
							              <div>
												                        <p>That was quite a huge piece of work and it still does so. I enjoyed working on a brand new thing, something not a standard exercise. It showed itself tricky and I failed as prioritizing the important point as I failed to eventually conceive a model that answer exactly to the problem.</p>
											                      </div>
						            
					          
				        </section>
		    </section>
   </body>
</html>