tame/core/ui.xml

<?xml version="1.0"?>
<!--
  Copyright (C) 2014-2023 Ryan Specialty, LLC.

  This file is part of tame-core.

  tame-core is free software: you can redistribute it and/or modify it
  under the terms of the GNU General Public License as
  published by the Free Software Foundation, either version 3 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->
<package xmlns="http://www.lovullo.com/rater"
         xmlns:c="http://www.lovullo.com/calc"
         xmlns:t="http://www.lovullo.com/rater/apply-template"
         title="UI Integration">

  <import package="base" />

  <!-- contains template dependencies -->
  <import package="vector/cmatch" export="true" />


  This package provides elementary integration with the UI through
  mystical knowledge of the naming conventions that the compiler uses
  when generating the UI package.

  You should \emph{never} reference generated values yourself without
  an abstraction.


  <section title="Applicability">
    An object in the UI is considered to be \dfn{applicable} if the
    predicate defined by its {\tt @when} attribute matches.  These
    predicates are generated, and should not be referenced directly;
    instead, \ref{_match-ui-applicable_} should be used with the
    question id.

    The term ``applicable'' is used instead of ``visible'' because
    object can be hidden by other means; a predicate might be true
    while a field is actually hidden.  Further, a non-matching
    predicate inhibits other behavior, like running of assertions.

    Note that this template will only be useful with an object
    (question, display, static, etc) that has a predicate defined;
    otherwise, compilation will fail.

    <template name="_match-ui-applicable_"
              desc="Match whether a UI question is visible">
      <param name="@on@"  desc="Question id" />

      <param name="@value@" desc="Value to match">
        <text>TRUE</text>
      </param>

      <param name="@__vis_class@" desc="Generated visibility class name">
        <text>--vis-</text>
        <param-value name="@on@" dash="true" />
      </param>


      <t:match-class name="@__vis_class@" value="@value@" />
    </template>


    \ref{_match-ui-set_} determines whether a UI field has a truthful value,
      which is non-empty and non-zero.

    <template name="_match-ui-set_"
              desc="Match whether a UI question is set">
      <param name="@on@"  desc="Question id" />

      <param name="@value@" desc="Whether set">
        <text>TRUE</text>
      </param>

      <param name="@__set_class@" desc="Generated set class name">
        <text>--set-</text>
        <param-value name="@on@" dash="true" />
      </param>


      <all>
        <t:match-ui-applicable on="@on@" />
        <t:match-class name="@__set_class@" value="@value@" />
      </all>
    </template>


    The templates below are analogous to the generic match templates,
      but they translate \tt{@on@} to the question param
        and also check that the question is applicable (using
        \ref{_match-ui-applicable_}).

    <inline-template>
      <for-each>
        <set cmp="eq" />
        <set cmp="ne" />
        <set cmp="gt" />
        <set cmp="gte" />
        <set cmp="lt" />
        <set cmp="lte" />
      </for-each>

      <template name="_match-ui-{@cmp@}_"
                desc="Match UI value {@cmp@}">
        <param name="@on@" desc="Question id" />

        <!-- pick one -->
        <param name="@value@" desc="Match against variable" />

        <all>
          <t:match-ui-applicable on="@on@" />

          <match on="ui_q_{@on@}">
            <dyn-node name="c:{@cmp@}">
              <c:value-of name="@value@" />
            </dyn-node>
          </match>
        </all>
      </template>

      <template name="_match-extern-ui-{@cmp@}_"
                desc="Match UI value {@cmp@} - using externs">
        <param name="@on@" desc="Question id" />
        <param name="@value@" desc="Match against variable" />

        <param name="@__yields@" desc="Generated visibility yields name">
          <text>__isvis</text>
          <param-value name="@on@" rmunderscore="true" lower="true" />
        </param>

        <!-- TODO: this default is transitionary, since there's no
             meaningful default -->
        <param name="@vis-dim@" desc="Classification dimensions (default 2)">
          <text>2</text>
        </param>

        <extern name="ui_q_{@on@}" type="param" dtype="integer" dim="1" />
        <extern name="@__yields@" type="cgen" dtype="boolean" dim="@vis-dim@" />

        <all>
          <match on="@__yields@" />

          <match on="ui_q_{@on@}">
            <dyn-node name="c:{@cmp@}">
              <c:value-of name="@value@" />
            </dyn-node>
          </match>
        </all>
      </template>
    </inline-template>
  </section>
</package>