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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<TITLE>Getting Started.</TITLE>
</HEAD>
<BODY text="#000000" bgcolor="#ffffff">
<A HREF="tutorial.html"><EM> Entity Introduction </EM></A>
<b>:</b> <EM>Getting Started.</EM><BR>
<b>Previous:</b> <A HREF="tutorial4.html"><EM>Data Structures</EM></A><BR>
<b>Next:</b> <A HREF="tutorial6.html"><EM>A More complex Application</EM></A>
<HR NOSHADE>
<H2><A NAME="5"></A>5. Getting Started.</H2>
<p>Now that we have an understanding of XML, and a general idea of how Entity
itself works, we'll show you how to create and run simple program.</p>
<p>Running entity Programs</p>
<p>Entity works like a scripting languages in how it loads up its applications.
The command:</p>
<p>$ entity file.e</p>
<p>will load up file.e (which contains an application marked up in
XML), and begin interpreting it. </p>
<p>Alternatively you can use what is called the 'shebang' method, in
which you make the first line of the file:</p>
<p>#!/path/to/entity</p>
<p>or</p>
<p>#!/usr/bin/env entity</p>
<p>and set the file's permissions to include execution. This allows you
to run it as an interpreted file directly, without having to call
entity on it each time. The second method is preferred because it
will work as long as you have /usr/bin/env, and Entity is in your
path. Entity's XML parser knows to ignore shebang lines if they are
present.</p>
<p>A first Entity program</p>
<p>Our sample file looks like this:</p>
<p>
<blockquote><code>
<pre>
<object name="foo">
<window title="This app rules">
<button label="DO NOT CLICK ME"/>
</window>
<?perl
### This is where the code will go, when we write it later
?>
</object>
</pre>
</code></blockquote>
</p>
<p>When entity parses this, it builds a tree of ENodes that can be
represented like this:</p>
<p>
<blockquote><code>
<pre>
/object.foo
/window._123
/button._254
/perl._343
</pre>
</code></blockquote>
</p>
<p>The names "_123", "_254" and "_343" are just unique identifiers made
up by entity; they may be different from run to run.</p>
<p>This should be familiar to anyone who has seen a graphical directory
tree browser. We can see that we have a root, "/", which has a single
child, an object node called "foo". "foo" in turn has two children: a
window node with an arbitrary (but unique) name, and a perl node with
another arbitrary name. The window has one child: a button node with
an arbitrary name.</p>
<p>At parse time entity will construct the implementations of these
tags and keep them synchronized with your tree. In our example, a
window is made with title "This app rules", containing just a button
labelled "DO NOT CLICK ME". Also, the perl code is compiled and placed
in its own perl namespace. </p>
<p>As a consequence of these at-startup actions, syntax errors or
compilation errors in code elements will be flagged at startup. The
tree will still continue being built and the program will be run, but
the offending node will not be added to the tree.</p>
<p>Once entity has finished parsing the XML file and building the
in-memory objects, entity waits for events to happen - events being
anything the application listens to, from user actions to network
activity.</p>
<p>If the user clicks the button, entity looks to see if that button
wants to report the event to anyone. Since our example has no code,
nothing happens. Let's change that now.</p>
<p>Change your file to look like this:</p>
<p>
<blockquote><code>
<pre>
<object name="foo">
<window title="This app rules">
<button label="DO NOT CLICK ME" onclick="perl:clicked"/>
</window>
<?perl
sub clicked
{
$the_button = shift;
print "button $the_button was clicked\n";
}
?>
</object>
</pre>
</code></blockquote>
</p>
<p>So what's changed? We've added an attribute called "onclick" to our
button tag, with the value "perl:clicked". This means that when a
click event happens, entity looks in any perl nodes within the parent
object tag (this is one of the main roles of the object tag)
for a procedure called "clicked" and executes that. </p>
<p>We've also added some code in the perl node, a sub called "clicked"
that we've told the button to call on click events. This sub takes one
parameter: the node that was clicked. This is so you can use a single
handler for a number of events, which can often be a very elegant way
of doing things.</p>
<p>You will find that in many applications programmers will set the
"default-lang" attribute in the object node to specify what language
should be called when no language identifier is given. For example:</p>
<p>
<blockquote><code>
<pre>
<object default-lang="javascript">
<button onclick="some_javascript_function"/>
...
</object>
</pre>
</code></blockquote>
</p>
<p>Because of the 'default-lang="javascript"' attribute of this object, when
the button is clicked, entity assumes the onclick callback
"some_javascript_function" is in fact a javascript function. Entity will
search for this function in any javascript nodes within this object and
execute this function.</p>
<HR NOSHADE>
<A HREF="tutorial.html"><EM> Entity Introduction </EM></A>
<b>:</b> <EM>Getting Started.</EM><BR>
<b>Previous:</b> <A HREF="tutorial4.html"><EM>Data Structures</EM></A><BR>
<b>Next:</b> <A HREF="tutorial6.html"><EM>A More complex Application</EM></A>
</BODY>
</HTML>
|
