tame/core/ui.xml

163 lines
5.1 KiB
XML
Raw Normal View History

<?xml version="1.0"?>
<!--
2020-03-06 11:05:18 -05:00
Copyright (C) 2014-2020 Ryan Specialty Group, 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>