Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
blob: 7b95dde2775d78c3c0a9592b6cc285e8015c650b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
<?xml version="1.0"?>
<!--
  Copyright (C) 2014-2019 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>
    </inline-template>
  </section>
</package>