Sana Assistant (online)
Table of Contents

Create an Add-on Project

Before writing any code, a new project for the future add-on has to be added to the Sana Commerce SDK solution.

Add New Project

In Visual Studio, add a new Class Library project under the "Addons" solution folder, targeting .NET 8.0 or appropriate .NET version Extension API is compatible with and specify its location to point to the "Addons" folder under the SDK root directory. The name might be Sana.Extensions.CustomHeadingContentBlock.

Note

It is very important to place a new project into the "Addons" directory under the SDK root, because all projects under this location are treated by Sana in a special way, which is explained later in this article.

Configure Add-on Project

Second, add the following Import statement to the newly created add-on project file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <Import Project="$(MSBuildProjectDirectory)\..\..\Scripts\Addons\msbuild.targets" />
</Project>

Doing this will automatically add the reference to the Sana Extension Framework library and all other required NuGet packages, like System.ComponentModel.Annotations. This will ensure, that an add-on is using the same NuGet packages versions, as the Extension Framework itself.

Add Package Metadata

The next step is to add the obligatory package manifest file, which contains the add-on package metadata.

To do that, add a new XML file named sanamanifest.xml to the root of the add-on project with the following contents:

<SanaPackageInfo>
  <metadata>
    <id>CustomHeadingContentBlock</id>
    <version>1.0.0</version>
    <title>Heading content</title>
    <description>Add-on which allows creating heading content elements.</description>
    <authors>Sana Commerce</authors>
    <type>Extension</type>
    <minSanaVersion>1.0.0</minSanaVersion>
    <minSubscriptionType>Pro</minSubscriptionType>
    <contentBlockUsageRestrictions>
      <location>header,footer,productDetails</location>
      <device>desktop,tablet,mobile</device>
      <contentBlocks>
        <contentBlock>
          <id>BlogCustomHeading</id>
          <location>blogItem</location>
          <device>desktop</device>
        </contentBlock>
      </contentBlocks>
    </contentBlockUsageRestrictions>
    <tags>content</tags>
  </metadata>
</SanaPackageInfo>

Here is an overview of the contents of the add-on package manifest file:

  • id - A unique add-on identifier, which will stay constant across all future add-on versions. It should be a single word (preferrably in PascalCase) and should not conflict with any other add-ons.
  • version - An add-on version. Supported formats are: "X.X", "X.X.X" and "X.X.X.X", where X is a non-negative number. It is highly recommended to use the Semantic Versioning approach for add-ons versioning.
  • title - (optional) A human-readable name of the add-on which is shown to the users in Sana Admin.
  • description - (optional) A human-readable short description of the add-on which describes what add-on does.
  • authors - The list of add-on authors, separated by comma (,).
  • type - For add-on packages, this field must always have value of Extension.
  • minSanaVersion - The version of Sana Commerce SDK, the add-on is developed with. This will set a limitation, so that this add-on will be compatible only with the current and future versions of Sana Commerce and cannot be installed into an older Sana Commerce installation.
  • maxSanaVersion - (optional) The highest version of Sana Commerce this package is compatible with.
  • minSubscriptionType - (optional) The minimal subscription type for add-on. It cannot be installed if subscription type is less than required by add-on.
  • contentBlockUsageRestrictions - (optional) The ability to add add-on content blocks usage restrictions. The value can limit add-on content blocks usage by specific location or device. It is possible to set general usage restrictions and content block specific usage restrictions.
    • location content blocks usage restrictions can contain multiple items and define all possible locations. To assign location restrictions add location inside contentBlockUsageRestrictions node with values from list below. If there is no value (empty list) add-on content blocks will be shown for all locations.
    • device content blocks usage restrictions can also contain multiple items and define all possible devices. To assign device restrictions add device inside contentBlockUsageRestrictions node with values from list below. If there is no value (empty list) add-on content blocks will be shown for all devices.
    • contentBlocks - (optional) The list of content block specific usage restrictions. General content blocks usage restrictions will be replaced. Each addon can contain several content blocks, accordingly it is possible to set specific restrictions for each of the content blocks.
      • id - The unique content block identifier.
      • location content block usage restrictions. The same set of values as for the general location parameter is supported.
      • device content block usage restrictions. The same set of values as for the general device parameter is supported.
  • tags - (optional) The list of add-on tags, separated by comma (,).

Note

Below a list of elements and their respective values.

Element Name Value
minSubscriptionType - Essential
- Pro
- Advanced
device - desktop
- tablet
- mobile
location - header
- footer
- productDetails
- productGroupDetails
- contactUs
- forgotPassword
- resetPassword
- login
- closedStoreLogin
- blog
- blogItem
- myAccountDashboard
- accountDetails
- editShippingAddress
- createShippingAddress
- subAccount
- orders
- quotes
- invoices
- returnOrders
- creditNotes
- returnReceipts
- shipments
- orderAuthorizations
- salesAgreements
- createDocFreeReturnOrder
- createDocBasedReturnOrder
- registration
- b2BRegistrationSuccess
- registrationSuccess
- loginDetails
- createProspect
- subAccounts
- orderConfirmation
- orderFailed
- orderCancelled
- paymentError
- salesAgreementDetails
- invoicePayment
- orderPayment
- orderDetails
- quoteDetails
- invoiceDetails
- returnOrderDetails
- creditNoteDetails
- returnReceiptDetails
- shipmentDetails
- content
- basket
- orderTemplates
- orderTemplateDetails
- offline
- represent
- productList
- search
- contentSearch
- lastViewedProducts
- oneStepCheckout
- multiStepCheckout
- productListItemRow
- twoFactorAuthenticationSetup
- twoFactorAuthenticationSetupConfirmation
- twoFactorAuthenticationRecoveryCodes
- twoFactorAuthenticationGeneralConfirmation
- twoFactorAuthenticationLoginConfirmation
- twoFactorAuthenticationClosedStoreLoginConfirmation
- twoFactorAuthenticationLoginWithRecoveryCode
- twoFactorAuthenticationClosedStoreLoginWithRecoveryCode
- twoFactorAuthenticationSpentRecoveryCodeAlert
- orderSubscriptions
- orderSubscriptionDetails
- orderSubscriptionProducts
- orderSubscriptionSettings
- subscriptionOrderConfirmation
- productComparison
tag - content
- forms
- navigation
- orderProcess
- productInformation
- socialAndContact

What's next?

Continue with creating your first simple Content Block Add-on.