Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 116 lines (82 sloc) 3.548 kb
f1ec9dc @dnewcome removed old readme file, added markdown elements to readme.md
dnewcome authored
1 # About
53e752b @dnewcome added README file'
dnewcome authored
2 Jath is a template language that lets you declaratively parse xml documents into
3 javascript objects using json markup and xpath selectors. The idea is to write
4 some json markup that looks like the object that you want to end up with, and then
5 add xpath selectors to tell jath where the data should come from.
6
a6f3c8e @dnewcome updated readme with a quick synopsis
dnewcome authored
7 # Synopsis
5ed4694 @dnewcome updated synopsis
dnewcome authored
8
79e8674 @dnewcome updated synopsis
dnewcome authored
9 **Turn:**
627d27a @dnewcome updated synopsis
dnewcome authored
10
53181c7 @dnewcome updated synopsis
dnewcome authored
11 <statuses userid="djn">
9e9283f @dnewcome updated synopsis
dnewcome authored
12 <status id="1">
13 <message>Hello</message>
14 </status>
15 <status id="3">
16 <message>Goodbye</message>
17 </status>
18 </statuses>
a6f3c8e @dnewcome updated readme with a quick synopsis
dnewcome authored
19
79e8674 @dnewcome updated synopsis
dnewcome authored
20 **into:**
be430f7 @dnewcome updated synopsis
dnewcome authored
21
8533f41 @dnewcome reformatted json output code snippet
dnewcome authored
22 [
23 { id: "1", message: "Hello" },
24 { id: "3", message: "Goodbye" }
25 ]
5ed4694 @dnewcome updated synopsis
dnewcome authored
26
79e8674 @dnewcome updated synopsis
dnewcome authored
27 **using:**
be430f7 @dnewcome updated synopsis
dnewcome authored
28
60d2ae2 @dnewcome updated synopsis
dnewcome authored
29 var xml = <your AJAXy call here>;
30 var template = { id: "@id", message: "message" };
31 var result = Jath.parse( template, xml );
a6f3c8e @dnewcome updated readme with a quick synopsis
dnewcome authored
32
33 Check out the samples.html for more examples.
34
f1ec9dc @dnewcome removed old readme file, added markdown elements to readme.md
dnewcome authored
35 # Example
7d7ae79 @dnewcome updates to readme file
dnewcome authored
36 Say we were parsing an xml stream of status updates from a service
53e752b @dnewcome added README file'
dnewcome authored
37 like Twitter. The data might look something like this:
38
444e673 @dnewcome updated synopsis
dnewcome authored
39 <statuses userid="djn">
40 <status id="1">
41 <message>Hello</message>
42 </status>
43 <status id="3">
44 <message>Goodbye</message>
45 </status>
46 <status id="5">
47 </status>
48 </statuses>
53e752b @dnewcome added README file'
dnewcome authored
49
7d7ae79 @dnewcome updates to readme file
dnewcome authored
50 We want to consume this data on the client in javascript. Let's start with
53e752b @dnewcome added README file'
dnewcome authored
51 a template that will create our status object. We want to have the id and the
52 message as attributes of the object, so we start like this:
53
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
54 var template = { id: "", message: "" };
53e752b @dnewcome added README file'
dnewcome authored
55
56 When jath processes a template, the field names 'id' and 'message' will be used
57 to hold the data in the resulting javascript objects. Now that we have described
58 the result format, we need to select where the data comes from. This is where the
59 xpath comes in. Relative to the <status> tag, the xpath selector for the id is
60
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
61 @id
53e752b @dnewcome added README file'
dnewcome authored
62
63 and the selector for the message is simply
64
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
65 message
53e752b @dnewcome added README file'
dnewcome authored
66
67 So, let's add that to the template:
68
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
69 var template = { id: "@id", message: "message" };
53e752b @dnewcome added README file'
dnewcome authored
70
71 We could tell jath to process this template as-is, but to be really useful to us
72 we want it to process all of the statuses and return them to us as an array. The
73 array template form in jath is an array literal with one small difference: the
74 first element of the array is the xpath selector that returns the collection that
75 the array will hold. The second element is the array item template. So to get
76 the statuses in our example we want to use an xpath selector like
77
4b38a39 @dnewcome changed readme to use markdown code blocks
dnewcome authored
78 `//status`
53e752b @dnewcome added README file'
dnewcome authored
79
80 Giving us a template in the form of
81
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
82 var template = [ "//status", { ... } ];
53e752b @dnewcome added README file'
dnewcome authored
83
84 We already know what our item template looks like, so let's insert into the array
85 template form:
86
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
87 var template = [ "//status", { id: "@id", message: "message" } ];
53e752b @dnewcome added README file'
dnewcome authored
88
89 Processing the template looks like this
90
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
91 Jath.parse( template, xml )
53e752b @dnewcome added README file'
dnewcome authored
92
93 where xml is an XML document as a Firefox XML DOM object. The resulting javascript
94 array, expressed in json, would look something like this:
95
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
96 var result = [ { id: "1", message: "Hello" }, { id: "3", message: "Goodbye" }, ... ];
53e752b @dnewcome added README file'
dnewcome authored
97
485503b @dnewcome updated synopsis
dnewcome authored
98 Jath does not support anything other than string data right now, hopefully
53e752b @dnewcome added README file'
dnewcome authored
99 that will change soon.
100
f1ec9dc @dnewcome removed old readme file, added markdown elements to readme.md
dnewcome authored
101 # Status:
485503b @dnewcome updated synopsis
dnewcome authored
102 This software is a proof of concept. There are cases that it cannot handle,
7d7ae79 @dnewcome updates to readme file
dnewcome authored
103 and isn't production-ready.
104
f1ec9dc @dnewcome removed old readme file, added markdown elements to readme.md
dnewcome authored
105 # Limitations:
53e752b @dnewcome added README file'
dnewcome authored
106 - Only supports Firefox
f6619e1 @dnewcome updated markdown of the readme file so that the xml would show up correc...
dnewcome authored
107 - No built-in support for xml namespaces. This can be worked around by using selectors
53e752b @dnewcome added README file'
dnewcome authored
108 in the form of:
109
38e9d99 @dnewcome changed readme to use block code snippets
dnewcome authored
110 [namespace-uri()='http://www.w3.org/1999/xhtml' and name()='p' and @id='_myid']
53e752b @dnewcome added README file'
dnewcome authored
111
112 see: https://developer.mozilla.org/en/Introduction_to_using_XPath_in_JavaScript
113
114 - No support for dates or numeric types
115 - No support for literal values in templates, ie all values in the template
116 name-value pairs are currently treated as xpath selectors.
Something went wrong with that request. Please try again.