Preferences

This section covers the different types of preferences in StudioWorks, how to get and set them, where they are saved, and how to add your own preferences.

StudioWorks classifies three types of preferences:

1. Application Preferences These are preference settings and values which are specific to the application that you write. Application preferences are shared by all the runtime users of the application at each site. The cached lists and string tables are application preferences.
2. Local Preferences These are preference settings which are specific to each user of the application. The size and location of each window when it was last closed and the last selected value in a lookup droplist are examples of local preferences.
3. Module Preferences These are preference settings which are specific to a particular module of the application. The default currency is an example of an accounting module preference. The security default timeout and default signoff are examples of system administration module preferences.

App Preferences

The oAppPrefs object class is the interface for getting, setting, and saving app prefs. The main library startup task variable, app_prefs, instantiates the oAppPrefs object class, located in the main library.

Using the Interface Manager you can view all the property methods of the oAppPrefs object. Each property method has a getter and setter method.

When you open your application StudioWorks loads the application preferences from one of two locations:

1. app_prefs.df1 data file location in the APP/libraries/modules folder.
2. AppPrefs table class in the main database. See Shared Application Preferences for more information.

The prefs are loaded into a row variable of the oAppPref object. The row variable is defined using the sAppPrefs_listdef schema classes located in swBase4 and in the main library.

To add your own application preference:

1. Add a column to the sAppPrefs_listdef schema class located in your main library. e.g. TechSupportEmail
2. Close and reopen the main library startup task.

When the oAppPrefs object is initialized it automatically adds getter and setter methods for the new column which you added to the sAppPrefs_listdef schema class in the main library.

The following sample code shows you how to set or get any app pref value.

; Set an app preference.
Do app_prefs.$:developercompanywebsite.$assign('www.vencor.ca')

; Get an app preference.
Do app_prefs.$:developercompanywebsite Returns URL

; Save all app preferences.
Do app_prefs.$savePrefs() Returns FlagOK
If not(FlagOK)
   Do errhndlr.$promptonceLastError()
End If
Quit method FlagOK

The app prefs are saved each time you use the Programmer Menu to do any rebuild, reload, or runtimize operations.

Shared Application Preferences

1. If your application is not set to using tablesownerlogon follow the instructions found under the topic Tables Owner Logon to set this up.
2. Open the APP/startupitems/startupsettings.txt file with a word processor.
3. Find or add a constants group to the file and a SharedAppPrefs property as follows:
   
   

   constants {
       sharedappprefs = TRUE ;
   }

   
   
   
   

   Be sure to remember the ; delimiter at the end of the line!

4. Close and reopen the application with your developer version of Omnis Studio.
5. Programmer Menu > Build Runtime Lists
   
   This completely rebuilds all the lists for use by the runtime users. You will be asked if this is a rebuild for a runtime release.
• If you answer yes, the cached lists will be copied to app_prefs and then saved to the main database.
• If you answer no, the cached list are copied to app_prefs, but they are not saved to the main database. Instead of saving the app_prefs to the database they are copied to a special column of the local_prefs. This is done to prevent messing up the shared app prefs if you are developing the application on the same database as the runtime users.
  
  
  The first time you rebuild the runtime lists StudioWorks automatically creates the AppPrefs server table in the main database for you.

Local Preferences

The oLocalPrefs object class is the interface for getting, setting, and saving local prefs. The main library startup task variable, local_prefs, instantiates the oLocalPrefs object class, located in the main library.

Using the Interface Manager you can view all the property methods of the oLocalPrefs object. Each property method has a getter and setter method.

When you open your application StudioWorks loads the application preferences from the local_prefs.df1 data file located either in the preferences folder used by the StudioWorks app. The preferences folder is normally in the OMNIS folder, but it could be in the APP folder depending on your startup settings.

Keeping the preferences in the OMNIS folder is recommended so that the user's local preferences will persist even if they replace their entire APP folder.

The prefs are loaded into a row variable of the oLocalPref object. The row variable is defined using the sLocalPrefs_listdef schema classes located in swBase4 and in the main library.

To add your own application preference:

1. Add a column to the sLocalPrefs_listdef schema class located in your main library. e.g. LastUserName
2. Close and reopen the main library startup task.

When the oLocalPrefs object is initialized it automatically adds getter and setter methods for the new column which you added to the sLocalPrefs_listdef schema class in the main library.

The following sample code shows you how to set, get, or save any local pref value.

; Set local preference.
Do local_prefs.$:LastUserName.$assign('John Smith')

; Get a local preference.
Do local_prefs.$:LastUserNam Returns UserName

The local prefs are saved each time you close the main library startup task.

Module Preferences

You could store module preferences in a special table in the database. An alternate approach used in StudioWorks is to store them in columns of a row variable in the Refs table. Doing so negates the need for creating additional tables in the database for each module and the need for adding columns to the servertable in the database each time you need to add a new preference for the module.

The StartNewApp demo has a myModulePrefsDemo library which includes the classes needed to implement the StudioWorks approach to storing module preferences in the columns of a row variable in the Refs table.

The mySysAdmin of the StartNewApp demo has an oSysPrefs object class and wSysPrefs window class which you can also review.

The design pattern for module prefs is similar to oAppPrefs and oLocalPrefs. When you want to add a new preference you simply add a column to the applicable sModuleNamePrefs_listdef schema class and rebuild lists.

StudioWorks adds getter and setter propery methods to the oModuleNamePrefs object and you are ready to go!

You can add meta-data for the label and tooltip and then add the edit field to the wModuleNamePrefs window class.

You can directly get any preference settings by instaniating the oModuleNamePrefs object and sending the respective message to the object.

To implement module preferences in one of your libraries do the following:

1. Create a module preferences list definition schema class in your library. e.g. sPayrollPrefs_listdef
2. Add at least one preference column to the schema class.
3. Add the text and tooltip in the description column. Delimit the text and tooltip with the ` backquote character
4. Set the $servertablename to the string table name you wish to use for the module preferences. e.g. Payrollprefs
5. Copy oModulePrefs from myModulePrefsDemo to your library and rename it to a suitable name for your library. e.g. oPayrollPrefs
6. Select the $:PrefsSchemaClassName property method of the module preferences object class and change the return value to the match name of the module preferences list definition schema class you created in your library. e.g. sPayrollPrefs_listdef
7. Copy wModulePrefs from myModulePrefsDemo to your library and rename it to a suitable name for your library. e.g. wPayrollPrefs
8. Change the $dataname property of each edit field in the window class to match the appropriate column names in your module preferences schema class. Change each $tooltip to match the $servertablename and appropriate column name. Delete any extra fields and labels.
9. Change each $text property of any labels to match the $servertablename and appropriate column name.
10. Set the ioModulePrefs ivar of the window class to point to your oModulePrefs module. e.g. oPayrollPrefs.
11. Add your module prefs window class to the oWindowsList object of your module. See oWindowsList in myModulePrefsDemo if you need more details.
12. Add your module prefs window instance ID to the oMenusList object of your module. See oMenusList in myModulePrefsDemo if you need more details.
13. Add your module prefs window instance ID to the sWn_stb schema class of your module.
14. Rebuild all lists and reload string tables for your module.
    
    All going well your module preferences window instance will appear in the navigation treelist. Clicking the node will present your module preferences window class instance and you can set your instance values.

If you want to have default values for any of the module preferences you can set the default in the appropriate propety method of your module preferences object class.


If isnull(iPrefsRow.ColName)
Calculate iPrefsRow.ColName as 'DefaultValue'
End If
Quit method iPrefsRow.ColName

StudioWorks Documentation - Copyright 2005 Vencor Software