System Design section.
To view the master list of available report definitions, select the "Reports" option. The following screen will appear:
Note
The stock xTuple ERP reports are written using Arial and Helvetica fonts. We chose these fonts to try and prevent unpredictable behavior caused when xTuple reports are printed on different operating systems. Of course, you are free to use other fonts when writing report definitions for your own environment.
The report definitions master list displays information on all stored reports, including report name, report grade, and report description.
Tip
Stock reports are given a grade of zero ("0"). These stock reports may be updated during database upgrades. You should assign a grade greater than zero to any custom reports to distinguish them from stock reports. Doing so will ensure your custom reports are not overwritten during upgrades. A report definition may have multiple grades. By default, the application uses the report definition with the highest grade.
To the far right of the screen, the following buttons are available:
- CLOSE
Closes the screen, returning you to the application desktop.
Runs the report associated with this screen.
- NEW
Opens screen for adding a new report definition to the reports master list.
- EDIT
Enables you to edit highlighted report definitions. The edit screen is the same as that for creating a new report definition—except that when editing, the fields will contain report information.
- DELETE
Highlight a report and then select this button to remove the report from the master list.
To create a new report definition, select the NEW button. The report writer will be opened, as shown in the following screen:
The report writer can be used to create new report definitions or edit those already found on the report master list. Once created, new reports can be added to the master list, making them available for use in the application. To edit an existing report, simply load the report into the report writer from the Database you are currently connected to. Then edit the report and save it back to the Database once editing is complete.
Custom Screens are screens you can design, using QtDesigner, and then run within your xTuple ERP application. Essentially, a screen is a UI form which specifies widgets and layout information. Just like scripts, screens are stored in your xTuple database using the functionality described in this section. To take advantage of this functionality, you should have a basic understanding of how to program using ECMAScript and create UI screens using QtDesigner.
Tip
You can read more about creating custom screens and scripting in the Development Zone of our wiki at www.xtuple.org.
When creating a new screen, the first thing to do is give it a name. This name is then used to find matching scripts. Screens can be enabled or disabled—as well as have an order. You may have several screens with the same name; however, only the lowest enabled screen is used. In addition, you must export or import the UI file (i.e., you cannot edit the UI file directly on the database). And, creating a screen does not automatically make it available to users. You must first create a custom command to make sure the screen is added to the menu structure, as described here: Section 14.2.1.1, “Custom Command”.
Note
Because screens are very limited in what they can be made to do without code or scripting, it will almost always be necessary to write one or more scripts for a screen.
To view the master list of available custom screens, select the "Screens" option. The following screen will appear:
The screens master list displays information on all custom screens, including screen name, description, order, and enabled status. If the screen is part of a larger package, the name of the parent package will be displayed—with all the child screens appearing in a nested list below it.
To the far right of the screen, the following buttons are available:
- CLOSE
Closes the window, returning you to the application desktop.
- NEW
Opens window for adding a new custom screen to the screens master list.
- EDIT
Enables you to edit highlighted custom screens. The edit window is the same as that for creating a new custom screen—except that when editing, the fields will contain screen information. If this screen is part of an extension package, the screen will be opened in view-only mode unless the package is set to allow modifications.
- DELETE
Highlight a custom screen and then select this button to remove the custom screen from the master list.
- TEST
Highlight a custom screen and then select this button to launch the screen in the xTuple ERP application. If successful, the highlighted screen will appear within the xTuple framework (e.g., on the desktop). If the screen does not appear, then check your settings—and be sure you have imported your source UI file into the database.
To create a new custom screen, select the NEW button. The following window will appear:
When creating a new custom screen, you are presented with the following options:
- Name
Enter a name to describe the screen.
- Notes
Enter some brief notes to describe the screen.
- Grade
Specify the ranking of the screen. As with report definitions, the screen having the highest grade is the one that will be used.
Note
Screens created with the same name as a core screen will be ignored. Core C++ based screens can not be over-ridden with their own UI. To over-ride a core screen, make a new screen with a new name, remove the core screen menu action from the menu, and replace with a new menu action that launches your new screen.
- Package
Displays the name of the package the screen belongs to, if any.
- Enabled
Select to enable the screen. If not selected, the screen will be disabled.
- Scripts
Display lists any scripts associated with the screen. Scripts may be added/removed, enabled/disabled, and ordered according to need.
To the far right of the screen, the following buttons are available:
- CANCEL
Closes the screen without saving any changes.
- SAVE
Saves the screen definition, including any UI file which you may have imported. The screen definition and the UI file are both saved to the database.
- EDIT
Highlight a screen definition and then select this button to launch an embedded version of the Qt Designer tool. The embedded version of Qt Designer has been added to xTuple ERP to make screen editing more convenient. It is not a requirement that the embedded version of Qt Designer be used for building custom xTuple ERP screens. You may also use a standalone version of Qt Designer for this purpose.
- IMPORT
Select to import the UI file you want to use as the basis for your custom screen. UI files should be created using Qt Designer. When they are imported using this option, they are stored in the database and associated with the specified screen definition. If you ever want or need to edit the UI file and do not have a copy stored locally, you can simply export the UI file to your file system—and then re-import it when you are done editing. Whenever you import a UI file, it automatically replaces whatever UI file was in place before it.
Warning
Every time you import a UI file, the new UI file replaces whatever UI file was imported previously—regardless of the name of the file(s).
- EXPORT
Select to export the UI file associated with the screen. You would use this option if you need or want to edit the UI file and do not have a copy stored locally on your system. Once exported, the UI can be edited using Qt Designer—and then re-imported into the database using the import option. Whenever you import a UI file, it automatically replaces whatever UI file was in place before it.
- NEW
Opens screen for creating a new script. Read more about creating scripts in Section 14.3, “Scripts”.
- EDIT
Enables you to edit highlighted scripts. The edit screen is the same as that for creating a new script—except that when editing, the fields will contain script. Double-clicking on a script will also bring you to the editing screen.
- DELETE
Highlight a script and then select this button to remove the script from the list.
To specify commands for the screen, select the "Commands" tab. The following screen will appear:
When specifying commands, you are presented with the following options:
- Commands
Displays the list of commands associated with the screen.
To the far right of the screen, the following buttons are available:
- NEW
Opens screen for creating a new command. The creation of custom commands is described in Section 14.2.1.1, “Custom Command”.
- EDIT
Enables you to edit highlighted commands. The edit screen is the same as that for creating a new command—except that when editing, the fields will contain command information. Double-clicking on a command will also bring you to the editing screen.
- DELETE
Highlight a command and then select this button to remove the command from the list.
Custom Commands enable you to insert ad hoc functionality into the xTuple ERP menu system. Examples of ad hoc features are custom report definitions, custom .ui screens, and more. All Custom Commands are launched from a special "Custom" menu, which gets created at the bottom of the menu tree for modules you are adding Custom Commands to. To create a new Custom Command, select the NEW button. The following screen will appear:
When creating a new Custom Command, you are presented with the following options:
- Module
Select the name of the module where you want the custom menu option to appear. You may create Custom Commands for any of the modules within the system. By default, a menu option named "Custom" will be added to the bottom of a module's menu tree when a Custom Command is created for that module.
- Menu Label
Enter a name to identify the Custom Command as it will appear on the menu tree for the specified module. Each menu label should be used to describe a separate Custom Command. There is no limit to the number of Custom Commands which may be added to a module.
- Priv. Name
Enter a name to describe the privilege associated with the Custom Command. By associating a privilege with a Custom Command, you gain the ability to grant or withhold access to the menu option on a user-by-user basis. Users who have been granted the privilege will have access to the Custom Command; all others will not.
- Action Name
Enter a programmatic-style name for the Custom Command, so the system will be able to locate and process the information easily. Having an action name also makes it possible to create a Hot Key for the Custom Command. Because of the Hot Key feature, you should consider using an action name which conforms to the already-existing naming convention for Hot Key actions. For more information see Section 5.1, “Hot Key”.
- Executable
The information entered in this field will vary depending on the use case. If the Custom Command is designed to launch a custom screen, then the following text should be entered:
!customuiformIf the Custom Command should open a file or web page, then the following text should be entered:
!openurlIf, on the other hand, the Custom Command will launch an executable program (e.g., RPTRender), then you should enter the path to the location where the executable program is located. When users select the associated Custom Command menu option, the executable program will be launched. For example, if you want to run a custom report, specify the location for the standalone report renderer (RPTrender). The following examples illustrate how (on Windows) you can map to either local or network drives:
Local Drive:
C:\\Program Files\\xTuple\\RPTrender.exeNetwork URL:
\\\\drive_name\\dir_name\\xTuple\\RPTrender.exe
Note
You may encounter cross-platform conflicts when placing executables on network drives. To reduce these conflicts, it may be necessary to create separate custom menus to support executables designed for different operating systems.
Tip
Macintosh users should enter an executable path which points all the way to the executable file located within a package's Contents directory. For example, to launch the report renderer, enter the following path:
../rptrender.app/Contents/MacOS/rptrender
Under Mac, the RPTrender application will not open if the path does not continue past the rptrender.app file.
- Description
Enter text to describe the Custom Command.
If you want the system to pass parameters or other arguments to the specified executable when it is launched, select the "Arguments" tab. The following screen will appear:
The arguments display lists all arguments defined for the specified executable. When trying top open a web page or file (i.e., the Executable is set to !openurl), create a new argument and enter the URL to open (see Qt's documentation for details).
The following table shows the range of possible arguments if the executable is a custom screen (i.e., ui form):
Table 9.2. Arguments Used for Custom Screens
Syntax | Description |
|---|---|
uiform= | Use this argument followed by the name of the ui form (i.e., the screen) which the Custom Command will be executing. The screen name is the name entered on the main custom screen window. Example:
|
uiformtype= | Use this argument to specify which type of screen it is. There are two possible values: Example:
|
The next table shows the range of possible arguments you can pass to the report renderer (RPTRender) if you are running custom reports:
Table 9.3. Arguments Used for Custom Reports
Syntax | Description |
|---|---|
-databaseURL | Used to specify the location of the database server. This is followed by the server address, database name, and port number. If running a custom report, the program will automatically connect to the database specified when the report renderer (RPTrender) is launched Example:
|
-username | Enter the username RPTrender should use to connect to the specified database. Example:
|
-passwd | Enter the password for the specified user. Example:
|
-param | Enter any parameters you want the system to pass to the report renderer. These pre-defined parameters will be used when RPTrender runs the specified report definition. Example:
|
This argument tells RPTrender to print the specified report definition using the indicated parameters—if any. Example:
| |
-close | Use this argument to close the RPTrender program when its work is done. Example:
|
-noAuth | This argument tell RPTrender that not all login fields, if any, are required and it will attempt to login to the specified database without presenting the login screen. Example:
|
-loadfromdb= | This argument specifies the name a report definition to load from the database that is being connected to. Example:
|
-printerName= | This argument specified the printer to print to by it's name. Names vary from system to system and you must determine the correct name for this option. Example:
|
This argument specifies that you want the output to be in .pdf format. Example:
| |
-outpdf= | This argument specifies the name you want pdf output to be sent to. Example:
|
To the far right of the screen, the following buttons are available:
- CLOSE
Closes the screen, returning you to the application desktop.
- NEW
Opens screen for creating a new argument.
- EDIT
Enables you to edit highlighted argument definitions. The edit screen is the same as that for creating a new argument definition—except that when editing, the fields will contain argument information. Double-clicking on an argument definition will also bring you to the editing screen.
- DELETE
Highlight an argument definition and then select this button to remove the argument from the list.
To create a new argument for the system to pass to the specified executable program, select the NEW button. The following screen will appear:
When creating a new argument, you are presented with the following options:
- Order
Specify the order in which the argument should be passed to the specified executable program.
Tip
You can change the position of an argument as it appears on the list by editing the argument and changing its order number.
- Argument
Enter the argument you want the system to pass to the specified executable program.
To the far right of the screen, the following buttons are available:
- CANCEL
Closes the screen, returning you to the application desktop.
- OK
Saves the argument information.
xTuple ERP supports QtScript, a tool for loading UI forms using ECMAScript based language files for creating and modifying application functionality without the need to recompile. To take advantage of this functionality, one should have a basic understanding of how to program using ECMAScript and create UI screens using QtDesigner. To learn more about scripting for xTuple ERP, please see the Scripting Guide.
Tip
You can enable automatic script debugging using the Qt Script debugger by setting a simple option on the "Advanced" tab of the User Preferences screen. If you are trying to develop your own custom scripts and want to use the Qt Script debugger, xTuple recommends starting your script with this command. To learn more about the User Preferences setting, see Section 5, “Preferences”.
To view the master list of available scripts, select the "Scripts" option. The following screen will appear:
The scripts master list displays information on all stored scripts, including script name, description, order, and enabled status. If the script is part of a larger package, the name of the parent package will be displayed—with all the child scripts appearing in a nested list below it.
To the far right of the screen, the following buttons are available:
- CLOSE
Closes the screen, returning you to the application desktop.
- NEW
Opens screen for adding a new script to the scripts master list.
- EDIT
Enables you to edit highlighted scripts. The edit screen is the same as that for creating a new script—except that when editing, the fields will contain script information. If this script is part of an extension package, the script will be opened in view-only mode unless the package is set to allow modifications.
- DELETE
Highlight a script and then select this button to remove the script from the master list.
To create a new script, select the NEW button. The following screen will appear:
When creating a new script, you are presented with the following options:
- Name
Enter a name to identify the script. The name of the script must match the name of the screen the script will be used for. If the script name does not match the screen name, the script will not be used. Because a single screen may require more than one script, you may save multiple scripts having the same name. The order, notes, and content of each script will distinguish one from the other.
- Notes
Enter a brief description of the script.
- Order
Specify the order in which the script should be run. The script having the lowest number (i.e., "0") will be run first, and then following scripts will be run in consecutive order.
- Package
Displays the name of the package the script belongs to, if any.
- Enabled
Select to enable the script. If not selected, the script will be disabled. A disabled script will not be run when the corresponding screen is executed.
- Script
Enter the content of the script using QtScript. You may type the script directly into this window, or you may import a script using the IMPORT SCRIPT button.
- Line
The spin box in the lower left hand corner shows you the current line number—and allows you to jump to specific line numbers within the script.
- Search
Enter a search term in the field and then select the FIND button to locate matches within the script.
To the far right of the screen, the following buttons are available:
- CANCEL
Closes the screen without saving any changes.
- SAVE
Saves the script and adds it to the scripts master list.
- FIND
Select to locate search term matches within the script.
- IMPORT SCRIPT
Select to import a script from your local file system into the database. This option is useful if you prefer to do your scripting using an external script editor. The script you import will be shown in the script window.
Warning
Every time you import a script file, the new script will replace the script which was shown in the script window previously.
- EXPORT SCRIPT
Select to export the script shown in the script window to your local file system. You would use this option if you need or want to edit the script and do not have a copy stored locally on your system. Once exported, the script can be edited using an external editor—and then re-imported into the database using the import option. Whenever you import a script file, it automatically replaces whatever script was in place before it.
If you want to execute external programs from within the menu structure, you can do so using the Custom Commands utility. This utility enables you to create custom menu options, which users may then select to launch specified programs. Custom Commands are well-suited for running custom reports. However, they may be used to execute a wide range of programs, for a variety of purposes. To access the master list of Custom Commands, select the "Custom Commands" option. The following screen will appear:
Note
There is no limit to the number of Custom Commands which may be added to a module. Executable programs may be launched from local or network drives.
The Custom Commands master list displays information on all Custom Commands, including module name and menu label.
To the far right of the list, the following buttons are available:
- CLOSE
Closes the screen, returning you to the application desktop.
- NEW
Opens screen for adding a new Custom Command to the master list of Custom Commands.
- EDIT
Enables you to edit highlighted Custom Command definitions. The edit screen is the same as that for creating a new Custom Command definition—except that when editing, the fields will contain Custom Command information. Double-clicking on a Custom Command definition will also bring you to the editing screen. If this Custom Command is part of an extension package, the Custom Command will be opened in view-only mode unless the package is set to allow modifications.
- DELETE
Highlight a Custom Command definition and then select this button to remove the Custom Command from the master list.
Custom Commands enable you to insert ad hoc functionality into the xTuple ERP menu system. Examples of ad hoc features are custom report definitions, custom .ui screens, and more. All Custom Commands are launched from a special "Custom" menu, which gets created at the bottom of the menu tree for modules you are adding Custom Commands to. To create a new Custom Command, select the NEW button. The following screen will appear:
When creating a new Custom Command, you are presented with the following options:
- Module
Select the name of the module where you want the custom menu option to appear. You may create Custom Commands for any of the modules within the system. By default, a menu option named "Custom" will be added to the bottom of a module's menu tree when a Custom Command is created for that module.
- Menu Label
Enter a name to identify the Custom Command as it will appear on the menu tree for the specified module. Each menu label should be used to describe a separate Custom Command. There is no limit to the number of Custom Commands which may be added to a module.
- Priv. Name
Enter a name to describe the privilege associated with the Custom Command. By associating a privilege with a Custom Command, you gain the ability to grant or withhold access to the menu option on a user-by-user basis. Users who have been granted the privilege will have access to the Custom Command; all others will not.
- Action Name
Enter a programmatic-style name for the Custom Command, so the system will be able to locate and process the information easily. Having an action name also makes it possible to create a Hot Key for the Custom Command. Because of the Hot Key feature, you should consider using an action name which conforms to the already-existing naming convention for Hot Key actions. For more information see Section 5.1, “Hot Key”.
- Executable
The information entered in this field will vary depending on the use case. If the Custom Command is designed to launch a custom screen, then the following text should be entered:
!customuiformIf the Custom Command should open a file or web page, then the following text should be entered:
!openurlIf, on the other hand, the Custom Command will launch an executable program (e.g., RPTRender), then you should enter the path to the location where the executable program is located. When users select the associated Custom Command menu option, the executable program will be launched. For example, if you want to run a custom report, specify the location for the standalone report renderer (RPTrender). The following examples illustrate how (on Windows) you can map to either local or network drives:
Local Drive:
C:\\Program Files\\xTuple\\RPTrender.exeNetwork URL:
\\\\drive_name\\dir_name\\xTuple\\RPTrender.exe
Note
You may encounter cross-platform conflicts when placing executables on network drives. To reduce these conflicts, it may be necessary to create separate custom menus to support executables designed for different operating systems.
Tip
Macintosh users should enter an executable path which points all the way to the executable file located within a package's Contents directory. For example, to launch the report renderer, enter the following path:
../rptrender.app/Contents/MacOS/rptrender
Under Mac, the RPTrender application will not open if the path does not continue past the rptrender.app file.
- Description
Enter text to describe the Custom Command.
If you want the system to pass parameters or other arguments to the specified executable when it is launched, select the "Arguments" tab. The following screen will appear:
The arguments display lists all arguments defined for the specified executable. When trying top open a web page or file (i.e., the Executable is set to !openurl), create a new argument and enter the URL to open (see Qt's documentation for details).
The following table shows the range of possible arguments if the executable is a custom screen (i.e., ui form):
Table 9.4. Arguments Used for Custom Screens
Syntax | Description |
|---|---|
uiform= | Use this argument followed by the name of the ui form (i.e., the screen) which the Custom Command will be executing. The screen name is the name entered on the main custom screen window. Example:
|
uiformtype= | Use this argument to specify which type of screen it is. There are two possible values: Example:
|
The next table shows the range of possible arguments you can pass to the report renderer (RPTRender) if you are running custom reports:
Table 9.5. Arguments Used for Custom Reports
Syntax | Description |
|---|---|
-databaseURL | Used to specify the location of the database server. This is followed by the server address, database name, and port number. If running a custom report, the program will automatically connect to the database specified when the report renderer (RPTrender) is launched Example:
|
-username | Enter the username RPTrender should use to connect to the specified database. Example:
|
-passwd | Enter the password for the specified user. Example:
|
-param | Enter any parameters you want the system to pass to the report renderer. These pre-defined parameters will be used when RPTrender runs the specified report definition. Example:
|
This argument tells RPTrender to print the specified report definition using the indicated parameters—if any. Example:
| |
-close | Use this argument to close the RPTrender program when its work is done. Example:
|
-noAuth | This argument tell RPTrender that not all login fields, if any, are required and it will attempt to login to the specified database without presenting the login screen. Example:
|
-loadfromdb= | This argument specifies the name a report definition to load from the database that is being connected to. Example:
|
-printerName= | This argument specified the printer to print to by it's name. Names vary from system to system and you must determine the correct name for this option. Example:
|
This argument specifies that you want the output to be in .pdf format. Example:
| |
-outpdf= | This argument specifies the name you want pdf output to be sent to. Example:
|
To the far right of the screen, the following buttons are available:
- CLOSE
Closes the screen, returning you to the application desktop.
- NEW
Opens screen for creating a new argument.
- EDIT
Enables you to edit highlighted argument definitions. The edit screen is the same as that for creating a new argument definition—except that when editing, the fields will contain argument information. Double-clicking on an argument definition will also bring you to the editing screen.
- DELETE
Highlight an argument definition and then select this button to remove the argument from the list.
To create a new argument for the system to pass to the specified executable program, select the NEW button. The following screen will appear:
When creating a new argument, you are presented with the following options:
- Order
Specify the order in which the argument should be passed to the specified executable program.
Tip
You can change the position of an argument as it appears on the list by editing the argument and changing its order number.
- Argument
Enter the argument you want the system to pass to the specified executable program.
To the far right of the screen, the following buttons are available:
- CANCEL
Closes the screen, returning you to the application desktop.
- OK
Saves the argument information.
Packages are compressed files which may contain either a) custom software designed to extend the functionality of xTuple ERP without touching the core xTuple ERP source code or b) upgrade bundles designed to migrate xTuple ERP databases from one version to the next. Using Packages, third-party software developers can add features without needing C++ programming skills. And these features can be integrated seamlessly into xTuple ERP independent of the release cycles and source code requirements defined by xTuple. In short, Packages are flexible. And they make it easy for software developers to add new features—or even just simple tweaks—to customize and enhance the xTuple ERP experience. For additional information, please see the CreateUpdaterPackages wiki page.
To view the complete list of Packages loaded into your xTuple ERP system, select the "Packages" option. The following screen will appear:
The "List Packages" screen displays information on all existing Packages.
To the far right of the list, the following buttons are available:
- CLOSE
Closes the screen, returning you to the application desktop.
Runs the report associated with this screen.
- LOAD
Opens the Updater utility to allow loading a new Package. If the application cannot find the Updater then the user is given a dialog to find the Updater. This option will only be available to xTuple ERP administrators.
- VIEW
Highlight a Package and then select this button to reach a read-only view of the "Edit" screen.
- ENABLE
Highlight a Package and then select this button to enable a Package which has been disabled. This option will only be available to xTuple ERP administrators.
- DISABLE
Highlight a Package and then select this button to disable a Package which has been enabled. This option will only be available to xTuple ERP administrators.
- DELETE
Highlight a Package and then select this button to remove the Package from the list.
- Automatically Update
Select to have the Packages master list automatically update whenever there are changes to the information shown on the screen.
Once a Package has been loaded into xTuple ERP, you have the ability to review the Package's contents using the Package screen. You won't be able to edit the Package, because Package details are defined at the Package level. However, being able to view Package details is helpful for general information and debugging purposes. For additional information, please see the CreateUpdaterPackages wiki page.
To view the details of a specific Package, select the VIEW button from the Packages master list. The following screen will appear:
When viewing a Package, you are presented with the following options:
- Name
Displays the name of the Package, as defined in the
package.xmlfile.- Version
Displays the Package version, as defined in the
package.xmlfile.- Description
Displays the Package description, as defined in the
package.xmlfile.- Developer
Displays the name Package developer, as defined in the
package.xmlfile. The name used could be an individual or a company name.- Enabled
Indicates whether the package is enabled or disabled.
- Modifications Allowed
Indicates whether users with sufficient privilege are allowed to modify contents of this package. This is used to switch between development mode and production mode of a package. Only database administrators may change this setting.
- Notes
Displays any notes related to the Package, as defined in the
package.xmlfile.
To the far right of the screen, the following buttons are available:
- CLOSE
Closes the screen, returning you to the Packages master list.
To review the contents included in a Package, select the "Contents" tab at the top of the "Package" screen. The following screen will appear:
The contents screen displays a directory listing of all the components contained in the Package. Packages may include any of the following:
user interface forms
application scripts
images
report definitions
MetaSQL statements
tables
views
stored procedures
application privileges
custom commands
To review a list of any Packages required to load the Package, select the "Requirements" tab at the top of the screen. The following screen will appear:
The "Requirements" list displays information on all packages required to load the Package, including Package name, description, and version.
To review a list of any Packages which depend on the Package, select the "Dependencies" tab at the top of the screen. The following screen will appear:
The "Dependencies" list displays information on all packages dependent on this package including, package name, description, and version.