{"id":15313995,"url":"https://github.com/vanruesc/stay","last_synced_at":"2025-10-08T23:32:18.113Z","repository":{"id":57170327,"uuid":"37808078","full_name":"vanruesc/stay","owner":"vanruesc","description":"A slim and effective module for the creation of dynamic xhr-driven web applications.","archived":true,"fork":false,"pushed_at":"2015-12-05T21:00:43.000Z","size":241,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-16T07:10:56.437Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanruesc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-21T12:28:37.000Z","updated_at":"2023-01-28T20:36:45.000Z","dependencies_parsed_at":"2022-08-27T12:01:51.106Z","dependency_job_id":null,"html_url":"https://github.com/vanruesc/stay","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanruesc%2Fstay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanruesc%2Fstay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanruesc%2Fstay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanruesc%2Fstay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanruesc","download_url":"https://codeload.github.com/vanruesc/stay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235775518,"owners_count":19043180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T08:44:04.505Z","updated_at":"2025-10-08T23:32:12.760Z","avatar_url":"https://github.com/vanruesc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stay \n[![Build status](https://travis-ci.org/vanruesc/stay.svg?branch=master)](https://travis-ci.org/vanruesc/stay) \n[![Windows build status](https://ci.appveyor.com/api/projects/status/7ojob52ctrwywgib?svg=true)](https://ci.appveyor.com/project/vanruesc/stay) \n[![GitHub version](https://badge.fury.io/gh/vanruesc%2Fstay.svg)](http://badge.fury.io/gh/vanruesc%2Fstay) \n[![npm version](https://badge.fury.io/js/%40vanruesc%2Fstay.svg)](http://badge.fury.io/js/%40vanruesc%2Fstay) \n[![Dependencies](https://david-dm.org/vanruesc/stay.svg?branch=master)](https://david-dm.org/vanruesc/stay)\n\nStay is a slim and effective module for the creation of dynamic xhr-driven web applications. \nIt expects the server to be able to send a page's content as a simple JSON string in which the key names \ncorrespond with the IDs of the target DOM containers.\n\n\n## Installation\n\nDownload the [minified library](http://vanruesc.github.io/stay/build/stay.min.js) and include it in your project:\n\n```html\n\u003cscript src=\"/js/stay.min.js\"\u003e\u003c/script\u003e\n```\n\nYou can also install this module from [npm](https://www.npmjs.com).\n\n```sh\n$ npm install @vanruesc/stay\n``` \n\n\n## Usage\n\n### The client part\n\nCreating an instance of Stay usually suffices. \n\n```javascript\nimport Stay from \"@vanruesc/stay\";\n\nvar stay;\n\ntry {\n\n    stay = new Stay();\n\n} catch(error) {\n\n    // XHR not supported.\n    console.warn(error);\n\n}\n```\n\nYou may also configure Stay's behaviour and take full control of the navigation flow.\n\n```javascript\nimport Stay from \"@vanruesc/stay\";\n\nvar stay;\n\ntry {\n\n    stay = new Stay({\n\n\t    // Logs to console by default\n\t    stderr: \"myDomElement\",\n\n    \t// Default is \"/json\"\n    \tinfix: \"/asyncRequests\",\n\n\t    // Default is 60000ms, 0 means no timeout\n    \ttimeoutPost: 0,\n\n    \t// Default is 5000ms\n    \ttimeoutGet: 0,\n\n\t    // Default is true\n    \tautoUpdate: false\n\n    });\n\n    stay.addEventListener(\"navigate\", function() {\n\n    \tconsole.log(\"Page navigation has started.\");\n        startMyFancyLoadingAnimation();\n\n    });\n\n    stay.addEventListener(\"receive\", function(event) {\n\n        maybeDoSomethingWithThe(event.response);\n\n    \t/* If autoUpdate is disabled, the programmer has to decide \n\t     * when to update the page content. The update() method MUST \n    \t * be called at some point to unlock the system!\n    \t *\n    \t * This event will always be dispatched. See the docs for \n    \t * payload information if you intend to process the server \n    \t * response.\n    \t *\n    \t * Please note: do not make your users wait artificially!\n\t     */\n\n    \tstay.update(event.response);\n\n    });\n\n    stay.addEventListener(\"load\", function() {\n\n        stopMyFancyLoadingAnimation();\n    \tconsole.log(\"The requested page has been loaded.\");\n\n    });\n\n} catch(error) {\n\n    console.warn(error);\n\n}\n```\n\n### The server part\n\n\u003e Every GET and POST endpoint needs to be available as a condensed JSON resource. \n\u003e This includes dynamically generated pages and error pages. Serving a JSON version of each \n\u003e resource should be seen as an additional feature and nothing more. \n\nStay is rather tolerant when it comes to different URI patterns, but a well-structured \nURI configuration is the foundation of a good web application. Take a look at some \nrecommendations for good URI design if you haven't already! \n[These guidelines](https://css-tricks.com/guidelines-for-uri-design/) are a good starting point.\n\nThe following example shows what's going on behind the scenes of Stay:\n\n```html\n\u003ca href=\"/foo/bar\"\u003eHyperlink\u003c/a\u003e\n```\n\nThis link will internally be converted to:\n\n```javascript\n\"http[s]://www.your-domain.com[:port]/json/foo/bar\"\n```\n\nThe modified URI won't be seen by the user and the infix can be freely chosen by you. \nIf we assume that the original URI points to a simple HTML page which looks like this:\n\n```html\n\u003chtml\u003e\n\t\u003chead\u003e\n\t\t\u003cmeta charset=\"utf-8\"\u003e\n\t\t\u003ctitle\u003eFoo\u003c/title\u003e\n\t\u003c/head\u003e\n\t\u003cbody\u003e\n\t\t\u003cdiv id=\"main\"\u003eBar!\u003c/div\u003e\n\t\u003c/body\u003e\n\u003c/html\u003e\n```\n\nthen the JSON equivalent must look like this:\n\n```javascript\n{\n    \"meta\": {\n        \"title\": \"Foo\"\n    },\n    \"main\": \"Bar!\"\n}\n```\n\nStay would look at this JSON response and then try to replace the children of ```#main``` with the received \ncontent which is a simple text node in this case, but could be any HTML content. The ```meta``` object's \n```title``` property is used to adjust the current page's title. Furthermore, the browser history will be \nmanaged for you to support the back and forward browser controls. \n\nAlthough the above example HTML is minimal, it highlights the main aspects of asynchronous web applications:\n\n- More efficient bandwidth usage\n- Better loading performance\n- More control over the navigation process\n- Consolidation of a main page structure\n- Still highly customisable!\n\n\n## Media and External Resources\n\nStay detects external resources and doesn't touch them. The user will experience a synchronous navigation. \nHyperlinks to internal resources such as images or executable files are problematic because they can't be \nidentified as such by their URI alone. You may, however, define an arbitrary number of regular expressions \nto exclude specific URIs. \n\n```javascript\nstay.exclusions.push(/\\/nonJSON\\//);\n```\n\nWhen linking a resource that can't be represented in JSON format, you should consider moving it to a dedicated \nfile server. Since Stay ignores external resources by default, the file would just open as expected.\n\n\n## Documentation\n[API](http://vanruesc.github.io/stay/docs)\n\n\n## Contributing\nMaintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.\n\n\n## License\n[Apache 2.0](https://github.com/vanruesc/stay/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanruesc%2Fstay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanruesc%2Fstay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanruesc%2Fstay/lists"}