As you develop and deploy new web or mobile apps for your Valence users on IBM i, inevitably you will run into situations where you’re tempted to hard-code global values into your program to control the behavior of your app. For instance, perhaps you have a situation where you want to default a date field value out by 10 days, so you place code in your program to take the current date and add 10, knowing that someday some user will inevitably be asking you to change the default to 14 or 7… Hard-coding values may save you time during development, but as a seasoned developer you know that requiring someone to make a program change in the future to adjust hard-coded values created today may come back to bite you.
It’d be much easier to simply adjust a control setting — provided, of course, that the process of finding and changing the control setting value is relatively straightforward. Fortunately the Valence Framework can help you with this! If you open the Portal Admin app and click on the “Settings” entity in the left column, you may have noticed in the “Portal Administration” section there is a setting labeled, “Show custom settings” (which is generally checked by default). When this box is checked then a section entitled “Custom Settings” will be found at the bottom of the list. Having custom settings here makes it easy to tweak the behavior of your apps that use them, as you can pull them in to your program using the vvUtility_getValenceSetting procedure.
Custom settings are added to this list by simply inserting records into the VVSETTINGS file in your Valence library. You can use any file editor, such as the Nitro File Editor app, to do this. The key is to ensure you comply with the following rules for each field:
- VVNAME – The name of the custom field you want to set. By convention it should be upper case, with underscores to separate words (i.e., DEFAULT_DAYS_OUT). It can be up to 30 characters long.
- VVSSORT – The sort sequence for the custom setting. This controls where the field shows in the list and should be a number that is 10.00 or greater (as all Valence core settings are under 10.00).
- VVSGROUP – This is the name of the group to “cluster” the settings in. Generally speaking this should always be set to “custom”, which corresponds to a pre-defined literal of “Custom Settings”. You can add additional groups (i.e., custom1, custom2, etc) but be sure to read the information below about adding your own custom literals to the Portal.
- VVFLDSET – (optional) Field set for sub-grouping your custom settings. If you place text here then it will show up as the title of a field set in the Settings list for all corresponding records. For example, you could have several settings records in a field set entitled “Order Entry” followed by a number of records in a “Purchasing” section, and so on.
- VVVALTYPE – The validation method for the field. You can use this to control or validate the data users enter for this setting. See below for valid values. You can also create your own custom validation types, though you’ll need to modify the back-end RPG program (VVADM_SETS) to handle them.
- VVXTYPE – The xtype to use on the front-end. This tells the app whether to show a text field, a number field, a check box, etc. See below for list of valid values.
- VVMAND – Mandatory flag. Set to “1” if the setting must be entered; “0” means the setting can be left blank.
- VVMAXSIZE – (optional) For non-numeric fields, this is the maximum number of characters allowed.
- VVMAXVAL – (optional) For numeric fields, this is the maximum value allowed.
- VVVALUE – this is the current value of the field. You can leave this blank as you’ll be using the Portal Admin app to set it.
- VVDFTVAL – this is a field for reference purposes. It contains the original value of the field as it was set when Valence was first installed at your site. You can leave this blank.
Once you’ve added your new VVSETTINGS records, you’ll be able to see them in the “Custom Settings” section and quickly make changes to the values as needed. These custom settings records will not be erased or overwritten by future updates or upgrades to the framework, so you can rest assured that once you add them they won’t disappear on you. In your RPG programs, you can obtain the values of your custom settings using the vvUtility_getValenceSetting procedure. The value is returned as a graphic (UCS2) field, so you may want to wrap it in %char() for full compatibility with character fields. If your field is numeric, you should further wrap it in %dec() or %int(). For example, your RPG code to retrieve a “default days out” control setting could look something like this: daysOut = %int(%char(vvUtility_getValenceSetting('DEFAULT_DAYS_OUT'))); For custom settings that impact what displays on the front-end app, you would typically retrieve these values in your RPG program and pass them back to the Ext JS or Sencha Touch front-end as a response to an initial Ajax call when the app is first launched (i.e., with an action of “getSettings” or something similar). Most commonly used VVVALTYPE Settings for custom records:
- *NUMBER – value specified will be numeric (typically used in conjunction with a VVXTYPE value of “numberfield”)
- *TEXT – value is basic character text
- *BOOLEAN – value specified will be 1 or 0 (typically used in conjunction with a VVXTYPE value of “checkbox”)
- *PATH – value specified must correspond to a valid IFS path
- *PATH-RELATIVE – must correspond to a valid IFS path inside the valence directory (i.e., /valence-4.0/)
- *LIB – must be a valid IBM i library
- *PGM – must be a valid IBM i program object, in a library defined in the current Valence environment
- *IBMIUSER – must be a valid IBM i user ID
VVXTYPE Settings:
- numberfield – value will be displayed and edited a number
- textfield – character field
- checkbox – checkbox (boolean) field
- email – email address
Custom literals in VVNAME and VVSGROUP fields: For the VVSGROUP field, Valence comes pre-installed with a literal value for “custom” (corresponding to Valence.lang.lit.custom) which will display in the Portal Admin app as “Custom Settings”. If you want to add additional custom setting sections, you will want to add the names to the Valence.lang.lit object so they display. Likewise your new settings names can be set up to correspond to label values (Valence.lang.label) that would show in the Portal Admin app as more descriptive name — i.e., “Default days out for order inquiry apps” instead of “DEFAULT_DAYS_OUT”.