Umbraco Commerce
CMSCloudHeartcoreDXP
15.latest
15.latest
  • Umbraco Commerce Documentation
  • Release Notes
    • v15.1.0-Rc
    • v15.0.0-Rc
  • Commerce Products
    • Commerce Packages
    • Commerce Payment Providers
    • Commerce Shipping Providers
  • Getting Started
    • Requirements
    • Installation
    • Licensing
    • Configuration
    • User Interface
  • Upgrading
    • Upgrading Umbraco Commerce
    • Version Specific Upgrade Notes
    • Migrate from Vendr to Umbraco Commerce
      • Migrate Umbraco Commerce Checkout
      • Migrate custom Payment Providers
  • Tutorials
    • Build a Store in Umbraco using Umbraco Commerce
      • Installation
      • Creating a Store
        • Configuring your Store
      • Creating your first Product
      • Implementing a Shopping Cart
        • Using the Umbraco.Commerce.Cart Drop-in Shopping Cart
        • Creating a Custom Shopping Cart
      • Implementing a Checkout Flow
        • Using the Umbraco.Commerce.Checkout Drop-in Checkout Flow
        • Creating a Custom Checkout Flow
      • Configuring Store Access Permissions
  • How-To Guides
    • Overview
    • Configure SQLite support
    • Use an Alternative Database for Umbraco Commerce Tables
    • Customizing Templates
    • Configuring Cart Cleanup
    • Limit Order Line Quantity
    • Implementing Product Bundles
    • Implementing Member Based Pricing
    • Implementing Dynamically Priced Products
    • Implementing Personalized Products
    • Implementing a Currency Switcher
    • Building a Members Portal
    • Order Number Customization
    • Create an Order via Code
  • Key Concepts
    • Get to know the main features
    • Base Currency
    • Calculators
    • Currency Exchange Rate Service Provider
    • Dependency Injection
    • Discount Rules / Rewards
    • Events
      • List of validation events
      • List of notification events
    • Fluent API
    • Order Calculation State
    • Payment Forms
    • Payment Providers
    • Pipelines
    • Price/Amount Adjustments
    • Price Freezing
    • Product Adapters
    • Product Bundles
    • Product Variants
      • Complex Variants
    • Properties
    • ReadOnly and Writable Entities
    • Sales Tax Providers
    • Search Specifications
    • Settings Objects
    • Shipping Package Factories
    • Shipping Providers
    • Shipping Range/Rate Providers
    • Tax Sources
    • UI Extensions
      • Analytics Widgets
      • Entity Quick Actions
      • Order Line Actions
      • Order Properties
      • Order Collection Properties
      • Order Line Properties
      • Store Menu Items
    • Umbraco Properties
    • Unit of Work
    • Umbraco Commerce Builder
    • Webhooks
  • Reference
    • Stores
    • Shipping
      • Fixed Rate Shipping
      • Dynamic Rate Shipping
      • Realtime Rate Shipping
    • Payments
      • Configure Refunds
      • Issue Refunds
    • Taxes
      • Fixed Tax Rates
      • Calculated Tax Rates
    • Storefront API
      • Endpoints
        • Order
        • Checkout
        • Product
        • Customer
        • Store
        • Currency
        • Country
        • Payment method
        • Shipping method
        • Content
    • Management API
    • Go behind the scenes
    • Telemetry
Powered by GitBook
On this page
  • UI Scaffolding
  • Default Values
  • Localization

Was this helpful?

Edit on GitHub
Export as PDF
  1. Key Concepts

Settings Objects

Strongly typed Settings objects in Umbraco Commerce.

PreviousSearch SpecificationsNextShipping Package Factories

Last updated 5 months ago

Was this helpful?

There are places in Umbraco Commerce where you can use Settings Objects to pass configuration to a Provider, such as Discount Rule Providers, Reward Providers, and Payment Providers.

The settings objects have a number of responsibilities.

  • Typed Settings Model - The type represents a strongly typed settings model the given Provider accepts. Any stored settings in the database will be deserialized to this type before being passed to the Provider for processing. This provides strongly typed access to the relevant configuration settings.

  • UI Scaffold - The settings object defines metadata on its properties via an Attribute implementing UmbracoCommerceSettingAttribute, each Provider type has its own attribute type in case they require additional config, for example DiscountRewardProviderSettingAttribute, DiscountRuleProviderSettingAttribute or PaymentProviderSettingAttribute. The attributes are used to dynamically build the AngularJS-based UI for the given Provider configuration. See the section below for more information on UI Scaffolding.

  • JavaScript Settings Model - The settings object also defines the JavaScript settings model passed to the Provider editor UI, using either the settings Property name as the object property key, or using the Key property of the Setting Attribute declared on the given Property.

UI Scaffolding

An important element of the Settings object is UI Scaffolding. UI Scaffolding is where Umbraco Commerce reads a series of Settings Attributes defined on your Settings object properties in order to dynamically build a User Interface for that Providers settings.

An example of a Discount Reward Settings Object might look something like this:

public class MyDiscountRewardProviderSettings
{
    [DiscountRewardProviderSetting(
        EditorUiAlias = "Umb.PropertyEditorUi.DatePicker",
        EditorConfig = "[{ \"alias\":\"offsetTime\", \"value\":true }]")]
    public DateTime Date { get; set; }

    ...
}

Attributes define an optional Key parameter to override the default setting alias which would otherwise be the property name in camel case. An optional EditorUiAlias and EdiutorConfig options can also be defined to control the Umbraco property editor used to edit the given property. If no view is defined, one will attempt to be automatically chosen based on the property's value type.

An example of a generated UI built from these properties would look something like this:

Default Values

To define default values for a settings object, you can assign a value to a property in your model and Umbraco Commerce will automatically fall back to that value if no explicit value is defined.

public class MyDiscountRewardProviderSettings
{
    [DiscountRewardProviderSetting]
    public string Title { get; set; } = "Untitled";

    ...
}

Localization

The format of the localization keys depends on the context. Refer to the specific feature's article for required localization keys.

Labels and descriptions for settings are controlled through entries.

When displaying your settings in the backoffice UI, it is necessary to provide localizable labels. This is controlled by Umbraco's feature.

UI Localization
UI Scaffolding
Localization
Discount Rule UI