In order to add a TXT changes task to a packaging project, users go to the TXT changes view of the Visual Designer mode.
With a click on the Create new... button, wizard for task creation is invoked.
Work your way through the steps of the wizard to define all required properties for the new task.
At any time, using the Next or Back buttons, which are displayed at the bottom of the wizard dialog, allows to navigate within the already processed steps.
To exit the wizard without creating a new object, use the Cancel button, also located at the bottom of the wizard dialog.
Step 1: Description
The name of the task has to be given as an unique alphanumerical string. Special characters (e. g. blanks, equals (=), exclamation mark (!), plus (+), minus (-), or asterisk (*)) are not allowed.
Since the description is the property that is displayed in the task list of the TXT changes view, it is recommended to use a self-explanatory value. By doing so it becomes easier to quickly access a specific task from a large list.
As long as the input field is marked by red background, the value is not valid yet. Please use the mouse cursor to hover over the input field and reveal the message that indicates what needs to be done to achieve a valid task description.
Step 2: Component
Each change task has to be related to a specific component. To select the component from the existing set of the current packaging project, users expand the selector control and click on the desired component.
If a new component has to be created, users click on the [...] button on the right hand side of the component selector control. The select component dialog is displayed. Please refer to the resembling common dialogs topic for further details.
Step 3: Text Changes Type
Two basic operational TXT change types are available:
Find & Replace
Searches for a specific string or a string matching the specified pattern and replaces the original content.
Find & Append
Searches for a specific string or a string matching the specified pattern and appends additional text to it.
This option is mostly used when a regular expression is evaluated during the search algorithm, and the varying original text phrases that actually match the search pattern should not be changed to one common new phrase by the txt change operation.
To select one of the two options, click on the resembling tile. The currently active option is marked with a check mark icon in the upper right corner of the type tile.
Step 4: Find and Replace
According to the selected change type, the entered values in this view are interpreted to execute the text change:
Find what
The definition of the actual string or pattern to search for.
|
Note: If the entered value has to be evaluated as a regular expression pattern, the search option Regular expression has to be activated. |
Replace / Append with
The new content that will be used as replacement or accretion. The value given here must be the actual text, regular expressions are not evaluated.
|
Note: As indicated by the square brackets ("[]") at the right hand side of the input fields for search and replace / append, it is possible to make use of syntax suggestions to define the search string. Simply enter an opening square bracket ("[") to display the list of available suggestions for property and path values. Select the desired value from the list to add it to the already entered search string. The actual value at run time will be used for the task execution. |
Match case
If this checkbox is activated, the case of the letters used within the entered search string has to match the case of the matches in the searched file contents. This option is only valid for exact searches, not for regular expression matchings.
Match whole word only
Activating this checkbox disables the RayPack standard behavior to search for any occurrence of the search string. If the checkbox is activated, the string will only be matched if it is found as a whole word, meaning that there has to be a blank before the string.
This option must be activated if the search term is assigned for regular expression matching. Even if the search term is a regular expression, it will not be evaluated by the resolver engine as long as the search option "Regular expression" is inactive.
|
WARNING Regular expressions are very powerful tools, which can be used to execute highly complex manipulation requirements. However, any potent tool can cause serious harm if used incorrectly. Therefore it is highly recommended to apply regular expressions on clearly defined target file groups. Responsible packaging engineers should make sure that vital resources of target machines operating systems are not damaged by their packages. |
Replace once
Text replacements are usually executed on all matching strings within the given path and file type specification (see next step: Files and Folders). If this checkbox is activated, only the first occurrence is replaced.
Step 5: Files and Folders
In this step the files that have to be considered by the change task have to be defined:
Target folder
The folder on the target machine that will be searched for matching files.
As indicated by the square brackets ("[]") at the right hand side of the input field, it is possible (and recommended) to make use of syntax suggestions to define the target folder. Simply enter an opening square bracket ("[") to display the list of available suggestions for property and path values. Select the desired value from the list to add it to the already entered text in the input field. The actual property or path value at run time will be used for the task execution.
|
Be aware: The definition of the target folder can cover whole system drives, e. g. the C: drive of the target machine. If the Include subfolders option is activated, the change task will search every directory on the defined drive for files with matching content. Depending on the system performance, and the amount of files on that drive such global target definitions may cause severe issues during the software package installation and / or uninstallation sequences. Therefore, it is highly recommended to reduce the target folder definition to the smallest required area. |
The target folder property may not be left empty.
Include subfolders
The standard behavior for change tasks is to check all files within the defined target folder for the search term - files that are stored within subfolders are not considered. Activating this checkbox sets up a search task that considers all files below the target folder, no matter how deep they are nested.
Again, please be aware that including subfolders may considerably reduce the target package's sequence execution performance.
Include files
The files within the defined target folder that have to be considered by the change task. The file list is a comma separated list of either actual file names (e. g. "file1.txt,file2.htm"), or of file extensions (e. g. "*.txt,*.htm"). Combinations of both value types are valid as well.
The wild card operator asterisk ("*") can be used to match any custom file group beyond file type extensions, e. g. use definitions like AnyFile*.ini to match a set of files with an index counter within the file name.
The include files property may not be left empty.
Exclude files
Every rule is only as good as its best exception. Therefore it is possible to reduce the list of included files, e. g. to protect system or license files from undesired manipulation. All files given in this comma separated list will not be affected by the change task, even if target folder, include files restriction and search term definition would match.
Whilst the include files list is usually a combination of file types defined by their file name extension string (e. g. "*.xml"), the exclude files list is usually a list of specific files. Again, the wild card operator asterisk ("*") may be applied to widen the definition.
Step 6: Run type
Text manipulations may be executed during package installation and / or uninstallation run time. Activate the desired run type by clicking on the resembling option tile. The currently active option is marked by a check mark in the center of the tile. The default run type is INSTALL, which will execute the change task only during package installation sequences.
Step 7: Summary
Use the summary page to check the correctness of the task properties that were defined during the previous wizard steps.
•If all properties are set as required, click Process to finally create the object
•If changes are due, click Back until the wizard step with the incorrect property definition(s) is displayed and make modifications as required.
Please note that changes in an early step may lead to different defaults or options in any later step. Therefore, please verify that all steps contain the desired settings whilst NEXTing to the summary page again.
Step 8: Finished
Once the new TXT changes task has been created, the wizard can be closed by using the Finish button at its lower right corner. The TXT changes view is updated, and the list of existing tasks contains the newly created object at the lowest position of the run order.