Collapse AllExpand All

11.3.1. Screen

To create a new custom screen, select the NEW button. The following window will appear:

Create new Screen

When creating a new custom screen, you are presented with the following options:

Note

You can read more about creating scripts in Section 11.4, “Scripts”.

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.

The following buttons are unique to this screen:

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

Select to create a new script using the Script Editor. For more information, please see Section 11.4.1, “Script Editor”.

To specify commands for the screen, select the Commands tab. The following screen will appear:

New Screen Commands

When specifying commands, you are presented with the following options:

Note

The creation of custom commands is described in Section 11.3.1.1, “Custom Command”.

Commands

Displays the list of commands associated with the screen.

11.3.1.1. Custom Command

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 option, 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:

Enter new Custom Command

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.

Note

You must restart the application to see any new Custom menu options. Some changes, like newly-added arguments, are effective immediately for existing custom commands.

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. Keep in mind, this is an optional setting. If the privilege name is left empty, then all users will have access to the Custom Command.

Action Name

Enter a programmatic-style name for the custom command, so the system will be able to locate and process the information easily. This is an optional setting but it is recommended. 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—that is, whether you are launching a custom screen, custom report, other executable program, etc. If 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 menu option, the executable program will be launched.

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:

Arguments

The arguments display lists all arguments defined for the specified executable. When trying to 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). If there are multiple arguments, each will be opened.

11.3.1.1.1. Custom Command Arguments

To create a new argument for the system to pass to the specified executable program, select the NEW button. The following screen will appear:

Custom Command Argument

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. If there are multiple arguments with the same number, then their order is undefined.

Argument

Enter the argument you want the system to pass to the specified executable program.

11.3.1.1.2. Custom Report Details

If the custom command is designed to launch a custom report, specify the location for the standalone report renderer (RPTrender) in the Executable field. The following examples illustrate how (on Windows) you can map to either local or network drives:

Local Drive: C:\Program Files\xTuple\RPTrender.exe

Network 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.

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.1. 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:

-databaseURL=psql://server.manufacturing.com/demo:5432

-username

Enter the username RPTrender should use to connect to the specified database.

Example:

-username=jsmith

-passwd

Enter the password for the specified user.

Example:

-passwd=abc123

-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:

-param=user_active:bool

-print

This argument tells RPTrender to print the specified report definition using the indicated parameters—if any.

Example:

-print

-close

Use this argument to close the RPTrender program when its work is done.

Example:

-close

-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:

-noAuth

-loadfromdb=

This argument specifies the name a report definition to load from the database that is being connected to.

Example:

-loadfromdb=SomeReportName

-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:

-printerName=default

-pdf

This argument specifies that you want the output to be in .pdf format.

Example:

-pdf

-outpdf=

This argument specifies the name you want .pdf output to be sent to.

Example:

-outpdf=myreport.pdf


11.3.1.1.3. Custom Screen Details

If the custom command is designed to launch a custom screen, then the following text should be entered in the Executable field:

!customuiform

It should be noted, however, that launching custom screens in this matter is a deprecated approach. This same functionality can be addressed more elegantly using xTuple's scripting tool set.

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=

This is a required argument. Use the 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:

uiform=Calculator

uiformtype=

Use this argument to specify which type of screen it is. There are two possible values: dialog and window.

Example:

uiformtype=dialog

This is an optional argument. The default value is window.


11.3.1.1.4. OpenURL Details

If the custom command should open a file or web page, then the following text should be entered in the Executable field:

!openurl

This command is good for opening either URLs or files in a cross-platform manner.