0ct0pu5/HRConvert2
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
HRConvert2/Documentation/CREATING_GUIS.txt
Justin Grimes 92a1fa4821
v3.2.9 - Improve docs, improve quality, update KO language pack 
-v3.2.9.
-Happy Halloween!
  -I started this commit a couple months ago and just got around to finishing it.
  -The next commit will hopefully be a small quality commit / release v3.3.
-Fix missed translation in Arabic language pack (languageStrings.php) for Default GUI.
  -'Archive Formats'
-Fix spelling, consistency errors in comments of config.php.
  -No logical changes, just comments.
  -'fules' instead of 'files'.
  -Standardize some comments around the verbiage 'Provide users with the option to'. 
-Fix bug in verifyDocumentConversionEngine() function.
  -This bug would have prevented the verifyDocumentConversionEngine() function from starting anything.
  -This would cause document conversion errors in cases where the rc.local steps of the installation instructions were not implemented.
-Update it, ko, pt, ru, uk, zh language packs.
-Fix bug with displaying number of files that were uploaded.
  -Move logic that calculates this to before the languageStrings.php call.
-Fix bug in convertGui2.php where the download button would produce a 404 unless the share link had been generated already.
  -Missing ajax request type: post.
2023-10-31 00:36:43 -04:00

280 lines
No EOL
20 KiB
Text
Raw Permalink Blame History

----------------------------------------------------------------------------------------------------------------------------------------------------------------
APPLICATION INFORMATION ...
HRConvert2, Copyright on 5/5/2023 by Justin Grimes, www.github.com/zelon88
LICENSE INFORMATION ...
This project is protected by the GNU GPLv3 Open-Source license.
https://www.gnu.org/licenses/gpl-3.0.html
APPLICATION INFORMATION ...
This application is designed to provide a web-interface for converting file formats on a server for users of any web browser without authentication.
FILE INFORMATION ...
v3.2.9.
This plain text file describes the process for creating, formatting, and installing additional GUIs into HRConvert2.
HARDWARE REQUIREMENTS ...
This application requires at least a Raspberry Pi Model B+ or greater.
This application will run on just about any x86 or x64 computer.
DEPENDENCY REQUIREMENTS ...
This application requires Debian Linux (w/3rd Party audio license), Apache 2.4, PHP 8+, LibreOffice, Unoconv, ClamAV, Tesseract, Rar, Unrar, Unzip, 7zipper,
Ffmpeg, PdfToText, Dia, PopplerUtils, MeshLab, Mkisofs & ImageMagick.
ADDITIONAL INFORMATION
HRConvert2 has one default GUI set in config.php and additional GUIs can be installed by administrators and selected by the user at runtime.
The default GUI used by HRConvrt2 can be selected by adjusting the --Default GUI-- section of config.php.
Administrators can prevent user GUI selection by adjusting the --Allow User Selectable GUI-- section of config.php.
If --Allow User Selectable GUI-- is set to TRUE in config.php, users can adjust GUI output using a 'gui' GET request.
To send a GET request, append the following string to the end of the HRConvert2 URL (without quotes): '?gui=<GUI_CODE>'
Substitute <GUI_CODE> in the string above for the name of the GUI defined by the name of the folder where it's files are contained.
If a user submits an unsupported GUI the default will be used instead.
It a supported GUI is missing required files a fatal error will occur.
<3 Open-Source
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About GUIs--
The HRConvert2 GUI is modular and separate from the core logic of the application.
This design makes modifying the look and feel of HRConvert2 easy.
This document will teach administrator and developers how GUIs are handled and structured.
In this document when we refer to a GUI, we refer to a set of files required to render HRConvert2.
In this document when we refer to a language pack, we refer to the files required to localize a GUI into a specific language.
An HRConvert2 GUI is made up of 7 components. Each component serves a specific function. The 7 components of a GUI are;
1. header.php
2. convertGui1.php
3. convertGui2.php
4. footer.php
5. styleCore.php
6. index.html
7. A 'Languages' folder with at least one ISO 639-1 supported Language Pack.
These components are stored in a folder named after the ISO 639-1 language code for the language.
The ISO-639-1 named folder is then placed inside the 'Languages' subdirectory of the installation location.
The supported ISO 639-1 language code must also be added to the --Supported Languages-- section of config.php or it will be ignored.
If --Allow User Selectable Language-- is enabled, users will be able to select this language pack by sendiing a GET request.
Users should not access the GUI directly. All requests should be directed to convertCore.php which will construct the GUI on-demand.
During operation, HRConvert2 initializes the language using the following process;
1. Initialize the language to english.
2. Build an array of languages that are included with HRConvert2.
3. Check if the $SupportedLanguages variable from config.php is set properly.
3a. If not, use the included array of default languages instead.
4. If a language was specified via GET input, sanitize it.
5. Check if the $DefaultLanguage variable from config.php is set & supported.
5a. If not, use english instead.
6. Check if the $AllowUserSelectableLanguage variable from config.php is set.
6a. If not, use $DefaultLanguage instead.
7. Check if a language was specified via GET input.
7a. If not, use $DefaultLanguage instead.
8. Check if the specified language is supported.
8a. If not, use $DefaultLanguage instead.
9. If all checks have passed and the specified language is supported, set the language to use to the one specified via GET request.
10. Reset the language GET variable to the currently specified language so future requests will continue using the same language.
11. Define all required language related files & folders.
12. Check for the existence of all required language related files & folders.
12a. If not, terminate the application.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Administration Tips--
Language Packs are contained within GUIs. GUIs typically contain multiple language packs.
Errors will occur if an installed GUI does not support every language listed in the --Supported Languages-- section of the config.php file.
Errors will occur if an installed GUI does not support the following colors: Red, Green, Blue, Grey.
Server administrators can;
Enable or disable GUIs by modifying the --Supported GUIs-- section of the config.php file.
Add or remove language packs to a GUI by creating a folder in the 'Languages' subdirectory of each enabled GUI folder.
Allow or prevent GUI selection via GET request by modifying the --Allow User Selectable GUIs-- section of the config.php file.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Development Tips--
The modular design of HRConvert2 is designed to make adding new GUIs and/or languages simple for administrators to manage and easy for developers to maintain.
If you are maintaining a branch of HRConvert2 and are focusing on a single language pack you can build your logic directly into the GUI pages themselves.
Any GUI files that are not needed can be left blank after the opening PHP tag.
To create a new GUI, copy & paste an existing GUI from the UI folder and modify the files with your favorite text editor.
To install a new GUI, place a folder in the 'UI' subdirectory of the installation location.
To enable or disable a GUI, update the --Supported GUIs-- section of the config.php file.
GUIs can utilize the icons and scripts in the default Resources directory or include their own.
If any non-stock directories are added to HRConvert2, a copy of index.html must be pasted into the directory.
Do not create any files named index.html. This filename is reserved by the application for document root protection mechanisms.
Upper Case variables are Global in scope. Lower case variables are severely limited in scope.
Limited scope variables should be manually nulled & unset after they are no longer required.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Maintenance Tips--
The 'Languages\<LANGUAGE_CODE>\languageStrings.php' file should be used to contain all localization specific code.
By placing localization specific code into 'Languages\<LANGUAGE_CODE>\languageStrings.php', GUI updates can be easily applied from one language pack to another.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About header.php--
This file contains the start of the GUI including the stylesheets, html, & head tags.
This file is always displayed.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run at the beginning of every page that HRConvert2 renders.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About convertGui1.php--
This file contains the upload field as well as some information about the application.
This file provides tokens to the user which must be included with any subsequent request by the user.
This file is displayed when no valid tokens have been supplied by the user.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run before the user has uploaded any files.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About convertGui2.php--
This file contains the available options for each submitted file.
This file dynamically selects which options to display for which files.
This file is displayed when valid tokens were supplied by the user.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run after the user has uploaded files.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About footer.php--
This file contains the end of the GUI including the Terms of Service & Privacy Policy links, when enabled.
This file is always displayed.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run at the end of every page that HRConvert2 renders.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About index.html--
This file serves to act as reliable and predictable document root protection for the server.
If users are allowed to view the document root of the server they could navigate manually to other users hosted scratch space.
This would allow users to see some temporary files of other users while they were in the process of working on them.
This file simply redirects the user to the main HRConvert2 landing page with a message asking them to wait.
The visual effect of the loading text is that a malicious actor knows they have hit some protection mechanism.
If you want to modify the global index.html file, modify the one in the installation location and then copy & paste to all other subdirectories.
HRConvert2 will automatically create new index.html files in folders it creates using the one from the installation location as a template.
This file must be manually copied & pasted into any folders that are manually created by administrators or developers of HRConvert2.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About 'Languages' Folder--
This folder must exist in each language pack.
This folder contains the major language-specific files.
Each subdirectory of this folder represents a different language pack.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Variable Scope--
This GUI only has access to certain variables. Variables that are available to the GUI include;
$GuiFiles, $LanguageFiles, $LanguageStringsFile, $GuiHeaderFile, $GuiFooterFile, $GuiUI1File, $GuiUI2File, $CoreLoaded, $ConvertDir, $ConvertTempDir,
$Token1, $Token2, $SesHash, $SesHash2, $SesHash3, $SesHash4, $Date, $Time, $TOSURL, $PPURL, $ShowFinePrint, $PDFWorkArr, $ArchiveArray, $DearchiveArray,
$DocumentArray, $SpreadsheetArray, $ImageArray, $ModelArray, $DrawingArray, $VideoArray, $SubtitleArray, $StreamArray, $MediaArray, $PresentationArray,
$ConvertGuiCounter1, $ConsolidatedLogFileName, $Alert, $Alert1, $Alert2, $Alert3, $FCPlural, $FCPlural1, $FCPlural2, $FCPlural3, $File, $Files, $FileCount,
$SpinnerStyle, $SpinnerColor, $PacmanLoc, $Allowed, $AllowUserVirusScan, $AllowUserShare, $SupportedConversionTypes, $FullURL, $LanguageDir, $FaviconPath,
$DropzonePath, $DropzoneStylesheetPath, $StylesheetPath, $JsLibraryPath, $JqueryPath, $GUIDirection, $SupportedFormatCount, $GUIAlignment, $HeaderDisplayed,
$UIDisplayed, $FooterDisplayed, $LanguageStringsLoaded, $GUIDisplayed
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Colors--
The GUI gets color specific styles from the $ButtonCode variable.
The $ButtonCode variable contains the color specific CSS for the GUI.
The $ButtonCode variable is set by Resources/styleCore.php.
There are 4 supported colors, and the code for each color is contained in styleCore.php.
The loading spinner will change color as well. There is one spinner .gif file for each style & supported color.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Loading Spinners--
There are 6 loading spinners to choose from that can be set in config.php.
Each spinner is available in 4 colors.
The color of the spinner can be adjusted separately from the color of the rest of the GUI.
The $PacmanLoc variable contains the relative path to use for the selected spinner.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Uploaded Files--
The $Files variable contains an array of all valid uploaded filenames that exist in the users scratch space.
The GUI must iterate through this array, determine what format it is, & display the correct options.
When submitting a file as input, only submit it's name with extension. HRConver2 will determine the path.
When redirecting the user to a download you must send them to the proper filename and hosted file path.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About The API--
HRConvert2 supports inputs through POST and GET requests.
All requests should be submitted to convertCore.php.
If Token1 and Token2 are not submitted via POST input, then convertGui1.php will be displayed prompting for file uploads.
If Token1 and Token2 are both submitted via POST input, then convertGui2.php will be displayed providing conversion options.
The included GUIs makes extensive use of JQuery + Ajax to submit requests & process responses.
All API requests should be sent to convertCore.php.
GUI files cannot handle API requests and will generate an error if they receive API requests.
All API inputs are sanitized by the core for special characters to prevent malicious or unintentional code injection.
As a result of sanitization the filename may change after upload.
To use HRConvert2 via POST & GET requests only;
1. Submit a blank GET request to convertCore.php to retrieve the value of Token1 and Token2.
2. Submit a file upload along with Token1 and Token2 to convertCore.php via POST input.
3. Submit an uploaded filename, a new filename, a file extension, Token1, Token2, and a valid set of file conversion options to convertCore.php via POST input.
The following is a list of supported GET inputs & their supported values;
noGui - 1
gui - String
language - String
The following is a list of supported POST inputs & their supported values;
Token1 - String
Token2 - String
height - Integer
width - Integer
rotate - Integer
bitrate - Integer
method - 0 or 1
archive - 1
extension - String
filesToArchive - String or Array of Strings
filesToDelete - String or Array of Strings
download - String or Array of Strings
archExtension - String
userfilename - String
userconvertfilename - String
pdfworkSelected - String or Array of Strings
convertSelected - String or Array of Strings
pdfextension - String
userpdfconvertfilename - String
scantype - String (clamav or scancore or all)
filestoscan - String or Array of Strings
clamScanButton - 1
scancorebutton - 1
scanallbutton - 1
----------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Open Source--
This application is open-source under the terms of the GPLv3 license, meaning anybody can obtain a copy and put it to use for personal or business use.
If you modify this application and use it to make money or offer it to your users as a product, you MUST make the source code with your changes available.
The ideal way to do this would be to fork the official zelon88/HRConvert2 repository on Github and make changes there.
Alternatively you can submit a pull request and have your changes added to the official repository (with credit due to you, of course).
By reciprocating changes & improvements with one another we can all enjoy the best, most capable and bug free version HRConvert2.
If you modify this codebase please consider making your changes public so everyone can benefit from them.
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Reference in a new issue View git blame Copy permalink