Creating Configurable Options

About Configurable Options

Configurable Options consist of additional fields that request information from clients when ordering packages. These fields can have a price associated with them and add to the base price set for the package. Configurable Options can be of the following types:

• Checkbox
• Radio
• Drop-Down
• Quantity
• Text (v4.3)
• Textarea (v4.3)
• Password (v4.3)

Configurable Option values are passed into modules during service provisioning, so modules expecting these fields can use the information to alter the way they provision the service.

Configurable Option Group Overview

Configurable Options Overview

Creating an Option Group

To create a configurable option group, visit [Packages] > [Options] and click the "Create Group" button.

The following form will be displayed:

1. Enter a name for the group. This name will only be visible in the staff area, and not visible to clients.
2. Enter a description for the group.
3. Select what packages this group should be assigned to, if any.
4. Click the "Create Group" button to create the option group.
   
   

Creating an Option

To create a configurable option, visit [Packages] > [Options] and click the "Create Option" button.

The following form will be displayed:

There are several sections, Basic, Options, and Group Membership.

Basic

The Basic section requires the following fields:

1. Label - This is the form label that will appear directly above this field
2. Name - This is the form field name, which is hidden. If this field is passing information into a module, the module may require it to have a specific name.
3. Description - This will be shown as a tooltip next to the option to explain it.
4. Type - The type of field, either "Checkbox", "Radio", "Drop down", "Quantity", "Text", "Textarea", or "Password".
5. Client can Add - Check to allow clients to add the config option to a service order or addon.
6. Client can Edit - Check to allow clients to edit the config option on existing services.

Options

The options that are displayed vary depending on the "Type" selected above.

Checkbox

When creating an option of the type check-box, the following will be displayed:

1. Name - Enter the display name for this option, which will appear next to the checkbox.
2. Value - Enter the value for this option, which if checked, will be submitted through the form.
3. Default - By checking or unchecking this box you will set the default value of the config option

Pricing

Enter the pricing for this option for every term and currency that this option should exist for.

Radio

When creating an option of the type radio, the following will be displayed:

1. Name - Enter the display name for this option, which will appear next to the radio option.
2. Value - Enter the value for this option, which if selected, will be submitted through the form.
3. Default - By checking the radio on this option you will set it as the default value of the config option
4. Status - Inactive option values can no longer be selected for services, but can be kept for existing services until changed to a different value.
5. Click "Add Additional Option" to continue adding more radio items to the form.

Pricing

Enter the pricing for this option for every term and currency that this option should exist for.

Drop Down

The drop down type looks identical to the radio type:

1. Name - Enter the display name for this option, which will appear above the drop down.
2. Value - Enter the value for this option, which if selected, will be submitted through the form.
3. Default - By checking the radio on this option value you will set it as the default value of the config option
4. Status - Inactive option values can no longer be selected for services, but can be kept for existing services until changed to a different value.
5. Click "Add Additional Option" to continue adding more items to the drop down.

Pricing

Enter the pricing for this option for every term and currency that this option should exist for.

Quantity

When creating an option of the type quantity, the following is displayed:

1. Name - Enter the display name for this option, which will appear above a slider.
2. Min - Enter the minimum quantity available to order.
3. Max - Enter the maximum quantity available to order.
4. Step - Enter the step or increment size.
5. Default - By checking the radio on this option value you will set it as the default value of the config option

Pricing

Enter the pricing for this option for every term and currency that this option should exist for. The price is per-unit. So, if the user selects a quantity of 100 for example, it will be multiplied by the price defined here.

Text

When creating an option of the type text, the following will be displayed:

Pricing

Enter the pricing for this option for every term and currency that this option should exist for.

Textarea

When creating an option of the type textarea, the following will be displayed:

Pricing

Enter the pricing for this option for every term and currency that this option should exist for.

Password

When creating an option of the type password, the following will be displayed:

Pricing

Enter the pricing for this option for every term and currency that this option should exist for.

Adding Configurable Options to Packages

Configurable Options must be assigned to one or more Configurable Option Groups in order to be usable. Assigning configurable options to packages is a matter of assigning a configurable option group to a package, which can be done in either of two ways:

1. Edit or create a Package, click to expand "Configurable Options", and move the option groups containing the options you wish to add to the package from the right to the left in the multi-select box. 
2. OR, edit the Package Option Group under [Packages] > [Options] > Groups, and move the packages you wish to add the options in this group to from the right to the left in the multi-select box.

That's it! When clients order packages, the options contained in all configurable option groups that are assigned to the package will be available.

Sorting Configurable Options

Configurable Options can be sorted within their groups by clicking to expand the group and using drag and drop to order them.

On this screen, hovering over the options under the group will display a sort icon in the left most column. To sort, click and hold on the option you wish to move, and drag it up or down in the list, releasing it where you wish to place it.

Using Configurable Options in Welcome Emails

Configurable options can be used in welcome emails and are numerically indexed within the services.options array. As an example, the value for the first configurable option would be available by using the following tag:

{services.options.0.value}

If you want to show all options, it's better to use a for loop. This will show the field label and the value, e.g.

License Key: 123-my-license-key
Notes: Here are some notes.
...

{% for option in service.options %}
{option.option_label}: {option.value}
{% endfor %}

To determine what index your config option has, you can use the {% debug %} tag in your welcome email and observe the data. Do not leave the tag in your welcome email, it may contain sensitive data that should not be emailed to clients. Below is an example of the array using a config option label of "License Key", with a name of "license-key", and a value of "new-key-123-abcdefg-license". Indexes start at 0, so the first will have an index of 0, the second an index of 1, and so on.

    [service] => stdClass Object
        (
            [id] => 3
            ....

            [options] => Array
                (
                    [0] => stdClass Object
                        (
                            [id] => 2
                            [service_id] => 3
                            [option_pricing_id] => 1
                            [qty] => 1
                            [value] => new-key-123-abcdefg-license
                            [encrypted] => 0
                            [option_value] => 
                            [option_value_name] => 
                            [option_id] => 1
                            [option_label] => License Key
                            [option_name] => license-key
                            [option_type] => textarea
                            [option_addable] => 0
                            [option_editable] => 0
                            [option_pricing_term] => 1
                            [option_pricing_period] => month
                            [option_pricing_price] => 0.0000
                            [option_pricing_price_renews] => 0.0000
                            [option_pricing_setup_fee] => 0.0000
                            [option_pricing_currency] => USD
                        )

                )

Overriding Module Row or Module Group with Configurable Options

Module Rows are typically associated with a server, and Module Groups are typically associated with a group of servers. For example, a shared hosting module like DirectAdmin allows you to create "Server Groups" and "Servers". A server group would be considered a Module Group, and a server would be considered a module row. These definitions may change from module to module, but whatever they are called within the module, they can be overridden.

Typically these are defined on a Package. For example, using the DirectAdmin module as an example, on the Package you can set a specific server or server group to provision new accounts from. These can be overridden with a configurable option. A common use-case for this is "Location". If servers are organized into groups, and those groups designate a location, you can allow the client to select their location on their own.

The value of the field should match the ID for the group, or row, specifically. To determine the group or row ID, edit the group or row and observe the ID in the URL.

/admin/settings/company/modules/editgroup/5/1/ (In this case, the group ID is "1")

/admin/settings/company/modules/editrow/5/4/ (In this case, the row ID is "4")