Usage of "document" vs. "page" in APIs and configuration

Development
#1

Hi devs,

We don’t have any clear rules about using “document” vs. “page” when naming APIs and configuration properties. While implementing https://jira.xwiki.org/browse/XWIKI-17447 I realized that I could use either of:

$services.edit.document.inplaceEditingEnabled()
$services.edit.page.inplaceEditingEnabled()

Same for the configuration property itself:

edit.document.inplaceEditing.enabled = true
edit.page.inplaceEditing.enabled = true

I know we agreed at some point to use “page” in the UI, when “talking” to the user, but I don’t recall any decision about the API / configuration level.

First of all, do you see any conceptual difference between page and document? Now that we have page references, for me a document and a page represents the same concept in the XWiki model.

If both represent the same concept, then which term do we deprecate on the long term? “document”?

If they are different concepts, then I guess we’ll keep them both on the long term, but then when do we use one versus the other? And don’t you find this confusing for the user / developer? They have to understand 2 concepts that are very close.

My view is that at the level of XWiki model they represent the same concept and that on the long term we’ll move away from document to page. Do you share the same view?

WDYT?

Thanks,
Marius

#2

Pretty much. The concept is the same yes, the difference is on implementation side but right now “document” is still very visible since pages are based on documents (i.e. there is no page store or any kind of POJO for page entities yet, only documents).

#3

Definitely confusing to have both concepts in the code :slight_smile:
Broadly speaking I would prefer using Document over Page for XWiki since for me “Page” refers to a piece of a Document, as in pagination.

Quite frankly I don’t recall having used a PageReference and reading the Javadoc it really looks like some internal syntaxic sugar to help dealing with Nested Documents/Pages.

All in all I have the feeling that it would be more difficult to replace everywhere the API that uses “Document”, over getting rid of “Pages” API or only keeping them for very specific stuff.

Now I agree that it might be a problem to not have the same terminology in UI and in code…

#4

Not sure about this. We discussed it in the past and I remember that in the discussion this came up:

  • Page = web page = the whole HTML representation incluiding skin
  • Document = just the holder of the content (metadata + main content)

So with this definition a Page is made up of a Document + other things (Skin + Document rendered to HTML).

Sergiu defined it as:

  • Page is Visual.
  • Document is Data.

Found this:

Now this is old and we introduced the changes in the UI after this I think.

Page can also be confusing at the developer level because when you talk about it, do you mean the web page or the document metadata. Also, I’m not sure we’ll be able to change the document concept in xwiki; it seems the effort might be too big to do this.

Maybe we should keep “document” at api level when we’re talking about the data and “page” when we’re talking about the visual representation.

Then the only question is referencing a document. Do we use DocumentReference or PageReference. Ideally we should keep using DocumentReference but it has the “WebHome” issue. We named the new solution PageReference for lack of a better word (document was used already).

I’m not sure… just thoughts.

There’s also https://design.xwiki.org/xwiki/bin/view/Proposal/DeprecatingSpaceAndSpaceReference