Functional options

Scope: managed applications, mobile applications, and ordinary applications.

1.1. When you develop a configuration, sometimes you need to embed optional features, which can be enabled or disabled in the settings. To implement such features, use the functional option mechanism. The values of functional options are stored in metadata objects, such as constants.

For example, a configuration contains a data versioning management feature, which you want to make optional. To do so, do the following:

Create the functional option UseObjectsVersioning, which will define whether the feature is enabled or disabled.
Create the Boolean constant UseObjectsVersioning, which will store the value of the functional option.
In the option's Data path property, specify the UseObjectsVersioning constant.

After that, you can link configuration objects to the functional option. To do so, specify the objects in the option's content. To manage code availability, use the method GetFunctionalOption. Example:

VersioningMechanismUsed = GetFunctionalOption("UseObjectsVersioning");

By using functional options, you can customize the availability of features depending on the client's needs. After the value of a functional option is changed, 1C:Enterprise platform modifies the user interface.

You can employ functional options to display or hide elements of the user interface and to modify the application's business logic. Usually, functional options take Boolean values. But to make the business logic management more flexible, you can use other data types, such as enumeration references.

1.2. The availability of functional options can be set up for the whole configuration or conditionally, for some of its objects. For example, some of the companies in a holding are subjects to VAT charge and some are not. You need to set up the accounting scheme depending on the company's VAT registration status. To do so:

Create the functional option AccountingPolicyVATAccounting.
Create the functional option parameter Company.
To store the functional option values, create the information register AccountingPolicyTaxAccounting with the Company dimension and resources required to manage the VAT accounting.
For the functional option, set the Data path property to the VATAccounting resource.
For the Company functional option parameter, set the Use property to the Company dimension of the AccountingPolicyTaxAccounting information register.

Now, you need to customize forms depending on the functional option value.

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

You can also set up the code availability depending on the functional option value. The example below shows how you can get its value:

AccountingPolicyParameters = New Structure("AccountingPolicyCompany", <CompanyName>);
VATAccounting = GetFunctionalOption("AccountingPolicyVATAccounting", AccountingPolicyParameters);
IdentifyTaxationScheme = GetFunctionalOption("AccountingPolicyIdentifyTaxationScheme", AccountingPolicyParameters);

Please note that the use of functional options is not limited by the above-mentioned case. It is a flexible mechanism that supports a wide range of scenarios.
For more details, see 1C:Enterprise Developer Guide.

1.3. Do not use the functional option mechanism for the following scenarios:

To hide and show the interface elements on a single form. The mechanism is intended to control interface elements or features throughout the configuration. Using it to control one form would be a misuse.
To optimize the access to the server data. For this purpose, employ memoization modules.

How to set and get values

2.1 1C:Enterprise platform does not provide any specific tool to set functional option values. To set a value, you can use the general features, like editing the constant values, catalog items, or information register records. The choice of the approach is at the developer's discretion.

2.2. For functional options with parameters, if the catalog or information register is missing the record that matches the parameter, the option is disabled. If the parameter matches with multiple records, the option values are combined using the OR operator.

2.3. If a functional option is linked to a resource of a periodic information register, by default, the option takes the newest record. If you need to get the option value for a certain date, specify the date in the Period functional option parameter, which has the Date type. For example, for a periodic information register that has the Company dimension:

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

Note that

The value of the Period parameter must be rounded to the first day of the register period to comply with the requirements stated in 2.5. For example, if an information register period is one month then:

BegOfMonth(<RequiredDate>)

Note that when you create a functional option, the Period parameter is created automatically.

2.4. When a functional option value is modified, the interface is not refreshed automatically. To run the interface refresh, call the RefreshInterface method.

2.5. Functional option values are cached on the server. Note that too large cache can have a negative effect on the performance. To avoid that, do not parameterize functional options with objects that are expected to have a large number of values. For example, do not use counterparty or product as a parameter since, in general, a company has a long list of counterparties and products. Using counterparties as a criterion is a misuse of the functional option mechanism. Instead, use counterparty's properties. For example, a configuration contains the enumeration CounterpartyType. The functional option takes its value depending on the counterparty's type.

Dependencies between functional options

3.1. Sometimes, a feature's availability depends on another feature' value. In this case, make sure the data related to the functional options are consistent.

For example, the feature that allows the transfer of employees between companies is available only when the functional options "Multi-company accounting" and "Human resources" are enabled.

Incorrect: each metadata object that relates to the employee transfers depends on the "Multi-company accounting" and "Human resources" values. Correct: there is the functional option "Employee transfer" and the metadata objects depend on its value.

The availability of "Employee transfer" depends on the "Multi-company accounting" and "Human resources" values.

The system administrator can access the values of all three functional options in a settings form. The value of "Employee transfer" is read-only.

To edit the values, create a "Field" control of the "Checkbox" type. The field title should match the functional option name.

3.2. When you have a number of mutually exclusive functional options, use a control that allows you to choose one item from a number of options, such as radio buttons or a drop-down list. The titles of the items must match the names of the functional options.

3.3. If a minor feature's availability depends on a number of functional options, it is recommended that you don't create a functional option that will manage that feature. Instead, when the form is created on the server, manage the availability of the form elements programmatically, by analyzing the functional option values.

Number of functional option parameters

4.1. To avoid configuration performance downgrade, limit the number of functional option parameters to 10. Make sure that the purposes of the functional option parameters don't overlap. For example, these two parameters:

VersionizedObjectType linked to the ObjectType dimension of the ObjectsVersioningSetting information register, and
ObjectTypeWithAdditionalReportsAndDataProcessors linked to the ObjectType dimension of the AdditionalDataProcessorsPurposes information register

Can be replaced with one ConfigurationObjectType that is linked to the dimensions of both information registers.

4.2. To design a functional option, take the following steps:

Analyze what features should be optional, that is enabled in some cases and disabled in others.
For each feature, define whether you need one control that would enable and disable the feature for the whole configuration or a few controls for different entities.
Make a list of all functional options and their parameters.
The list must not contain several parameters of the same type. For example, if a number of functional options depend on the company type, they all must use the same parameter.
If the number of the parameters is unreasonably large, make a short-list: analyze all functional options that use a parameter and rank their importance.
Cross out the less important parameters.
For each functional option whose parameters have been crossed out:

Reconsider the functional option to be non-parameterized. That is, it is enabled or disabled for the whole configuration.
Delete the functional option if without parameterization it cannot deliver its purpose.

As a result, you will get a reasonable number of parameters.

See also:

How session parameters and functional options affect data access restrictions