Using functional options

This article describes the functional option usage rules. All of the listed recommendations are mandatory unless noted otherwise.

1.1 If your configuration includes optional features, we recommend that you implement functional options that allow enabling or disabling them at the deployment stage. Your Infobase must include data for storing functional option values (such as constants).

For example, your configuration includes optional Infobase data versioning functionality. To manage the availability of this feature, do the following:

• Create the UseVersioning functional option, which defines whether the feature is available in the current Infobase.
• Create the UseVersioning constant of the Boolean type for storing the functional option value.
• In the Data path property of the functional option, specify the UseVersioning constant. 

Then link configuration objects to the functional option by including them in its content. If you need to check the feature availability using 1C:Enterprise script, use the GetFunctionalOption method:

VersioningAvailable = GetFunctionalOption("UseVersioning");

So, a set of functional options describes the configuration functionality whose availability can be configured at the deployment stage according to the company needs. The platform modifies the user interface automatically based on the functional option values.

Functional options can affect the business logic. Such scenarios imply using functional options that have not only Boolean type but also other types, such as references to catalogs or enumeration values. 

1.2. You can specify feature availability not only for the entire Infobase but also depending on the context where the feature is required. For example, the availability of the "charge sales tax" feature can depend on the company. To implement this, do the following:

• Create the AccountingPolicyChargeSalesTax functional option.
• Create the Company functional option parameter (if you have not created it earlier).
• Create the AccountingPolicyTaxAccounting information register for storing the functional option values, with the Company dimension and resources required to manage the "charge sales tax" feature.
  
  
  
• In the Data path property of the functional option, specify the ChargeSalesTax register resource. 
• For the Company functional option parameter, in the Use property, specify the Company dimension of the AccountingPolicyTaxAccounting information register.

Then you can set the functional option value depending on the context, as in the following example:

SetFormFunctionalOptionParameters(New Structure("Company", <CompanyName>));

If you need to check the feature availability using 1C:Enterprise script, you can get the functional option value as in the following example:

AccountingPolicyParameters = New Structure("AccountingPolicyCompany", <CompanyName>);
ChargeSalesTax = GetFunctionalOption("AccountingPolicyChargeSalesTax", AccountingPolicyParameters);
SalesTaxDefinitionTime = GetFunctionalOption("AccountingPolicySalesTaxDefinitionTime", AccountingPolicyParameters);

Important! In addition to the described scenario, other functional option usage scenarios are available. For more information, see the 1C:Enterprise documentation.

1.3. Use functional options according to their intended purpose.

• Do not use functional options for managing the visibility of form controls. Functional options are intended for managing feature availability in the entire configuration, not in a single form (and therefore for managing the form control availability in the entire configuration, not in a single form). 
• Do not use functional options for optimizing access to Infobase data (for storing values on the server). Use modules with reusable return values instead.

Setting and getting functional option values

2.1 The 1C:Enterprise platform does not provide any dedicated features for setting functional option values. You can set their values by assigning values to related constants, catalog items, or information register records.

2.2. If you use functional option parameters and a catalog or information register does not have records linked to the parameter, the functional option is considered disabled. If multiple records are linked to a single parameter, the functional option values are combined using the OR operator.

2.3. If a functional option is linked to a periodic information register resource, the platform uses the "slice last" option for getting the functional option value. To get the functional option value for a different date, you have to specify a value of the Date type for the Period functional option parameter. For example, use the following syntax for a periodic information register with the Company dimension:

SetFormFunctionalOptionParameters(New Structure("Company, Period", <CompanyName>, <Date>));

Note that

• The Period parameter value must be converted to the register periodicity value in order to comply with the recommendation described in paragraph 2.5. For example, for a monthly periodicity use: 

BegOfMonth(<Date>)

• and do not create the Period metadata object because the platform provides this functional option parameter automatically.

2.4. Changing a functional option value does not cause the automatic refreshing of the user interface. To refresh the interface, run the RefreshInterface method.

2.5. Functional option values are cached on the server, which might affect the performance. Large cache size can reduce the performance. That is why we do not recommend parameterizing functional options with data that can have a large number of values. For example, do not use contractors or products as functional option parameters. Besides, the dependence of feature availability on a contractor does not make sense anyway, in practice developers use a dependence on contractor type or other contractor properties. For example, if your configuration includes the ContractorType enumeration, link functional options to this enumeration instead of linking them to the contractor.

Functional option dependencies

3.1 In some scenarios some features should only be available when some other features are available or not available. If your configuration includes such complex dependencies between functional option values, you have to ensure the consistency of data linked to the functional options.

For example, the "move employees between companies" feature (all related documents and reports) should only be available if the "multiple companies" and "human resource management" features are available.

In this scenario all of the metadata objects related to employee movement should not depend on the "multiple companies" and "human resource management" fucntional options. You have to create the "employee movement" functional option and link all metadata objects related to this feature directly to this functional option.

You also have to ensure that the value of this functional option is changed when the values of the "multiple companies" and "human resource management" functional options are changed (for example, when the values of the linked constants are written).

We recommend that you make the values of all three functional options available to the applied solution administator in a settings form. The value of the "employee movement" functional option should be unavailable for editing.

We recommend that you use checkbox fields for such functional option values, with their titles identical to the functional option names. 

3.2. For mutually exclusive functional options, we recommend that you use radio button fields, input fields with drop-down lists, or other controls that imply the selection of a single value from a list. The radio button titles or drop-down list items should be identical to functional option names.

3.3. If the availability of some minor features depends on multiple functional options in a complicated way and you cannot think of a simple and clear name for it, we recommend that you avoid creating a functional option for this feature. Instead, you can check the availability of form controls on the server based on the functional option values using 1C:Enterprise script.

Functional option parameter limitations

4.1. We recommend that you implement no more than 10 functional option parameters in your configuration due to possible performance issues. To reduce the number of functional options, ensure that you do not create multiple functional option parameters with similar meaning. For example, instead of the following two parameters:

• ObjectTypeToBeVersioned, linked to the ObjectType dimension of the ObjectVersioningSettings information register 
• ObjectTypeWithAdditionalReportsAndDataProcessors, linked to the ObjectType dimension of the AdditionalDataProcessorPurposes information register

we recommend that you create a single ConfigurationObjectType functional option parameter linked to both information register dimensions.

4.2. Use the following generic algorithm for designing the list of functional options and their parameters:

1. Define which applied solution features can be optional (can have switches for enabling and disabling them).
2. For each feature, define whether it needs a single switch for the entire Infobase or multiple switches (for example, one per company or one per product).
3. Create the list of all parameterized functional options, as well as the list of their parameters. 
4. Ensure that the list of functional option parameters does not include multiple parameters of a single type (for example, all functional options that depend on the company must use a single parameter).
5. If the total number of functional option parameters is still too big, set parameter priorities based on the number of usage instances and on the importance of parameterized functional options. 
6. Remove the parameters with lower priorities.
7. For functional options that had their parameters removed, do one of the following:
   • Implement them without parameters (so that they affect the entire Infobase)
   • Remove them (if these features do not make sense when applied to the entire Infobase)

As a result, you will end up with a reasonable number of functional option parameters.

Next page: Using session parameters


See also:

• How the changing of values of session parameters and functional options impacts the performance of data access restrictions mechanism