content
content copied to clipboard
mdn
Issue with "History API": Documentation more concerned with adding to history and changing the present instead actually working with history
MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/History_API
What information was incorrect, unhelpful, or incomplete?
This should document working with the history but it really only scratches the top of the iceberg and seems to be more concerned with the current state than the window history actually. E.g. if I want to replace the last URL - that the back button would point to, that is not answered. If I want to change or remove any other entry in the stack of url in the history, that is also not really considered.
Specific section or headline?
Not really, the whole article isn't as useful as it could be.
What did you expect to see?
E.g. mentioning
window.addEventListener('popstate', function(event) {
window.location.assign("http://example.com/");
});
from https://stackoverflow.com/questions/30526811/change-the-back-button-url-in-browser which actually works.
Did you test this? If so, how?
This simply changes, what the back button points to when it is clicked. This is something I would consider relevant to "history" in the browser.
MDN Content page report details
- Folder:
en-us/web/api/history_api - MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/History_API
- GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/history_api/index.html
- Last commit: https://github.com/mdn/content/commit/dc9089417852530f233c345bd6821d6e06f11b1e
- Document last modified: 2020-12-18T10:05:08.000Z
Can you submit a PR?
I am not sure, I have the needed insight - otherwise I wouldn't search for documentation. I sketched up what, in my opinion, needs to be changed to make the documentation more useful. Perhaps the original author will recognize this point of view?
Hi @KaliszAd are your use cases explained better here https://developer.mozilla.org/en-US/docs/Web/API/History_API/Working_with_the_History_API ?
Hi @KaliszAd are your use cases explained better here https://developer.mozilla.org/en-US/docs/Web/API/History_API/Working_with_the_History_API ?
I have read the current documentation. The problem really seems to be, the API is named "history" but really it changes the present as I have written. (E.g. you cannot really rewrite the whole history, you cannot get an entry before the most recent one without resorting to hacks - if there are any. Either way, nothing of this is written in the documentation. I understand the potential security implications/ considerations but they aren't written down in the documentation.) You can do some things, that approach working with actual history - e.g. changing what the history button will go to or working with event listeners (popstate) as I have shown. The section on popstate is very terse even though it seems to be rather useful for hacking around some of the deficiencies of the API.
I think that's because popstate is linked to elsewhere - maybe we update that section to be more informative?
It has been 3 years and no action is taken. I think we should close this because the docs are not wrong here. You should understand what an API does by looking at the methods it offers, not by its name. It's weird for MDN to document what an API doesn't do.
It has been 3 years and no action is taken. I think we should close this because the docs are not wrong here. You should understand what an API does by looking at the methods it offers, not by its name. It's weird for MDN to document what an API doesn't do.
Well, in that case, you could name APIs just with UUIDs or something, if the name does not/ should not convey meaning, right? I think, a clarification that the naming perhaps isn't ideal but is left as-is for legacy/ compatibility reasons is helpful to people that only need it occasionally and don't want to consult SO/ AI about what the API can or cannot do.
We don't decide what APIs are named or what they can/should do. We can only document what they actually do.