I am pleased and proud to announce E2's new better XML output. This increases our current set of XML ticker functionality, plus provides a better and cleaner set of XML (well formed, but not yet validating) displays for this site. This will eventually replace our current displaytype=xml output, but for a while the old tickers will be in place, and the old displaytype=xml interface will still be good (for how long remains to be seen of course).

In general these tickers and interfaces are to be treated as if they were in beta, as they still are. Interfaces are subject to change, so please consider any code of this nature "in beta". Interface changes will be mentioned here, but as time goes on, these interfaces will firm up. Please make your code flexible, as one of the large items that is subject to change is the interpositioning of elements within the XML tags, and new elements will be added (especially to the user element).

One requirement of all clients is to assume a server error on malformed elements. This is because of in case of an actual server error (yes, we all know how perfect our code runs and how infrequently one of the boxes does not run out of memory), the output will in fact be mangled. If you encounter a server error, please try to reload the page in a minor amount of time, and fire a decent user error off. This is a general limitation to ecore in the sense that this is only xml-ish behavior, and does not reflect any underlying changes to the core.

It should not matter which user the client uses. Preferably, we'd only like to have logged in users be able to really access the ticker and get at important information, but in reality, Guest User should have no problem accessing each node.

Document text (in large blocks), should always be encodeHTML'ed. Otherwise it will form badly formed output (see the link parsing section below). This is bad. Yes, you may have to go through the trouble of taking ampersands back to their normal form, and other escaped characters, but that should be doable without much trouble. The goal of this export was to create readable output that any parser on the street could read, so all the characters need to be escaped, no matter what.

The new basic interface is displaytype=xmltrue. This produces valid output for the following nodetypes:
  • user
  • writeup
  • e2node
Each of these provides a different set of functionality, but in general quite closely mimics the actual interface of Everything2. Many types of documents can not, and will not be supported. If you try to xmltrue a document that is not supported, you should be getting, at the very least, a "no valid conversion" document (info tags). This means that simply, you can't view it. You should always, whenever available, view nodes by node_id. This will give you a cleaner viewing style across E2. If you need to look up a node title, use the XML Search Interface. It's fast, and it's clean. It should work well for you (hopefully).

All nodes have a standard header. Writeup is an embedded type, even though it duplicates some information (rather than having to special case it in to a bunch of things, think of a writeup as an e2node with only one writeup in it. In a lot of ways, that's how it works on e2, and that's how the data stream works for code cleanliness. Each node should give you it's node_id, title, author name, author_id, nodetype, creatime, etc. The XML export is designed with the thought that you should not have to keep a large client side mapping of node_ids to names. That would be largely inefficient, so we provide you with that information whenever possible. If forced to make a choice between the two, we should always give you the node_ids (except in the case of something like Personal Nodelet where the strings are user editable, and have no bearing on what may or may not actually exist (anymore at least), in the database.
  • Standard header information is provided by xmlheader
  • Standard footer information is provided by xmlfooter (at this point, the xmlfooter output is really lame, but that's unimportant.
  • The generic xml request is handled in ecore by node xmltrue page
  • formxml handles the request type negotiation. This was chosen over an indivual displaypage for each type, as it would simplify the process for now. We might move over to such a system later, but it allows us a little more ease in making changes for the time being.


displaytype=xmltrue (user)
Currently, homenode exporting works fairly well. You get the userstrings, the document text (the homenode text), parsed correctly for the usertype, and the experience. Also you can view their bookmakrs if they have them available. The bookmarks use a standard link mechanism known as <e2link> This allows them to have a standard interface for things such as firmlinks, softlinks, and bookmarks. They contain the node_id and inside, for their #PCDATA, they have the title, again, saving you from the node_id => title mapping that we fear.

...in the future they might have user specific information per session, but that has yet to really be nailed down. The exact implementation details of a lot of that are still largely unavailable.
  • formxml_user is largely responsible for the generation of the user page.
  • displayUserText was modified to help with the output and removal of links. See link parsing below.


displaytype=xmltrue (e2node)
E2nodes export their firmlinks (as <e2link>'s), each writeup as an embedded object and then their softlinks. They also pose a suggestion, if there is also a user under the exact same title, the same as what they normally do now. The number of softlinks are correct and exact for the usertype. This is handled by the softlink htmlcode itself, and thus produces the same output (except not in tabular format). For more information on the writeup portion of it, see writeup below.
  • Softlinks are governed by an argument to that htmlcode, and return output if that argument is valid
  • xmlfirmlinks does the firmlinks and is largely very similar to:
  • xmlwriteup is the generic writeup display code


displaytype=xmltrue (writeup)
The writeup xmltrue display is largely similar to the e2node display, except that you only get one writeup for sure, and a lot of the information is duplicated. One thing that is added to the actual <writeup> tag is the voting information that you get if you either own the node, or have voted on it before. C! Information is not available yet, but has been bugged, and will be eventually added to this type. You get the writeup type information (as it could be non-standard, presumably). Softlinks and firmlinks should be exported per normal on a writeup.
  • xmlwriteup, as mentioned earlier, governs the generic writeup output
  • formxml_writeup does the combining, and largely only calls xmlwriteup for a good portion of it


Stopping of link parsing
In all three acceptable nodetypes, you can halt the processing of links by appending the following to the url: links_noparse=1; If you don't pass it one, then an "undocumented result happens". Just pass it one. Thanks. This is special cased in to each section and is not specific to any one thing. It will also affect your homenode if you do it there (not in an xml viewtype). This may even work on older exports, but this does not work on any of the tickers. Tickers are being generally overhauled as mentioned below.

The New Ticker type, and it's benefits
The old tickers were derived from nodes with the fullpage type. This still means that their links get parsed. This is largely bad because URLs don't really make any sense to XML clients and was producing, among other things, badly formed content. Therefore, we have created a new type ticker that does everything the previous one does, except parse links from the text field areas (we do encodeHTML them, but that's to be expected). Since hyperlinks depend per implementation, we don't need to force clients into writing a scrubber for the URLS. Also, we want to create the tickers, so that we are not based performance wise on their implementations of the tickers (IE, cached tickers), but please feel free to make your clients as kind as possible. There are currently three "tickers" available:



Random Nodes XML Ticker
The random nodes ticker works really similarly to the random nodes nodelet. You get 12 random nodes (and even a bit of wit), ever minute or so. It gets fed off a nodelet called Random Nodes XML Feed, so feel free to hit this nodelet as often as you like, it's quite cheap, I can assure you. It's also fine to hit from Guest User.

Scratch Pad XML Ticker
The scratch pad ticker merely dumps out the contents of your scratch pad, and whether it is public or private. It should return an empty pad if the user is guest user. It does not take any input for change (but might someday).

E2 XML Search Interface
This should be where your client spends a lot of it's time. It takes two parameters "keywords" and "typerestrict". These parameters take a keyword string (separated by spaces, exactly how you'd type it in to the search form, and a typerestrict parameter, which you'd pass it a string of which type to restrict against (user or e2node are really the only two sensible choices). If you do not pass a typerestrict parameter, the script will default to an e2node. It will return a large page or results, similar to the Findings: page on E2. Please do not search in the standard way for that node, but use this ticker to gather your intelligence about what's available for viewing in any client. It returns a list of <e2link>'s with titles and node_ids. If you pass it a typerestrict you can also do inexact searches on users. You will get only the type that you passed it in (this will be available inside the XML you get back.



This is still a work in progress, as largely most of these interfaces are finished or in beta quality. If you see any typos or things that could use to be clarified, please let me know. There are bugs listed offsite on the sourceforge page for the e2client project insanefuzzie is working on (and I am merely helping to port). Please check there before reporting a bug, but also feel free to suggest anything that might make usage of these interfaces easier. We plan on doing an all out schema for these interfaces, but vailidity is by far a low priority, as we are using all internal apps to parse them. Hopefully this will prove useful to client developers, and in turn, the general populace of E2.

**Note, I typed this all up, very very tired, so if the sentences don't make any sense, please let me know. This is a prelimiary document for this new feature.
This is a little complicated, if you spot any mistakes *please* /msg me.

Introduction

Many people have written little scripts and utilities designed to work on information from e2. At first, people extracted the information they required from the HTML you and me view every day on the site. However, this was buggy and required modifying for every theme, upon anyone changing the layout, etc. So along came the old XML tickers, still retrieved via HTTP, which you can find at the top of Everything Data Pages. And so did they provide the basic information we all love, and scripts and utilities such as the E2 Node Tracker and the Java Chatterbox used them. And also provided was the XML displaytype, which edev people could use to view their own nodes. And the magnificent nate made this buggy displaytype available to all to view e2nodes and others writeups, but it was buggy and exported minimal information. And so wasn't incredibly useful.

And so, the beloved JayBonci, after much prodding from me and my quest to write e2client, has developed a new set of XML tickers! They produce well-formed, valid XML, and replace the old tickers entirely, although they're still there for backwards compatibility. But you need not use them any longer! They have been cast off a cliff, impaled on rocks and left there to die, as they deserve! The new tickers export a lot more information, and have been designed so that, when correctly used, they add very little to server load. And displaytype=xml has also been replaced! We now have displaytype=xmltrue, which exports all available node information from a variety of nodetypes.

One requirement of all clients is to assume a server error on malformed elements. This is because of in case of an actual server error (yes, we all know how perfect our code runs and how infrequently one of the boxes does not run out of memory), the output will in fact be mangled. If you encounter a server error, please try to reload the page in a minor amount of time, and fire a decent user error off. This is a general limitation to ecore in the sense that this is only xml-ish behavior, and does not reflect any underlying changes to the core.

- jaybonci

Note that almost everything - node titles, document text, etc - is passed through the encodeHTML function before being output. This replaces < with &lt;, > with &gt;, & with &amp; and " with &quot;, which is obviously necessary for it to be valid XML (as, for instance, the HTML of very few writeups would turn out to validate as XML). So you'll probably want to reverse this before actually using the data.

Also note that you'll probably want to pass a login cookie along when you're requesting all this stuff! You can either construct it manually (it's a pretty simple structure, the password is just crypt()ed, with the first two characters of the username as the salt), extract it from an op=login, or extract it from a web browser's cookie.txt. :)

This writeup fully documents this new e2 XML functionality. I will be updating it as necessary as we update and add to the exports and/or tickers. If you'd like to discuss all this XML stuff, we have a usergroup - clientdev - for just that purpose! /msg N-Wing or JayBonci to be added. Alternatively, feel free to /msg me questions.

Node Exports

If you're in edev, you'll probably want to look at the code for this, which is in node xmltrue page. Called from this is the code for the header (xmlheader), the footer (xmlfooter) and the code to render the actual node (formxml, which just calls whichever one is appropriate for the node in question, see the links in the list below).

At present, we have exports for the following types of nodes (if you're in edev, you can view the code):

To retrieve the XML, simply add a displaytype parameter with a value of 'xmltrue' to the URL of your request. This would typically mean adding '&displaytype=xmltrue' onto the end.

So, for instance, if you were trying to retrieve the node Butterfinger McFlurry your URL might be http://www.everything2.com/?node=Butterfinger+McFlurry&displaytype=xmltrue. If you already had the node_id (which is 980113) and wanted to avoid the need for the server to look the name up, you might use http://www.everything2.com/?node_id=980113&displaytype=xmltrue.

But wait! If you're like me, you don't want the server to parse the links for you, you want them left in [link] form, with the square brackets. In that case, the 'links_noparse' parameter, which must have a value of '1' to work, comes to your rescue! So you'd request http://www.everything2.com/?node_id=980113&displaytype=xmltrue&links_noparse=1.

Okay, so, we've worked out where the code is and how to request the XML. Now you'll be wanting to know the format of the xml... well, here's an example.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node node_id="980113" createtime="2001-03-12 17:25:41" type_nodetype="116" 
 xmlns="http://www.everything2.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.everything2.com/?node_id=1259759">
<type>e2node</type>
<title>Butterfinger McFlurry</title>
<author user_id="381970">donfreenut</author>
node-specific data here
</node>

Okay. The first line is just a generic XML header, of course. You can ignore most of the parameters of the node tag for practical purposes; you'll probably just want the node_id and the createtime, both of which should be self-explanatory. The contents of the node tag are of course what is important: the type is the nodetype, the title is, well, the title and the author tag provides both the node_id and the name of the node creator.

The node-specific data is discussed in seperate sections, below.

Node Exports: e2node/writeup

The node exports for e2nodes and writeups are very similar, the main difference simply being that only one writeup is exported for a writeup node, whereas many are exported for an e2node.

Both e2nodes and writeups have 'softlinks' and 'firmlinks' tags. These contain of a set of e2link tags, which consist of a node_id parameter and the node name as the contents of the tag; for example: <e2link node_id="1353299">VDMSound</e2link>. The softlinks are exported in order, and the same number are exported as are available; so if you're not logged in you will recieve less.

e2nodes have a 'nodelock' tag, which, if non-empty, contains either the softlock text or text which states that the account being used is locked so it cannot create writeups. They also have a 'sametitles' tag, which can contain 'nodesuggest' tags. These tags have a 'type' parameter and contain an e2link tag pointing to the target node, in the same format as above. 'nodesuggest' tags representing users may also have a 'useralias' tag which means that the user is a chatterbox forward for another one - the aliased user is detailed in an e2link tag inside the 'useralias' one. An example of this is shown below.

<sametitles>
<nodesuggest type="user"><e2link node_id="1271581">sex</e2link>
<useralias><e2link node_id="1275765">nate</e2link></useralias></nodesuggest>
<nodesuggest type="room"><e2link node_id="1106905">Sex</e2link></nodesuggest>
</sametitles>

An individual writeup will just contain one writeup tag, whereas an e2node may contain zero, one or more writeup tags. The parameter 'no_doctext', if provided and set to 1, means that the contents of the 'doctext' tag will not be provided. An example of a writeup tag is shown below:

<writeup node_id="1186415" createtime="2001-10-25 10:05:30" type_nodetype="117" marked="0">
<parent><e2link node_id="77439">sex</e2link></parent><writeuptype>thing</writeuptype>
<cools>
<e2link node_id="397402">moJoe</e2link>
</cools>
<reputation up="24" down="3" cast="-1">21</reputation>

<title>sex (thing)</title>
<author user_id="1082371">Mikkel</author>
<doctext>&lt;p&gt;A [useful] little [program] from [Nullsoft] (developers of [Winamp]).&lt;/p&gt;

&lt;p&gt;[Available] from www.nullsoft.com/free/sex/&lt;/p&gt;</doctext>
</writeup>

The 'marked' parameter is normally 0, but is 1 if the writeup is in the node row weblog, normally known as being "marked for destruction". The 'parent' tag points to the parent e2node, and is only really useful in writeups. The 'reputation' tag only appears if you've voted on, or are the author of, the writeup in question. I'd hope the rest should be pretty obvious from the example.

Node Exports: user

This is pretty simple. I'm just going to give you an example and let you work it out from there. The parameter 'no_doctext', if provided and set to one, means that the contents of the 'doctext' tag are not exported, to save bandwidth if you don't need it. The 'image' tag is empty if the user has no homenode image. The 'cools' tag doesn't appear if the user hasn't cooled any writeups. Note that the creation time is exported in the node header, and hence is not duplicated here.

<doctext>Homenode text here</doctext>
<experience>1234</experience>
<lasttime>2002-09-01 11:04:55</lasttime>
<level value="3">3 (Acolyte)</level>
<writeups>80</writeups>
<image>images/userincoming/fuzzie.jpeg</image>
<lastnoded>
<e2link node_id="1353299">VDMSound</e2link>
</lastnoded>
<cools>12</cools>
<userstrings>
  <mission>Monkeys!</mission>
  <specialties>Soy!</specialties>
  <motto>Pants!</motto>
  <employment>Lesbians!</employment>
</userstrings>
<groupmembership>
<e2link node_id="838015">edev</e2link>
</groupmembership>
<bookmarks>
  <e2link node_id="1354310">Binary literals in C (thing)</e2link>
  <e2link node_id="1228978">Yay! We're doomed!</e2link>
</bookmarks>

Note that groupmembership only exports edev, gods and content editors, just as it is on homenodes. Why? Because those three groups are already loaded when we get to this point, as they're used by various other bits of the code on each page, which means no extra server load.

Node Exports: superdoc

Okay, this is icky. When a superdoc is requested, the code is run, and the results placed in a 'superdoctext' tag. You should be warned, however, that many superdocs manually generate URLs, and as such, links_noparse may not work.

There are two possible parameters which can be used here - if you want to use either of them, it's recommended that you pass them with every request, because you obviously usually don't have a way to work out whether a node is a superdoc or not before you request it. The parameters, both of which have to be set to '1' in order to work, are 'no_findings' and 'no_superdocs'. They both do the same thing, the first just for the Findings page and the second for all superdocs, which is to disable generation and output of the superdoctext tag. This reduces server load for those cases in which you don't want the pages - clients will probably just use no_findings, as they'll be using the Search Interface (below) for this purpose (for instance, when e2client retrieves the Findings superdoc, it automatically sends another request to the Search Interface, so it would be pointless to generate/download the superdoc text).

Node Exports: usergroup

Again, this one is just an example. The contents of the 'description' tag are not exported if the parameter 'no_descrip' (which must, as usual, be '1') is provided. The 'weblog' is used for such things as edevify! and clientify!, and is only exported if the logged-in user is a member of that usergroup.

<description>TEXT HERE</description>
<weblog>
<e2link node_id="1350387">On Making E2 Distributed (idea)</e2link>
<e2link node_id="1338222">edev: User Data (idea)</e2link>
<e2link node_id="1337951">edev: User Data (idea)</e2link>
<e2link node_id="1329316">Mozilla Everything2 Search Plugin (thing)</e2link>
</weblog>
<usergroup>
<e2link node_id="459692">JayBonci</e2link><e2link node_id="220">nate</e2link>
<e2link node_id="9484">dbrown</e2link><e2link node_id="2447">sgtbaker</e2link>
</usergroup>

Node Exports: room

If you hit a room node, you meet the entry criteria (eg, only gods are allowed to enter Valhalla, only M-Noders in The M-Noder Washroom, etc) and you're not Guest User, then you're moved into that room. The returned xml has a 'canenter' tag which is 0 if you didn't enter the room for some reason, or 1 if you did (the usual case if you're not a guest).

<canenter>1</cancenter>
<description>room description here</description>

Tickers

Tickers are special pages which provide XML information, mostly data required for rendering nodelets, but also other information such as user search and clientdev client data. They all being with a standard XML header tag (plus maybe an inline DTD or schema or whatever), and then are all pretty much unique.

You should request them based on their node_id. And you shouldn't hardcode these node_id's into your code, if at all possible, but should instead use the Interfaces Ticker which is documented below.

Note that you can't request these with the xmltrue displaytype, you'll just get the xml header for the nodetype 'ticker'. They must be requested with the default ('display') displaytype, which you can do by simply not including a displaytype parameter with your request.

For each ticker I've provided a paragraph of explanatory text, and then example 'real' ticker output. Note that in most cases I've stripped the output down to just two or three items where there are many, and that I've obviously modified some of them considerably. :)

Interfaces Ticker

XML Interfaces Ticker; interface "interfaces"

This ticker is also available via '/interfaces.xml', which is an apache alias for the node. Why? Because this ticker is a site-independent way to retrieve tickers. You simply retrieve the xml file, lookup the node_id of the ticker you want in it, and then request that node_id. You obviously should just request this once per session, or even just request it once and then cache it.

Since the server move, interfaces.xml has not worked, presumably due to the removal of the apache alias.

<xmlcaps>
<this node_id="1261407">XML Interfaces Ticker</this>
<xmlexport iface="rooms" node_id="1254496">Available Rooms XML Ticker</xmlexport>
<xmlexport iface="search" node_id="1252400">E2 XML Search Interface</xmlexport>
</xmlcaps>

Each ticker documented here has the interface name, as provided by the 'iface' tag of each 'xmlexport' tag here, provided. So in order to download a ticker, reference your interfaces list, find the required one, get the node_id, and then download it.

Client Version Ticker

Client Version XML Ticker; interface "clientversions"

See clientdev: Registering a client for information about client registration. This ticker simply exports the information about all registered clients, mainly so that clients can automatically detect when a new version is available and suggest upgrading to the user.

<clientregistry>
<client client_id="1262679" client_class="jchatter">
<version></version>
<homepage>http://sourceforge.net/projects/jchatter/</homepage>
<download>http://sourceforge.net/project/showfiles.php?group_id=4370</download>
<maintainer node_id="9740">N-Wing</maintainer></client>
<client client_id="1262284" client_class="e2client.kde">
<version>0.03alpha</version>
<homepage>http://sourceforge.net/projects/e2client/</homepage>
<download></download>
<maintainer node_id="1167948">fuzzie</maintainer>
</client>
</clientregistry>

New Writeups Ticker

New Writeups XML Ticker; interface "newwriteups"

An integer parameter 'count' defines the number of writeups to return. It defaults to 15, and has a maximum value of 300.

<newwriteups>
<wu wrtype="idea">
<e2link node_id="1355036">Pentium (idea)</e2link>
<author><e2link node_id="1350577">carlos_avdas</e2link></author>
<parent><e2link node_id="28647">Pentium</e2link></parent>
</wu>
</newwriteups>

Other Users Ticker

Other Users XML Ticker II; interface "otherusers"

A list of users logged onto e2. An optional parameter 'in_room', with a parameter of the node_id of the room in question, restricts the output to users in a certain room. A parameter 'nosort', if set to 1, means that the output is not sorted. Please enable this and sort client-side by the 'xp' parameter, in order to reduce server load.

<otherusers>
<user e2god="1" ce="0" edev="0" xp="36251" borged="0" >
<e2link node_id="898906">Gritchka</e2link>
</user>
<user e2god="1" ce="0" edev="1" xp="23896" borged="0" >
<e2link node_id="768243">Professor Pi</e2link>
</user>
<user e2god="0" ce="0" edev="1" xp="8136" borged="0" >
<e2link node_id="7515">xunker</e2link>
<room node_id="553146">Noders Nursery</room>
</user>
</otherusers>

Available Rooms Ticker

Available Rooms XML Ticker; interface "rooms"

A list of all the room nodes, along with a link to the go outside superdocnolinks.

<e2rooms>
<outside>
  <e2link node_id="1102338">go outside</e2link>
</outside>
<roomlist>
 <e2link node_id="1062657">&amp;gt;hug)))&amp;gt;</e2link>
 <e2link node_id="1159213">Fruan's Hidden Place</e2link>
 <e2link node_id="930643">Hammock Heaven</e2link>
 <e2link node_id="1243647">House of Cheese</e2link>
</roomlist>
</e2rooms>

Universal Message Ticker

Universal Message XML Ticker; interface "messages"

Okay, this can be used to retrieve two types of messages: chatterbox messages, and your message inbox. It takes a bunch of parameters:

  • 'msglimit', an integer parameter. This should contain the id last message you have stored locally; it will only return messages which are newer than this one. If not present, all messages are returned.
  • 'for_node', an integer/text parameter. This should contain the node_id of the room and/or user you wish to retrieve messages for. If you set it to 'me', it will return your own messages. It will not work for retrieving messages from any user except yourself, nor any room except the one you are in. If not present, messages from the 'outside' room in the chatterbox will be returned, which will NOT WORK unless you're in that room. If you're not logged in, ie logged in as Guest User, you can retrieve the contents any 'public' room (this is currently outside and political asylum only).
  • 'backtime', an integer parameter. This should contain either '5' or '10', depending on whether you want the last 5 or 10 minutes of chatterbox messages to be returned. This only works if requesting chatterbox messages (ie, from a room).
  • 'nosort', which should be set to '1' if you don't want the results to be sorted. Please enable this and sort messages by their ids client-side, to reduce server load.
  • 'links_noparse', which, as with the xmltrue stuff, stops links from being transformed into <a> tags.

The first example is from the chatterbox.

<messages>
<room room_id="0">outside</room>
<topic>There's a progress we have found, a way to talk around the problem.</topic>

<msglist>

<msg msg_id="5254722" msg_time="20020901131007">
<from><e2link node_id="5404">Byzantine</e2link></from>
<txt>er, pass off, even</txt>
</msg>

<msg msg_id="5254724" msg_time="20020901131108">
<from><e2link node_id="974148">ascorbic</e2link></from>
<txt>Well, wertperch has a quote from bones on his h/n &quot;Unattributed c/p is plagiarism and
plagiarism goes, period.&quot;</txt>
</msg>

</msglist>
</messages>

And another one from my Message Inbox.

<messages>
<msglist>
<msg msg_id="5251400" msg_time="20020831181554">
<from><e2link node_id="1167948">fuzzie</e2link></from>
<grp><e2link node_id="1199641">clientdev</e2link></grp>
<txt>Jay/someone, could you add xmltrue support for rooms please? :-)</txt>
</msg>
</msglist>
</messages>

Personal Session Ticker

Personal Session XML Ticker; interface "session"

This ticker updates your session, and displays useful data like your personal nodelet, the votes/cools you have left, the amount of karma (Golden Trinkets) you have, and updates/displays your borg status. IN ORDER TO BE UNBORGED, YOU MUST EITHER REQUEST THIS TICKER OR CAUSE THE EPICENTER TO BE DISPLAYED (typically by downloading a normal (ie, web-based) e2 page). The 'forbiddance' character displays a userlock, which is the text displayed like a softlock if your entire account is stopped from posting writeups. The 'xpinfo' section only appears if your numwriteups or XP has changed since this ticker and/or the Epicenter were last executed. Note that if you're not logged in, only the 'currentuser' and 'servertime' tags are produced.

I made up a lot of the numbers in this example.

<e2session>
<currentuser user_id="1167948">fuzzie</currentuser>
<servertime time="1030887589">Sun Sep  1 13:39:49 2002</servertime>
<borgstatus value="0">unborged</borgstatus>
<personalnodes></personalnodes>
<cools>0</cools>
<votesleft>7</votesleft>
<karma>8</karma>
<experience>1203</experience>
<numwriteups>83</numwriteups>
<forbiddance></forbiddance>
<xpinfo>
 <xpchange value="1">1203</xpchange>
 <nextlevel experience="50000" writeups="999">4</nextlevel>
</xpinfo>
</e2session>

Random Nodes Ticker

Random Nodes XML Ticker; interface "random"

The Random Nodes nodelet, but an XML version! Along with that randomish witty phrase you've grown to love. You get 12 of them each time it's refreshed (every minute or so), and JayBonci says "It gets fed off a nodelet called Random Nodes XML Feed, so feel free to hit this nodelet as often as you like, it's quite cheap, I can assure you. It's also fine to hit from Guest User".

<randomnodes>

<wit>Just another sprinking of indeterminacy</wit>
<e2link node_id="408940">Oulu</e2link>
<e2link node_id="226765">Doughfaceism</e2link>
</randomnodes>

Search Interface

E2 XML Search Interface; interface "search"

A tool for searching the site using keywords, just like the search textbox at the top of all e2 pages. Pass a parameter 'keywords' with your keywords and a parameter 'typerestrict' with the type of node you want returned (probably the default which is used if you don't provide a 'typerestrict' parameter at all - 'e2node').

<searchinterface>
<searchinfo>
 <keywords>rabbit</keywords>
<search_nodetype node_id="116">e2node</search_nodetype>
</searchinfo>

<searchresults>
 <e2link node_id="1239286">Flemish Giant Rabbit</e2link>
 <e2link node_id="1228072">cutaneous rabbit</e2link>
</searchresults>
</searchinterface>

Maintenance Nodes Ticker

Maintenance Nodes XML Ticker; interface "maintenance"

Returns the contents of the boring heaven nodes setting. Used for working out which e2nodes should have writeups be hidden by default, and that's it, basically.

<maintenance>
<e2link node_id="174079">Edit these E2 titles</e2link>
<e2link node_id="171917">E2 Nuke Request</e2link>
</maintenance>

Scratch Pad Ticker

Scratch Pad XML Ticker; interface "scratch"

Returns a scratchpad, by default yours, however you can provide a 'scratch' parameter, which consists of the node_id of the user whose scratchpad you wish to view. You cannot view it unless the user has set it as shared, and you cannot view it if you're not logged in. You can also pass 'links_noparse', as with the xmltrue interfaces.

<scratchpad>
<scratchtxt user="fuzzie" public="1">text</scratchtxt>
</scratchpad>

Cool Nodes Ticker

Cool Nodes XML Ticker II; interface "coolnodes"

Returns a list of cooled writeups, with optional parameters as listed below.

  • 'writtenby', an integer parameter, containing the node_id of the user whose cooled writeups you wish to view. If not provided, displays cooled writeups by all users.
  • 'cooledby', an integer parameter, containing the node_id of the user who cooled the writeups you wish to view. If not provided, displays writeups who were cooled by any user.
  • 'limit', an integer parameter with a default and maximum value of 50, which specifies the number of writeups to list.
  • 'startat', an integer parameter, which contains the location in the list you wish to start the list at, commonly used when paging through a large list (as a list of cooled writeups is likely to be). So, for instance, you'd retrieve the second page with 'startat=50', assuming you retrieved the first with 'limit=50'.
<coolwriteups>
<cool>
<writeup><e2link node_id="1355024">Lupe Velez (person)</e2link></writeup>
<author><e2link node_id="1177778">vixen</e2link></author>
<cooledby><e2link node_id="898906">Gritchka</e2link></cooledby>
</cool>
<cool>
<writeup><e2link node_id="1355024">Lupe Velez (person)</e2link></writeup>
<author><e2link node_id="1177778">vixen</e2link></author>
<cooledby><e2link node_id="8933">Lord Brawl</e2link></cooledby>
</cool>
</coolwriteups>

Editor Cools Ticker

Editor Cools XML Ticker; interface "edcools"

Editor Cools, otherwise known as 'Endorsements'. One integer parameter, 'count', which defaults to 10 and has a maximum value of 50, which specifies the number of writeups to return. Sorted by time of endorsement.

<editorcools>
<edselection>
 <endorsed node_id="949709">fuzzy and blue</endorsed>
 <e2link node_id="1028921">I am three, she said</e2link>
</edselection>
<edselection>
 <endorsed node_id="780564">WonkoDSane</endorsed>
 <e2link node_id="576555">How to cook rice</e2link>
</edselection>
</editorcools>

Everything's Best Users Ticker

Everything's Best Users XML Ticker; interface "bestusers"

The XML equivalent of the Everything's Best Users superdoc, along with a shiny 'ebu_noadmins' parameter, which, if set to 1, doesn't include gods, and if not set or set to anything else, does include gods.

<EBU ebu_noadmins="0">
<bestuser>
 <experience>78790</experience> <writeups>1924</writeups>
 <e2link node_id="2654">Segnbora-t</e2link>
 <level value="11">11 (Godhead)</level>
</bestuser>
<bestuser>
 <experience>57476</experience> <writeups>4235</writeups>
 <e2link node_id="4586">Pseudo_Intellectual</e2link>
 <level value="12">12 (Pseudo_God)</level>
</bestuser>
</EBU>

Node Heaven Ticker

Node Heaven XML Ticker; interface "heaven"

Retrieves the contents of your Node Heaven. An optional parameter, 'visitnode_id', means that the only writeup displayed is the one matching that node_id, if one exists, and that the contents of that writeup are also provided. The writeups are sorted by title unless the 'nosort' parameter is set to '1'. 'links_noparse' is also supported, and works the same as it usually does.

<nodeheaven>
<nodeangel node_id="1231188" title="Apogee Software (thing)" reputation="8" 
createtime="2002-01-09 00:26:30">writeup text here. delete all my nodes. etc.</nodeangel>

User Search Ticker

User Search XML Ticker II; interface "usersearch"

The equivalent of User Search, but in XML form! Supports the following truly amazing parameters:

  • 'searchuser', the username to display the writeups of. If the user doesn't exist or this parameter isn't provided, it defaults to the logged-in user.
  • 'startat', for use when paging through the list bit-by-bit: defines where in the list of writeups to start output.
  • 'count', which defines the amount of writeups to output at a time, with a default value of 50.
  • 'nolimit', which, if set to '1', means that 'startat' and 'count' are disregarded and all writeups written by this user are displayed. Obviously, try to avoid using this, it involves quite a lot of work server-side.
  • 'nosort', which, as ever, should be set to '1' to disable sorting and hence reduce server load. DO IT CLIENT-SIDE!
  • 'sort', which has three possible values: 'rep', which sorts by reputation, 'title', which sorts by title, and 'creation', which sorts by creation time. Obviously this doesn't work with nosort.
<usersearch user="fuzzie">
<wu createtime="2002-08-29 10:56:05" marked="0" hidden="0" cools="0" wrtype="">
<rep up="8" down="1">7</rep>
<e2link node_id="1353814">VDMSound (thing)</e2link>
<parent><e2link node_id="1353299">VDMSound</e2link></parent>
</wu>
<wu createtime="2002-08-26 07:06:03" marked="0" hidden="0" cools="0" wrtype="">
<rep up="12" down="0">12</rep>
<e2link node_id="1352546">Visual J++ (thing)</e2link>
<parent><e2link node_id="973217">Visual J++</e2link></parent>
</wu>
</usersearch>

Raw VARS Ticker

Raw VARS XML Ticker; interface "vars"

Exports the contents of the $VARS variables you're allowed to change, doesn't work for Guest User.

<vars>
<key name="topicCbox">1</key>
<key name="noTypoCheck">1</key>
<key name="powersChatter">1</key>
</vars>

Time Since Ticker

Time Since XML Ticker; interface "timesince"

Returns the time since a set of users were seen. Pass it either the parameter 'user', with a comma-delineated list of usernames (eg 'user=JayBonci,TheBooBooKitty,nate') or the parameter 'user_id', with a comma-delineated list of user_ids (eg 'user=4653, 452753, 296735'). If you don't pass it either of these parameters, it details to returning information about the logged-in user. ascorbic notes that it's also quite useful for matching usernames with user_ids...

<timesince>
<now>2002-10-18 12:59:42</now>
<lasttimes>
<user lasttime="2002-10-17 12:20:07">
<e2link node_id="459692">JayBonci</e2link>
</user>
<user lasttime="2002-10-17 12:55:36">
<e2link node_id="1019201">TheBooBooKitty</e2link>
</user>
<user lasttime="2002-10-16 22:01:33">
<e2link node_id="220">nate</e2link>
</user>
</lasttimes>
</timesince>

Log in or register to write something here or to contact authors.