Oqtane Tutorials
Oqtane Tutorials

Formulas Tutorials

Tutorial Home › Formulas
Formulas for Field-Groups
#6 Formulas with parameters or App Settings
Formulas using REST or WebApi Calls
Requirements
Resources

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.

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.

Ephemeral fields explained

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.

Configure an Epemeral field

To configure a field to not save and be temporary / ephemeral, use this setting:

Learn more about Ephemeral fields here.

Ephemeral field

Button which doesn't tell the form anything:

    Button which will tell the form to show advanced:

      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;
});
      Button which doesn't tell the form anything:
@Kit.Toolbar.Empty().New("FormulasEphemeral", ui: Sys.SourceCode.Formulas.Icon()).AsTag()
<br>
Button which will tell the form to show advanced:
@Kit.Toolbar.Empty().New("FormulasEphemeral",
  ui: Sys.SourceCode.Formulas.Icon(),
  prefill:"VarShowAdvanced=true"
).AsTag()

      Configure edit form UI using parameters

      In 2sxc v14 we added data.parameters.* which contains all parameters given in the prefill.

      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.

      prefill:showAdvanced=true:

        prefill:showAdvanced=false:

          showAdvanced is a parameter, that was passed with the toolbar prefill. 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 based on the passed prefill parameter.

          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";
});
          <code>prefill:showAdvanced=true</code>:
@Kit.Toolbar.Empty().New("FormulasParameters",
  ui: Sys.SourceCode.Formulas.Icon(),
  prefill: "showAdvanced=true"
).AsTag()
<br>
<code>prefill:showAdvanced=false</code>:
@Kit.Toolbar.Empty().New("FormulasParameters",
  ui: Sys.SourceCode.Formulas.Icon(),
  prefill: "showAdvanced=false"
).AsTag()

          Example without Ephemeral field (new v14)

          Try it:

            If you just need a parameter and don't expect the user to toggle it, you can use data.parameters. You can still pass it in using prefill, but don't need to create a field.


            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";
});
            @inherits Custom.Hybrid.Razor14
@using ToSic.Razor.Blade;
<!-- unimportant stuff, hidden -->


<div @Sys.PageParts.InfoWrapper()>
  @Html.Partial("../shared/DefaultInfoSection.cshtml")
  <div @Sys.PageParts.InfoIntro()>
    <h2>Formulas with parameters or App Settings</h2>
    <p>We'll show you how to use page parameters with formulas</p>
    <p>In this tutorial you'll learn how to:</p>
    <ul>
      <li>
        Use emphemeral fields
      </li>
      <li>
        Use <code>data.parameters</code> in your formulas <em>new in v14</em>
      </li>
    </ul>
    @Html.Partial("./Part NowUsingV2.cshtml")
  </div>
</div>
@Html.Partial("../shared/WarnAnonymousIfFeatureIsOff.cshtml")

<h3>Ephemeral fields explained</h3>
<p>Sometimes you need fields which controle the Form UI without being real data. Some examples:</p>
<ul>
  <li>Toggles which show/hide other fields or field groups</li>
  <li>Hidden calculations which will consolidate other field values to determine if something else is required</li>
</ul>

<p>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.</p>

<h3>Create an Ephemeral field</h3>
<p>An Ephemeral field is just a normal field with an additional configuration.</p>
<h4>Configure an Epemeral field</h4>
<p>To configure a field to not save and be temporary / ephemeral, use this setting:</p>

<p>Learn more about Ephemeral fields <a href="https://docs.2sxc.org/basics/data/fields/ephemeral.html">here</a>.</p>



<h3>Ephemeral field </h3>
@{
  var specs = Sys.SourceCode.Formulas.Specs("parameters-ephemeral");
}

  Button which doesn't tell the form anything:
  @Kit.Toolbar.Empty().New("FormulasEphemeral", ui: Sys.SourceCode.Formulas.Icon()).AsTag()
  <br>
  Button which will tell the form to show advanced:
  @Kit.Toolbar.Empty().New("FormulasEphemeral",
    ui: Sys.SourceCode.Formulas.Icon(),
    prefill:"VarShowAdvanced=true"
  ).AsTag()

<p>
  <code>VarShowAdvanced</code> 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.
  <br>
  <em>Click on the (Σ) button above to see the edit-UI with the formula. </em>
</p>




<h3>Configure edit form UI using parameters</h3>
<p>
  In 2sxc v14 we added <code>data.parameters.*</code> which contains all parameters given in the prefill.
</p>
<p>
  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.
</p>

@{ specs = Sys.SourceCode.Formulas.Specs("parameters-basic"); }

  <code>prefill:showAdvanced=true</code>:
  @Kit.Toolbar.Empty().New("FormulasParameters",
    ui: Sys.SourceCode.Formulas.Icon(),
    prefill: "showAdvanced=true"
  ).AsTag()
  <br>
  <code>prefill:showAdvanced=false</code>:
  @Kit.Toolbar.Empty().New("FormulasParameters",
    ui: Sys.SourceCode.Formulas.Icon(),
    prefill: "showAdvanced=false"
  ).AsTag()

  <p>
    <code>showAdvanced</code> is a parameter, that was passed with the toolbar prefill.
    This formula determines the visibility of the Advanced Settings group.
    The group becomes visible, when the passed <code>showAdvanced</code> parameter is true.
    <br>
    <em>Click on the (Σ) button above to see the edit-UI with the formula based on the passed prefill parameter. </em>
  </p>







@* Footer *@
@Html.Partial("../Shared/Layout/FooterWithSource.cshtml", new { Sys = Sys })

            Use App Settings in Formulas (new v16)

            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 for Field-Groups
              #6 Formulas with parameters or App Settings
              Formulas using REST or WebApi Calls

              Source Code of this file

              Below you'll see the source code of the file. Note that we're just showing the main part, and hiding some parts of the file which are not relevant for understanding the essentials. Click to expand the code

              @inherits Custom.Hybrid.Razor14
@using ToSic.Razor.Blade;
<!-- unimportant stuff, hidden -->


<div @Sys.PageParts.InfoWrapper()>
  @Html.Partial("../shared/DefaultInfoSection.cshtml")
  <div @Sys.PageParts.InfoIntro()>
    <h2>Formulas with parameters or App Settings</h2>
    <p>We'll show you how to use page parameters with formulas</p>
    <p>In this tutorial you'll learn how to:</p>
    <ul>
      <li>
        Use emphemeral fields
      </li>
      <li>
        Use <code>data.parameters</code> in your formulas <em>new in v14</em>
      </li>
    </ul>
    @Html.Partial("./Part NowUsingV2.cshtml")
  </div>
</div>
@Html.Partial("../shared/WarnAnonymousIfFeatureIsOff.cshtml")

<h3>Ephemeral fields explained</h3>
<p>Sometimes you need fields which controle the Form UI without being real data. Some examples:</p>
<ul>
  <li>Toggles which show/hide other fields or field groups</li>
  <li>Hidden calculations which will consolidate other field values to determine if something else is required</li>
</ul>

<p>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.</p>

<h3>Create an Ephemeral field</h3>
<p>An Ephemeral field is just a normal field with an additional configuration.</p>
<h4>Configure an Epemeral field</h4>
<p>To configure a field to not save and be temporary / ephemeral, use this setting:</p>

<p>Learn more about Ephemeral fields <a href="https://docs.2sxc.org/basics/data/fields/ephemeral.html">here</a>.</p>



<h3>Ephemeral field </h3>
@{
  var specs = Sys.SourceCode.Formulas.Specs("parameters-ephemeral");
}

  Button which doesn't tell the form anything:
  @Kit.Toolbar.Empty().New("FormulasEphemeral", ui: Sys.SourceCode.Formulas.Icon()).AsTag()
  <br>
  Button which will tell the form to show advanced:
  @Kit.Toolbar.Empty().New("FormulasEphemeral",
    ui: Sys.SourceCode.Formulas.Icon(),
    prefill:"VarShowAdvanced=true"
  ).AsTag()

<p>
  <code>VarShowAdvanced</code> 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.
  <br>
  <em>Click on the (Σ) button above to see the edit-UI with the formula. </em>
</p>




<h3>Configure edit form UI using parameters</h3>
<p>
  In 2sxc v14 we added <code>data.parameters.*</code> which contains all parameters given in the prefill.
</p>
<p>
  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.
</p>

@{ specs = Sys.SourceCode.Formulas.Specs("parameters-basic"); }

  <code>prefill:showAdvanced=true</code>:
  @Kit.Toolbar.Empty().New("FormulasParameters",
    ui: Sys.SourceCode.Formulas.Icon(),
    prefill: "showAdvanced=true"
  ).AsTag()
  <br>
  <code>prefill:showAdvanced=false</code>:
  @Kit.Toolbar.Empty().New("FormulasParameters",
    ui: Sys.SourceCode.Formulas.Icon(),
    prefill: "showAdvanced=false"
  ).AsTag()

  <p>
    <code>showAdvanced</code> is a parameter, that was passed with the toolbar prefill.
    This formula determines the visibility of the Advanced Settings group.
    The group becomes visible, when the passed <code>showAdvanced</code> parameter is true.
    <br>
    <em>Click on the (Σ) button above to see the edit-UI with the formula based on the passed prefill parameter. </em>
  </p>







@* Footer *@
@Html.Partial("../Shared/Layout/FooterWithSource.cshtml", new { Sys = Sys })
              An error has occurred. This application may no longer respond until reloaded. Reload 🗙