Oqtane Tutorials
Oqtane Tutorials

Formulas Tutorials

Tutorial Home › Formulas
Formulas affecting Groups of Fields
#5 Formulas using Parameters
Advanced Formula APIs
Requirements
Resources

Formulas using Parameters

Important: The feature "Public Use of Edit Form" is disabled

If you want this demo to run for anonymous users you would need it. Register your site on patrons.2sxc.org to get access to the feature.

Formulas with parameters or App Settings

We'll show you how to use page parameters with formulas

In this tutorial you'll learn how to:

  • Use emphemeral fields
  • Use data.parameters in your formulas new in v14

Important: Now using Formulas V2 🆕 in 2sxc 16

Formulas V2 has intellisense, stoppability, support for promises and more.

Try it:

This doesn't tell the form anything

    This tells the form to show advanced prefill:VarShowAdvanced=true

      This example uses an ephemeral field which is prefilled from the open-button.

      VarShowAdvanced is an ephemeral field and thus not saved in the database. This formula determines the visibility of the Advanced Settings group. The group becomes visible, when the VarShowAdvanced toggle is active.


      Click on the (Σ) button above to see the edit-UI with the formula.

      Formulas of FormulasEphemeral.AdvancedGroup

      Field.Settings.Visible (Formula-Target: Field.Settings.Visible)

      v2((data) => {
  return data.VarShowAdvanced == true;
});

      Ephemeral (Non-Saving) Fields in Formulas

      Sometimes you need fields which controle the Form UI without being real data. Some examples:

      • Toggles which show/hide other fields or field groups
      • Hidden calculations which will consolidate other field values to determine if something else is required

      We don't want to save these fields as the data is not relevant, and often the value should be calculated upon opening the form - so it's important that they are reset.

      Create an Ephemeral field

      An Ephemeral field is just a normal field with an additional configuration. 

      To configure it, check out the picture. 

      Learn more about Ephemeral fields here.

      Configure edit form UI using parameters

      In 2sxc v15 we added data.parameters.* which contains all parameters given in the FormParameters.

      By passing parameters directly, edit forms can be configured without the need of additional Ephemeral fields. This enables a editing experience matching the page context.

      Try it:

      This will show the advanced stuff form:showAdvanced=true

        This won't show advanced stuff form:showAdvanced=false

          This also won't (no parameters)

            showAdvanced is a parameter, that was passed with the toolbar form:. This formula determines the visibility of the Advanced Settings group. The group becomes visible, when the passed showAdvanced parameter is true.


            Click on the (Σ) button above to see the edit-UI with the formula.

            Formulas of FormulasParameters.AdvancedGroup

            Field.Settings.Visible (Formula-Target: Field.Settings.Visible)

            v2((data) => {
  if (!data.parameters || data.parameters.showAdvanced == null)
    return false;
  return data.parameters.showAdvanced == "true";
});

            Try it:

              This will show how a formula accesses the App Setting Settings.FormulaDemoShowAdvanced to determine if it should show more fields. 


              Click on the (Σ) button above to see the edit-UI with the formula.

              Formulas of FormulasUseSettings.GroupAdvanced

              Field.Settings.Visible (Formula-Target: Field.Settings.Visible)

              v2((data, context) => {
  return context.app.getSetting("Settings.FormulaDemoShowAdvanced");
});

              Formulas using WebAPI and REST calls

              Formulas can retrieve data from WebAPIs and REST. We have various examples of this on other pages, so this page will just repeat the examples from those page.

              Try it:

                This formula is very advanced, and will initialize a fields value (if empty) from a WebAPI call.

                🆕 in v2 all formulas returning a promise are stopped by default!
                This is why the code is much simpler compared to v1.

                If ever necessary, the promise returned can specify to not stop the formula, but we don't need this for the current demo.


                Click on the (Σ) button above to see the edit-UI with the formula.

                Formulas of FormulasWebApiText.Title

                Field.Settings.Disabled (Formula-Target: Field.Settings.Disabled)

                v2((data) => {
  // Only enable once data has been loaded
  return !data.Title;
});

                Field.Value (Formula-Target: Field.Value)

                v2((data, context) => {
  // for demo reasons, don't do this till start is toggled.
  if (!data.Start) return data.value;
  
  // Call the sxc web-api controller from other tutorials
  return context.sxc.webApi.fetchJson('app/auto/api/basic/hello')
    .then(data => {
      console.log('got data', data); // log for demo reasons
      return data; // Use the result as the new value
    });
});

                Source Code of BasicController.cs

                // Add namespaces for security check in Oqtane & DNN despite differences in .net core/.net Framework
// If you only target one platform, you can remove the parts you don't need
#if NETCOREAPP
using Microsoft.AspNetCore.Authorization; // .net core [AllowAnonymous] & [Authorize]
using Microsoft.AspNetCore.Mvc;           // .net core [HttpGet] / [HttpPost] etc.
#else
using System.Web.Http;                    // .net 4.5 [AllowAnonymous] / [HttpGet]
using DotNetNuke.Web.Api;                 // [DnnModuleAuthorize] & [ValidateAntiForgeryToken]
#endif

[AllowAnonymous]                          // all commands can be accessed without a login
public class BasicController : Custom.Hybrid.Api14 // see https://r.2sxc.org/CustomWebApi
{
  [HttpGet]                               // [HttpGet] says we're listening to GET requests
  public string Hello()
  {
    return "Hello from the basic controller in /api";
  }

  [HttpGet]        // [HttpGet] says we're listening to GET requests
  public int Square(int number)
  {
    return number * number;
  }

}

// The next line is for 2sxc-internal quality checks, you can ignore this
// 2sxclint:disable:no-dnn-namespaces - 2sxclint:disable:no-web-namespace

                Try it:

                  This is an advanced formula which will call a WebApi to get the possible values in a drop down. 


                  Click on the (Σ) button above to see the edit-UI with the formula.

                  Formulas of FormulasDropdownWebApi.Dropdown

                  Field.Settings.DropdownValues (Formula-Target: Field.Settings.DropdownValues)

                  v2((data, context) => {
  // Call the sxc web-api controller from other tutorials
  return context.sxc.webApi.fetchJson('app/auto/api/formulas/OptionsFromBackend')
    .then(data => {
      console.log('got data', data);// log for demo reasons
      // The result is a dictionary, so we convert to lines
      const lines = Object.keys(data)
        .map(k => k + ":" + data[k])
        .join('\n');

      return lines;
    });
});

                  Source Code of FormulasController.cs

                  // Add namespaces for security check in Oqtane & DNN despite differences in .net core/.net Framework
// If you only target one platform, you can remove the parts you don't need
#if NETCOREAPP
using Microsoft.AspNetCore.Authorization; // .net core [AllowAnonymous] & [Authorize]
using Microsoft.AspNetCore.Mvc;           // .net core [HttpGet] / [HttpPost] etc.
#else
using System.Web.Http;                    // .net 4.5 [AllowAnonymous] / [HttpGet]
using DotNetNuke.Web.Api;                 // [DnnModuleAuthorize] & [ValidateAntiForgeryToken]
#endif
using System.Linq;        // this enables .Select(x => ...)
using System.Collections.Generic;          // To use the Dictionary

[AllowAnonymous]                          // all commands can be accessed without a login
public class FormulasController : Custom.Hybrid.Api14 // see https://r.2sxc.org/CustomWebApi
{
  [HttpGet]                               // [HttpGet] says we're listening to GET requests
  public object OptionsFromBackend()
  {
    var results = new Dictionary<string, string>() {
      { "first", "First option from WebApi" },
      { "second", "Second option from WebApi"},
      { "third", "3rd option" }
    };
    return results;
  }

  // Note: Persons just copied from Books Controller to test functionality
  [HttpGet]                               // [HttpGet] says we're listening to GET requests
  public object Persons()
  {
    return AsList(App.Data["Persons"])
      .ToDictionary(x => x.EntityId.ToString(), p => p.FirstName + " " + p.LastName);
  }
}

// The next line is for 2sxc-internal quality checks, you can ignore this
// 2sxclint:disable:no-dnn-namespaces - 2sxclint:disable:no-web-namespace

                  Try it:

                    This is an advanced formula which will call a WebApi to get the possible values in a drop down - from Data in the App. 


                    Click on the (Σ) button above to see the edit-UI with the formula.

                    Formulas of FormulasDropDownWebApiData.Dropdown

                    Setting DropdownValues (Formula-Target: Field.Settings.DropdownValues)

                    v2((data, context) => {
  // Call the sxc web-api controller from other tutorials
  const promise = context.sxc.webApi.fetchJson('app/auto/api/formulas/Persons')
    .then(result => {
      console.log('got result', result);// log for demo reasons
      // The result is a dictionary, so we convert to lines
      return Object.keys(result)
        .map(k => k + ":" + result[k] + ' (' + k + ')')
        .join('\n');
    });

  // Return a loading value and a promise for later...
  return { value: data.value, promise };
});

                    Source Code of FormulasController.cs

                    // Add namespaces for security check in Oqtane & DNN despite differences in .net core/.net Framework
// If you only target one platform, you can remove the parts you don't need
#if NETCOREAPP
using Microsoft.AspNetCore.Authorization; // .net core [AllowAnonymous] & [Authorize]
using Microsoft.AspNetCore.Mvc;           // .net core [HttpGet] / [HttpPost] etc.
#else
using System.Web.Http;                    // .net 4.5 [AllowAnonymous] / [HttpGet]
using DotNetNuke.Web.Api;                 // [DnnModuleAuthorize] & [ValidateAntiForgeryToken]
#endif
using System.Linq;        // this enables .Select(x => ...)
using System.Collections.Generic;          // To use the Dictionary

[AllowAnonymous]                          // all commands can be accessed without a login
public class FormulasController : Custom.Hybrid.Api14 // see https://r.2sxc.org/CustomWebApi
{
  [HttpGet]                               // [HttpGet] says we're listening to GET requests
  public object OptionsFromBackend()
  {
    var results = new Dictionary<string, string>() {
      { "first", "First option from WebApi" },
      { "second", "Second option from WebApi"},
      { "third", "3rd option" }
    };
    return results;
  }

  // Note: Persons just copied from Books Controller to test functionality
  [HttpGet]                               // [HttpGet] says we're listening to GET requests
  public object Persons()
  {
    return AsList(App.Data["Persons"])
      .ToDictionary(x => x.EntityId.ToString(), p => p.FirstName + " " + p.LastName);
  }
}

// The next line is for 2sxc-internal quality checks, you can ignore this
// 2sxclint:disable:no-dnn-namespaces - 2sxclint:disable:no-web-namespace

                     

                     

                    Formulas affecting Groups of Fields
                    #5 Formulas using Parameters
                    Advanced Formula APIs