With sentences such as these
'...This tree structure and the relationships between the elements are described using a standard API called the Document Object Model or DOM, which is a W3C standard...'
'...Of course, you can do all of this using the standard DOM API, which is now implemented in all major modern browsers. The DOM API, however, is very verbose, and sometimes it takes quite a bit of code to accomplish what you want to do. JQuery solves this problem by providing a layer of API functions over the standard DOM that simplify a lot of common operations...'
I am led to believe that the DOM is a bit more than what I just typed into my text editor.
Please expound upon what is implied by the language being used in referring to the DOM as an API.
What you type into your text editor is marked up content. The markup uses a markup language like Hypertext Markup Language (HTML) or Extensible Markup Language (XML).
When this is served to a browser, it is parsed. This parsing converts the marked up content to an internal, tree structured, object graph, called a Document. The browser provides a collection of methods and properties through which this object graph can be read or manipulated. Although, each browser's internal object graph may be quite different from other browsers, the methods and properties are standardized. That is, each browser provides the same methods and properties regardless of its internal object graph.
These methods and properties collectively form an Application Programming Interface (API). It's possible for alternative collections of methods and properties to be defined to read and manipulate the object graph but the particular collection that JavaScript uses in browsers is called the Document Object Model (DOM).
Because the DOM API is the only collection of methods and properties natively available to JavaScript in browsers for manipulating the object graph, the distinction between this collection and the internal object graph that it accesses is normally not relevant, so the term "DOM" is often used as if it were the object graph itself.
Related
Sling provides a functionality to ease resource resolution. It's ability to resolve to exact resource representation we need is very useful in content based application.
However I am not able to understand one question is the use of suffix.
Example:
http://localhost:4502/content/app/mycomponent.large.html/something.html
Here, "something.html" is the suffix. I want to know under what circumstances would I go for a suffix ? What advantages do we get when compared to passing the information as a selector ?
Pretty hard question, but I will try to clear up it a bit.
According to best practices, selectors should not be treated as input parameters in functions. It means, that you should use selectors only for registering servlets (or JSP file names) and selectors should notify sling about the operation you want to do with given resource or the way it should be displayed.
For example, let's imagine, that you have page /page/a.html and you have some special representation for mobile devices. Then, accessing it with /page/a.mobile.html will open this page in a mobile friendly way.
On the other hand, suffix usually used to provide additional information to your servlet/JSP page. Just check editor interface in TouchUI: the url looks like
localhost:4502/editor.html/content/pageYouEdit.html
So you always stays on the same page /editor.html, but suffix notifies Edit Interface which page to edit.
Also another example:
there is a nice library for include content dynamically - https://github.com/Cognifide/Sling-Dynamic-Include.
When it's configured for some component, then after the page is loaded, your component will be included with AJAX call, like this:
publish/pathToThePage/_jcr_content/pathToTheComponentNode.nocache.html//apps/pathToTheRenderer
In this example, you can see, that both selector and suffix is used. Selector tells, what is special about a representation of this component we need and suffix tells which component should render requested data.
It's used to provide different versions of a resource, which are cacheable. This plays nicely with the Apache HTTP module known as "Dispatcher" which Adobe architects will recommend in any AEM implementation.
http://me.com/page.html/todays_promotion <-- cacheable
http://me.com/page.html?todays_promotion <-- not cacheable
The second example there, with a request parameter, should be treated as a variable resource that could produce different results upon each request.
I'm writing scala-js frontend framework, the key feature of which is server-side rendering. The idea was that there are components that manipulate dom with document.createElement, element.appendChild and others. On the server I'd subclass HTMLDocument, Element and others, override their methods with server dom implementation that can be converted to plain string html. So I added scalajs-dom_sjs dependency to the server module and tried to do that. But HTMLDocument, Element and most likely other classes have calls to js.native inside their constructors which throw exceptions saying "use JVM version of the library". Which doesn't exist obviously. I could use the other way and implement my own dom library, but that is twice as much work, cause I'd have to implement it on server and client, while using the first approach I'd implement it only once on server.
So my question is: why is it forbidden to use scala-js library versions on server so strictly and is there a work around it?
The reason this is forbidden is that, as you noticed, the DOM API is full of js.natives. These classes are not implemented in Scala. They are part of the browser's DOM API, which does not have an equivalent on the JVM. You cannot use the types defined in scalajs-dom on the JVM and expect them to do anything useful. Where would the implementations of the methods come from?
You will indeed need to implement your own DOM-like library for the JVM side. If you do not want to "reimplement" it on the client side, you could reuse the org.scalajs.dom namespace for your classes, and give them exactly the same structure and types as in scalajs-dom (except they won't extend js.Any, obviously).
Note that this is semantically dubious. Types extending js.Any do not have the same semantics as normal Scala types. You might be able to come up with some "compatible enough" API for normal use, but it's still dubious.
Usually, to enable so-called isomorphic DOM manipulations on server and client, one would write a DOM-agnostic cross-compiling library. On the client side, it would offer a "rendering" function to actual DOM nodes; and on the server side, it would render to strings to be sent to the client in the HTML.
This is precisely what Scalatags does.
Background
I am developing my first webapi2 rest interface for some products/batches/packs etc. I read this excellent page on how to make a good rest api and i'm stuck on a few concepts and my googling skills have failed me.
I would like to give the developer the option to embed or sideload sub resources to prevent repeated api hits for child/sub-resource data (i.e return all packs with a batch). I would also like them to be able to specify which fields they would like to return.
I'm used to a normal MVC/WebApi style of creating a Method and its own or shared ViewModel and sending down that in its entirety. If I need to send less data I create a slimmer ViewModel.
Question
What return type do I put on the rest endpoint, is it just a JObject that I construct manually depending on what fields they've requested (and the developer has to rely on the documentation to figure out what it could return)?
Or do I create a fat view model and somehow mark the fields as optional with the ability for the JSON/XML converter to omit these fields if the value is null etc (but then how do I side-load sub-resources...)?
Thanks, Pete
I have decided to use OData v4 so that I can allow the client-app to decide on what and how to consume the data i'm exposing. It doesn't support sideloading (that i've discovered so far) but it allows me to embed, filter and slim down any models easily.
It appears most of the WebAPI examples are returning some models (either domain models or particular view models).
When using domain models, we actually request more data than needed in the view from ajax calls, and then build our view models using JavaScript (assuming we are building a web app).
I tried using different view models for each page (view), which allow me to reduce the network footprint and return only the fields in need. But in the ApiController I would have too many GET methods. And it is impossible for us to predict the future need and build an API returning all kinds of view models.
I would like to mimic the Facebook Graph API and build a uri like:
http://... api/games/333?fields=id, name, price, imageUrl
And our user should be able to update the record with only these few fields.
A detailed description can be found in a google code blog entry: Making APIs Faster: Introducing Partial Response and Partial Update.
Some other posts here suggest this is beyond the current ability of ASP.NET WebAPI. Will ServiceStack or some other package help us achieve the goal?
Try this project: https://github.com/AnthonyCarl/ServiceStack.PartialResponse for the partial response side of the question
ServiceStack.PartialResponse.ServiceModel
Google Style Partial
Responses for ServiceStack.Net. Currently only the following Content
types are supported:
application/json
application/jsv
text/html
application/xml is NOT currently supported.
I wanted to implement this as a ServiceStack IPlugin, but I was unable
to figure out how to get the access I needed to the response DTO for
my approach. Currently, this is implemented as an IRequestContext
extension.
Providing Field Selectors
Field Selectors can be passed using the header or query string. By
default field selectors are combined form both. Duplicate field
selectors are reduced. The field selector is applied to all entries in
a list if the selector refers to a list.
There are a couple of options to implementing partial updates in ServiceStack. See this question about implementing PATCH requests for an approach that uses a request DTO with nullable values, and the PopulateWithNonDefaultValues and similar extension methods in ServiceStack, to take a PATCH-style request where the client can send any subset of fields in the request body. If a given field is not present in the request body, then that property of your domain object will not be updated.
If you really need to use a query string to specify the subset of fields that should be updated, then you can still use the approach described above, but add some code that first nulls out any values in the incoming request DTO object that are not named in the query string. Then you can again use PopulateWithNonDefaultValues to copy the remaining values to the domain object.
Also, to comment on another part of your post that is closely related to the recommendations I just gave:
When using domain models, we actually request more data than needed in the view from ajax calls...
Here is where a message-based design is helpful: model your request/response messages as separate DTO classes, instead of reusing and exposing your internal domain model objects. Among over benefits, you'll eliminate the problem of exposing unnecessary fields in your request/response models. Message-based design is one of the core concepts that drives ServiceStack's implementation. You could, though, achieve similar results with Web API or MVC. I highly recommend reading this article that discusses how this design works in ServiceStack.
You can use OData Protocol,look this example.
It's can use key:$select,$expand,$filter for search,select some fileds.
Most important,the ASP.NET WEB API has a SDK for support this.
If I have a URL that represents a collection, is there a good way to describe filters?
e.g. http://example.com/comic_books?after=2001-01-01&before=2002-03-09
If I make these filters part of the service contract, aren't I violating the idea of hypermedia as the engine of application state?
Do I need to have another resource that links to my collection and describes the filters e.g. via an HTML form?
You can consider an HTML form as a URL template representing your resource and the filter, there's nothing wrong with that, we all do it every day (google.com?s=query). There are those that argue that you don't need a form to represent a URL template, that documentation alone is adequate, so for many the form itself is optional.
The hyper media aspect is mostly related to the presence of the links themselves. Documenting the service is not an "out of band" consideration. What you want though is to present the link options as part of the hyper media that the client can follow. The form can be nice, but it's not required. You can use (even require) the same link and query parameters for the filter without explicitly listing them as part of the payload.
Consider HAL as an alternative to HTML, and it has no concept of forms, yet is consider by many to be a fine hyper media compatible media type.