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:
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.