1. General information
1.1. Description of the control
File is a control for inserting a file attachment using the “Browse...” button. The maximum size of an embedded file attachment can be limited to a predetermined size. The file uses the “int” database type, and stores in the database the ID of the file attachment, which is physically stored on disk in the “Files” directory, and has descriptive data with the file name and size stored in a separate entry in the “sfiles” database table.
The File control always inserts a single file attachment. To upload multiple files at once, or to select and upload multiple file attachments simultaneously in an edit form (bulk upload via drag-and-drop or a single button), use the DROPZONE (drag-and-drop area) and UPLOADBUTTON (file selection button) server functions, which are described in the separate guide Server functions.
The “...” button next to the control offers further options. It is displayed only if it offers at least one of them, and never in an edit form that cannot be modified:
- Insert... – only on a mobile device; downloads a file from a URL pasted from the clipboard and saves it as a file attachment.
- Browse Cloud – offers the files of the record's directory in the public directory. It is displayed only if a public directory is set (the “PublicDirectory.txt” configuration file in the “Config” directory), never in NET Genium Online and never to the anonymous user.
- New from template – creates a new file attachment from a print template selected on the “Templates” tab.
- Rename – renames the inserted file attachment. It is not displayed to the anonymous user or when the “Hide ‘Rename’ button” option is checked.
The edit form is always refreshed after a file is uploaded.
1.2. Create a new control
- A detailed description of creating new controls in the edit form is provided in the separate guide Creating edit form controls.
1.3. Edit or delete a control
- For each existing control, a pencil icon appears on the left side of the edit form to change or delete the control's settings.
- Individual controls can be moved vertically in the edit form using the Drag&Drop method. Moving consists of grabbing the control, preferably behind its name located in the left column of the edit form, and then dragging it to the desired position in the edit form.
- Controls can be moved only with the “Drag&Drop” check box located above the toolbar with controls selected. For security reasons, this check box is cleared after each login to the application, so that a control is not moved by accident.
- Deleting a file results in the irreversible deletion of the database column associated with that file in the database, and thus in the deletion of its values in all records in the database table. The attachment files remain on the disk in the “Files” directory together with their records in the “sfiles” table, but no record refers to them any more.
2. List of tabs in the control settings dialog
- General – Setting general properties
- Templates – Template settings
- Print to template – Template print settings
- Button – Button settings that can be displayed to the right of the control
- Help – Settings for help text that can be displayed on the right side of the edit form
- Filter – Setting the filter that can be displayed in the view table in the column header
- Rights – Rights settings
- Administration – Setting other properties
2.1. “General” tab
2.1.1. Name
- The name of the control displayed in the edit form in a separate column with a colored background to the left of the control itself.
2.1.2. Abbreviated name
- Optional control name displayed in the view table header if the control is selected as one of the view table columns.
- If an abbreviated name is specified, the full name of the control is displayed in the tooltip above the abbreviated name.
- If an abbreviated name is not specified, the full name of the control is displayed in the header of the view table.
- The abbreviated name “ ” (fixed space) can completely hide the name of the control displayed in the view table.
2.1.3. Dictionary...
- The dictionary lists the names of other controls, forms, view pages, categories, applications, and application groups used across the entire application.
- The dictionary search is used to design the correct control name and to maintain the consistency of the nomenclature throughout the application so that controls with the same meaning located in different places in the application are named in the same way.
2.1.4. Maximum size
- The maximum size of the uploaded file in MB. The field accepts values from 0 to 1024.
- A file larger than the set maximum size is not uploaded after being selected with the “Browse...” button, and a warning is displayed.
- An empty value or 0 means the upload limit set on the server, 50 MB by default; it can be increased with the “MaxRequestLength.txt” configuration file, a detailed description of which is provided in the separate guide NET Genium settings. For inserting with the “Insert...” item, a limit of 10 MB applies in that case.
2.1.5. Options
- Required field
- Checking the required field determines whether the edit form should require the insertion of a file attachment before saving the record to the database.
- The required field setting does not affect the database type of the column that is associated with the current control in the database. All database columns are set to accept the database value “null”.
- The value can be stored in the database as an integer or as a “null” database value. When compiling the conditions of a database query, it is therefore important to take into account the alternative that the database value “null” is stored in a column in the database table in addition to zero – an integer. Such a condition may look like this in NG speech: file equals “0” or file is not defined. And now in SQL: ng_file = 0 OR ng_file IS NULL.
- Hide “Remove” button
- Checking this box determines whether the “Remove” button, which is used to remove an existing file attachment stored in the control, should be hidden. Even with the “Remove” button hidden, it is possible to upload another file attachment using the “Browse...” button.
- Hide “Rename” button
- Checking this box determines whether the “Rename” item, which is used to rename an existing file attachment stored in the control, should be hidden in the menu of the “...” button.
- Hidden field
- The hidden field setting determines whether the control should be part of an edit form, but should not be visible in user mode.
- The hidden control, including the filled value, can be found in the source code of the web page. It cannot therefore be used as part of security measures, the rights to the control are used for this.
2.2. “Templates” tab
2.2.1. Templates
- Templates define a list of print templates from the “NETGenium\Templates” directory, from which a new file attachment can be created directly from the control with the “New from template” item in the menu of the “...” button.
- The “New from template” item offers only the selected templates that actually exist in the “Templates” directory. The document can be created only in an edit form that can be modified.
- Print templates must be saved in the “NETGenium\Templates” directory. It is possible to copy files to this directory directly from the server desktop, or via the dialog for NET Genium settings on the “Print templates” tab.
- In print templates, all variables in the edit form are automatically replaced, as is the case with normal button printing. A detailed description of templates is provided in the separate guide Print templates.
2.3. “Print to template” tab
2.3.1. Nested records
- Nested records define how database records from view tables or other visual controls will be copied to Excel print templates.
- Insert new rows – the first record of the view table will be inserted at the place where the variables with the identifiers of the table columns were found in the print template. The other records will always be inserted after the first row of the table on the newly created row, so that the rest of the document will scroll downwards.
- Overwrite rows – the first record of the view table will be inserted at the place where the variables with the identifiers of the table columns were found in the print template. Other records will overwrite the rows in the document after the first row of the table.
- Nested record settings only apply to Excel or ODS (OpenOffice) print templates.
2.3.2. Options
- Run script
- Checking this box determines whether the script should be run before a document is created with the “New from template” item.
- The same script is run as by the button defined on the “Button” tab (the “Server” field). Script execution typically sets the values of script variables used in the print template.
- The “Modify script” link opens the integrated graphical script designer, in which the script itself is defined.
- Alternate row background
- Checking this box specifies whether to use alternating white and gray rows when printing records inside tables.
- The settings in this field only apply to XLSX, XLSM, XLS, or ODS print templates.
- By values in first column
- Only in conjunction with the “Alternate row background” option
- Checking this box determines whether the row color should be dependent on the value of the first column of the printed table – rows with the same first column value will have the same color.
- The settings in this field only apply to XLSX, XLSM, XLS, or ODS print templates.
- Lock the document
- Checking this box determines whether the printed document is protected against writing. The sheets of an Excel file are locked with a password that can be changed using the external function “NETGenium.ExcelPassword”; Word documents are locked without a password. A detailed description of external functions is provided in the separate guide External functions.
- In Word documents (DOCX, DOCM, DOC, ODT), only edits with tracked changes are allowed after locking.
- The settings in this field apply only to XLS, XLSX, XLSM, ODS, DOC, DOCX, DOCM, or ODT print templates. With HTM and HTML print templates, checking this box saves the document in PDF format; with a PDF print template, it has no effect.
2.4. “Button” tab
2.4.1. Title
- The title specifies the name of the button, which optionally appears to the right of the control itself in the edit form.
- An empty name means that the button will not be displayed.
2.4.2. Width
- Button width in pixels.
- A filled-in width of “0” or “1” hides the button; an empty width leaves the decision to the browser, which derives it from the label.
2.4.3. Client
- The “Client” field specifies a list of javascript commands that will be executed when the button is pressed. The drop-down list offers the following frequently used javascript functions:
- Are you sure you want to ... ? – return jsConfirm(this, 'Are you sure you want to ... ?');
- AJAX... – return bt_Eval(this, 'ngef.aspx?test', 'evalFunction');
- control_SetValue – control_SetValue(#ng_#, 0);
2.4.4. Server
- If the “Client” field is empty, the server-side script is run after the button is pressed. If the “Client” field contains code, the script is run only if the code returns a true value with the “return” command – code without the “return” command does not run the script. The “Modify script” link is used to open the integrated graphic script designer, in which the script is defined, resp. server part of the button.
- Execution of javascript commands can be interrupted by the command “return false;”, which prevents the subsequent execution of the script on the server side.
- The control has a single script, which is shared by the button and by creating a document with the “New from template” item (the “Run script” option on the “Print to template” tab). The “Modify script” links on both tabs therefore open the same script, and a change to it applies in both cases.
2.5. “Help” tab
2.5.1. Help
- Help text is displayed to the right of the control in the edit form.
- The help texts of all controls start at the same vertical line across the entire edit form.
- Text – the help text is defined by a manually entered text string in a multi-line text field below the radio button
- From query – the help text is defined by the result of a database query that is evaluated when the edit form is opened
- A detailed description of the help text is provided in the separate guide Layout settings.
2.5.2. Notes
- Notes are used to enter any text intended for the application administrator.
- Notes can contain the MAXWIDTH(n), MAXHEIGHT(n) and QUALITY(n) functions, which shrink an image uploaded with the “Browse...” button to the specified maximum width and height in pixels, or save it with the specified quality (1–99). This applies to BMP, GIF, JPE, JPEG, JPG and PNG files, which are saved in JPG format after the change.
2.6. “Filter” tab
2.6.1. Options
- Show filter in the view table
- Checking this box determines whether the view table should be allowed to filter records by the values present in the database in the column associated with this control. The filter drop-down list is located in the header of the view table under the name of the control.
- The filter drop-down list does not display the specific values present in the database in the column associated with this control, only the options
- Search – search for records in the database that have the search value stored in the file attachment name, or in the case of file attachment indexing enabled, also in its content.
- Empty – search for records in the database that have the value 0 or the database value “null” stored in the column associated with this control
- Non-empty – search for all other records in the database
2.7. “Rights” tab
2.7.1. Rights
- Rights define a list of user groups and users who have permission to display a control on an edit form and to display the values of that control elsewhere in the application.
- Users who do not have control rights
- they do not see the control or its value in the edit form, and the control is not rendered into the source code of the page in a web browser either,
- they cannot display the column associated with this control in a view table or other visual control intended for viewing data,
- they can create an entry in the edit form in which there is a control to which they do not have rights, the value of these controls is then set to the database value “null”,
- by default, they cannot delete a record in an edit form containing a control to which they do not have rights; enabling “Always allow deleting to the owner or co-owner of the record” in the “ActionButtons” control is an exception.
- An application administrator can cause a logical error when a javascript function refers to a control that may not be accessible from a rights perspective for some users. The variable “ng_” is then replaced by the value stored in the database in this control instead of a reference to the object of the control itself. In most cases, this error stops loading the edit form, it disables itself, and the user is shown a message that he should contact the application administrator. This type of error can be partially eliminated using the report “Controls (JavaScript + insufficient rights)”. The substituted value is part of the page source code – therefore, the identifier of a control with a sensitive value should not be used in JavaScript or in the “HTML” control.
2.7.2. Show value
- The display of the control value can be limited only to the users who created the database record, or are set as co-owners of all records in the edit form settings.
- The radio button contains the following types of value display:
- To all users – the control, including its value, will be displayed to all users who have the right to the control
- Only to the owner or co-owner of the record – the control, including its value, will be displayed in the edit form only to users who have the right to the control and at the same time may edit the record – a user with administrator rights, a co-owner, and the owner of the record if “Editing rights” is set to “Owner or co-owner of the record”. The control cannot be displayed as a view table column. A detailed description of how the value is displayed in other controls is provided in the separate guide Edit form.
2.7.3. Replace rights to other controls
- The “Replace rights to other controls” function is used to unify the rights within the entire edit form for controls that are related in terms of rights.
- Thanks to the “Show...” link, it is possible to display a list of all controls in the edit form, including setting the rights of these controls. A check box is displayed for each control to select it. When the control is saved, the same rights are then set for the selected controls.
- An alternative for unifying rights within the entire edit form is to display the report available from the “Subordinate object rights” tab in the edit form settings.
2.8. “Administration” tab
- The “Administration” tab is only displayed for existing controls.
2.8.1. Identifier
- The identifier specifies the name of the database column in which the values entered through the control in the edit form are stored in the database.
- The identifier is derived from the name of the control. It starts with the prefix “ng_”, and also contains the alphanumeric characters used in the control name (system controls do not include the prefix “ng_”). When changing the name of the control, the “Correct” button is available, which is used to correct the identifier, and thus to rename the database column in the database. For clarity and to eliminate possible misunderstandings, it is recommended to keep the identifier in accordance with the name of the control element. If external applications also access the database and, for example, read or write data to this column, it is necessary to schedule the change of the identifier until a suitable time.
2.8.2. Full identifier
- The full identifier of the control also contains the identifier of the edit form, and is used in printing templates.
2.8.3. Index
- Checking this box determines whether the column associated with this control should be indexed in the database. In the text field located below the check box, it is also possible to define the names (identifiers) of other columns that are to be in the associated index with this database column – they should be part of the index key.
- For the MSSQL database, it is also possible to define “INCLUDE” columns to be attached to the index. However, they are not part of the index key, but the values of that key. The Firebird database does not allow this functionality.
2.8.4. Search in the view table
- The search determines whether records in the view table should be searched after entering a search term or phrase in the database in the column associated with this control – by file attachment name and, where applicable, also by file content.
- Allow – Searching in this column is enabled, and a check box appears in the view table, which can be used to include the table column in the list of searched columns.
- Deny – Searching in this column is disabled, and there is no check box in the view table to include the table column in the list of columns to be searched.
- File content is searched only if the “Windows Search” full-text catalog, or “Indexing Service” with a filled-in catalog name, is selected in NET Genium settings, and only in files with the .htm, .html, .eml, .xml, .txt, .doc, .docx, .docm, .xls, .xlsx, .xlsm or .pdf extension. A detailed description of the full-text catalog is provided in the separate guide NET Genium settings.
2.8.5. Other
- Current value in the database
- The text box displays the current value of the currently open record in the edit form in the given control, with the possibility to change this value.
- Change type to
- The drop-down list offers the types of controls to which conversion of the control is supported, including automatic conversion of the data present in the database table.
2.8.6. Statistics
- Statistics display aggregated information about control usage across the entire application.
- Using the “Statistics” button, a detailed report of all places where the control is used or referenced is displayed, including the possibility to open the settings of such a place or control.
- Before each change of control type or data type, or before each deletion of a control from the edit form, it is recommended to thoroughly go through the control statistics, and eliminate any misunderstandings.
- Before each deletion of the control from the edit form, the evaluation of the statistics starts automatically. If the control is used or referenced somewhere in the application, it is necessary to confirm the deletion of the control again.
2.9. Picker
- The magnifier icon located in the lower-left corner of the dialog is used to configure the picker for this control.
- A detailed description of the picker is provided in the separate guide Picker.
2.10. “Save”, “Save and continue editing”, “Copy”, “Delete”, and “Close” buttons
- “Save” button – Saves changes to the control settings.
- “Save and continue editing” button – Saves changes to the control settings and keeps the settings dialog open for further modifications.
- “Copy” button – Creates a new copy of the current control with identical settings, but with a newly generated unique identifier.
- “Delete” button – Permanently deletes the control.
- “Close” button – Closes the control settings dialog without saving changes.
3. Behavior of attachments
- The download link of an attachment is bound to the logged-in user and the user's session and is valid for 24 hours. It cannot be passed on to another user.
- Attachments in HTML (.htm, .html) and SVG format open directly in the browser in isolated mode (sandbox): scripts do not run in them and the content has no access to NET Genium. Images are displayed, other attachments are downloaded.
- Only an attachment that the server created or made available in the current session can be saved into the File control – uploaded by the button, pasted from the clipboard, taken over by a picker or assigned by a script. The control does not take over the ID of an existing attachment from elsewhere.
- The “Remove” button only clears the value of the control. The attachment file remains on the disk in the “Files” directory together with its record in the “sfiles” table, just as after deleting the record, the control, the edit form or the change history. This makes it possible to restore a deleted record from the history including its attachment.
- Attachments that are no longer referenced by any record or change history are cleaned up by the “SqlBackup.exe” program with the “/unusedfiles” parameter. It creates the “UnusedFiles.log” file with a proposal for review, and the attachments are deleted only by the “SqlBackup.exe /run UnusedFiles.log” command. A detailed description is provided in the separate guide Utilities.
4. Examples
4.1. Javascript functions
- var s = control_GetValue(#ng_#);
- var filename = #ng_#.getAttribute('title');
- var size = jsN(#ng_#.getAttribute('size'));
- control_Disable(#ng_#); // General javascript function for all database controls
- file_Disable(#ng_#);
- control_Enable(#ng_#); // General javascript function for all database controls
- file_Enable(#ng_#);
- picker_Open(#ng_#);
4.2. Server functions
- SCHEDULEDEFAULTVALUE(ng_,#ng_#)
- ATTACHMENT2PDF(#ng_file#)
- ATTACHMENT2PDF(#rootpath#Temp\file.doc)
- ATTACHMENT2PDF(#rootpath#Temp\file.xls)
- ATTACHMENTCONTENT(#ng_file#)
- ATTACHMENTGALLERY(1;2;3, 120, 120)
- ATTACHMENTGALLERY(1;2;3, 120, 120, 5)
- ATTACHMENTNAME(#ng_file#)
- ATTACHMENTURL(#ng_file#)
- COPYATTACHMENT(#ng_file#)
- COPYATTACHMENT(#ng_file#, #rootpath#Temp)
- CREATEATTACHMENT(data:image/png;base64,...)