#854 Dom API cleanup

andy Mon 7 Dec 2009

Along side the Web refactor, we need to clean up the Dom pod as well. We didn't end up using this pod nearly as much as we originally expected, but it has some core APIs we need to enable FWT-based UIs, so I'd like to get it locked down.

Window

  • Move static methods to instance methods
  • Get the current instance with Window.cur
  • Add Window.onEvent hook
  • Add conveniences for events? onLoad, onHashChange, etc?

We need to flush out more of that API, but I'll tackle that after this round of changes. So the API would like this:

class Window
{
  static native Window cur()      // Get current Window instance
  native Void alert(Obj obj)      // Display modal message box
  native Uri uri()                // Get the Uri for this window
  native Void hyperlink(Uri uri)  // Hyperlink to the given Uri
  native Document doc()           // Get Document instance for this window
  native Void onEvent(Str type, Bool useCapture, |Event e| handler)   
}

Doc

  • Rename to Document
  • Move static methods to instance methods
  • Current instance available from Window.doc

Otherwise I think this API is ok:

class Document
{
  native Elem body()         // Get the body element
  native Elem? elem(Str id)  // Get the element with this 'id'
  native Elem createElem(Str tagName, [Str:Str]? attrib := null)
  Str:Str cookies()          // Map of cookie values keyed by cookie name
  Void addCookie(Cookie c)   // Add a cookie to this session.
}

Elem

  • Use Elem.value for all form element values; Remove Elem.checked
  • Create Style class for Elem.style/computedStyle
  • Add conveniences for events? onMouseDown, onBlur, etc?
  • Remove Elem.effect (see below)

Rest of that API seems fine. There is definietly some overlap here with xml::XElem, but haven't given this one too much thought yet. Elem seems like it should be serializable. But does it extend XElem? That would require XElem to be compiled to JavaScript.

Effect

This API was never really used, and is a bit half-baked. So I think we're better off removing it, at least for now. And I think I'd like to see it implemented with something like Emile vs rolling our own animation engine.

HttpReq/HttpRes

We talked about modeling this using the web::WebClient API - but I don't think thats really feasible using XmlHttpRequest. A WebSocket backed API is probably better suited for that. However, I do think we could clean up this guy:

  • HttpReq: Move headers/async into ctor
  • HttpReq: Move method into send; provide conv for get,post,postForm
  • HttpRes: Use InStream for content

New API:

class HttpReq
{
  new make(Uri uri, Str:Str headers := Str:Str[:], Bool async := true)
  native Void send(Str method, Str content, |HttpRes res| c)
  native Void get(|HttpRes res| c)
  native Void post(Str content, |HttpRes res| c)
  native Void postForm(Str:Str map, |HttpRes res| c)   
}

class HttRes
{
  Int status       // the response status code
  Str:Str headers  // the response headers.
  InStream in      // the content of the response
}

What does everyone think about those changes? Anything you think is missing?

brian Mon 7 Dec 2009

Overall sounds good, couple things:

Use Elem.value for all form element values

That should be Elem.val - convention is always val over value. All of the xml APIs use val.

HttpReq: Move headers/async into ctor

This seems inconsistent with our typical patterns and with WebClient. I think it should be a field which may be set via at it-block.

But does it extend XElem? That would require XElem to be compiled to JavaScript.

I think this is a huge issue that needs to be solved before 1.0. If I write non-browser code that works with XML, that API is xml. However that code is not portable to the browser which currently has an entirely different set of APIs for working with XML. What is even worse is that Elem doesn't actually use the same slot names as XElem todays which means even duck typing won't work. I think the right solution is to have dom depend on xml, and use/extend those APIs.

tactics Tue 8 Dec 2009

Shouldn't we keep consistency between dom::Doc, fandoc::Doc, fluxText::Doc, and xml::XDoc?

andy Tue 8 Dec 2009

Shouldn't we keep consistency between dom::Doc, fandoc::Doc, fluxText::Doc, and xml::XDoc

Yeah probably, but I don't like having Window and Doc - so maybe it should be Win. I think they should both be abbreviated or not (and I guess throw Elem in there too).

That should be Elem.val - convention is always val over value

Agreed.

This seems inconsistent with our typical patterns and with WebClient. I think it should be a field which may be set via at it-block

Agreed.

brian Tue 8 Dec 2009

We already fwt::Window - since both fwt and dom are used together, we should try to use something with no obvious conflicts. Win wouldn't conflict, but at the same time might be confusing what it means versus fwt::Window.

andy Wed 16 Dec 2009

Promoted to ticket #854 and assigned to andy

Ok, I'll plan on doing this as outlined below. I'll tackle the simple API changes first to clean up the code, then we can revisit the XElem vs Elem debate.

Win

  • Rename Window to Win
  • Move static methods to instance methods
  • Get the current instance with Win.cur
  • Add Win.onEvent hook

Doc

  • Move static methods to instance methods
  • Current instance available from Win.doc

Elem

  • Use Elem.val for all form element values; Remove Elem.checked
  • Remove Elem.style/computedStyle (todo: replace with Style type)
  • Remove Elem.effect

Effect

  • Remove this API

HttpReq/HttpRes

  • HttpReq: Move to it-block style ctor
  • HttpReq: Move method into send; provide conv for get,post,postForm
  • HttpRes: Replace Str content -> InStream in

Elem is going to need a bit of work, so I'll open a new topic to discuss how it should correctly map into the DOM, fit together with XElem, and handle the CSS DOM.

andy Fri 18 Dec 2009

Renamed from Dom Proposal to Dom API cleanup

andy Fri 18 Dec 2009

Ticket resolved in 1.0.48

Everything on this list has been fixed except:

  • Left Elem.checked - this actually can't be combined into val the way I intended
  • Left HttpReq.content - need to check in new compilerJs before I fix
  • Left out Win.onEvent - after looking at this I think we need to add an EventTarget API to model things a bit more cleanly. Will make a new proposal after I've looked at the DOM API on this some more.

As part of this cleanup, I also moved testWeb::DomTest into the dom pod, and removed the testWeb pod since it no longer served a purpose.

Login or Signup to reply.