commit db3eecadd0a39f3b44d5bf5429097e8c31ff7474 Author: Maxime Thirouin Date: Mon Mar 24 08:34:59 2014 +0100 First commit diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..8978b44 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +# editorconfig.org +root = true + +[*] +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[Makefile] +indent_style = tab diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules/ diff --git a/.jscs.json b/.jscs.json new file mode 100644 index 0000000..2ca2f74 --- /dev/null +++ b/.jscs.json @@ -0,0 +1,147 @@ +{ + "excludeFiles": [ + ] + , "requireCurlyBraces": [ + "if" + , "else" + , "for" + , "while" + , "do" + , "try" + , "catch" + ] + , "requireSpaceAfterKeywords": [ + "if" + , "else" + , "for" + , "while" + , "do" + , "switch" + , "return" + , "try" + , "catch" + ] + , "requireSpacesInFunctionExpression": { + "beforeOpeningCurlyBrace": true + } + , "disallowSpacesInFunctionExpression": { + "beforeOpeningRoundBrace": true + } + , "disallowEmptyBlocks": true + , "disallowSpacesInsideObjectBrackets": true + , "disallowSpacesInsideArrayBrackets": true + , "disallowSpacesInsideParentheses": true + , "disallowSpaceAfterObjectKeys": true + , "disallowCommaBeforeLineBreak": true + , "requireOperatorBeforeLineBreak": [ + "?" + , "+" + , "-" + , "/" + , "*" + , "=" + , "==" + , "===" + , "!=" + , "!==" + , ">" + , ">=" + , "<" + , "<=" + ] + , "disallowLeftStickedOperators": [ + "?" + , "+" + , "-" + , "/" + , "*" + , "=" + , "==" + , "===" + , "!=" + , "!==" + , ">" + , ">=" + , "<" + , "<=" + ] + , "requireRightStickedOperators": [ + "!" + ] + , "disallowRightStickedOperators": [ + "?" + , "+" + , "/" + , "*" + , ":" + , "=" + , "==" + , "===" + , "!=" + , "!==" + , ">" + , ">=" + , "<" + , "<=" + ] + , "disallowSpaceAfterPrefixUnaryOperators": [ + "++" + , "--" + , "+" + , "-" + , "~" + , "!" + ] + , "disallowSpaceBeforePostfixUnaryOperators": [ + "++" + , "--" + ] + , "requireSpaceBeforeBinaryOperators": [ + "+" + , "-" + , "/" + , "*" + , "=" + , "==" + , "===" + , "!=" + , "!==" + ] + , "requireSpaceAfterBinaryOperators": [ + "+" + , "-" + , "/" + , "*" + , "=" + , "==" + , "===" + , "!=" + , "!==" + ] + , "disallowImplicitTypeConversion": [ + "numeric" + , "boolean" + , "binary" + , "string" + ] + , "disallowKeywords": [ + "with" + ] + , "disallowMultipleLineStrings": true + + , "validateQuoteMarks": "\"" + , "disallowMixedSpacesAndTabs": true + , "disallowTrailingWhitespace": true + + , "requireKeywordsOnNewLine": [ + ] + , "requireLineFeedAtFileEnd": true + , "requireCapitalizedConstructors": true + , "safeContextKeyword": "that" + + , "validateJSDoc": { + "checkParamNames": true + , "checkRedundantParams": true + , "requireParamTypes": true + } +} diff --git a/.jshintrc b/.jshintrc new file mode 100644 index 0000000..7568631 --- /dev/null +++ b/.jshintrc @@ -0,0 +1,4 @@ +{ + "asi": true + , "laxcomma": true +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bd542fa --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,5 @@ +# Changelog + +## 0.1.0 - 2014-03-24 + +Initial release diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bde99ff --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,185 @@ +# Contributing Guide + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of +the developers managing and developing this open source project. In return, +they should reciprocate that respect in addressing your issue, assessing +changes, and helping you finalize your pull requests. + + +## Using the issue tracker + +The issue tracker is the preferred channel for [bug reports](#bugs), +[features requests](#features) and [submitting pull +requests](#pull-requests). + + + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the GitHub issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `master` or development branch in the repository. + +3. **Isolate the problem** — ideally create a [reduced test + case](http://css-tricks.com/6263-reduced-test-cases/). + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What OS experiences the +problem? What would you expect to be the outcome? All these details will help +people to fix any potential bugs. + +Example: + +> Short and descriptive example bug report title +> +> A summary of the issue and the browser/OS environment in which it occurs. If +> suitable, include the steps required to reproduce the bug. +> +> 1. This is the first step +> 2. This is the second step +> 3. Further steps, etc. +> +> `` - a link to the reduced test case +> +> Any other information you want to share that is relevant to the issue being +> reported. This might include the lines of code that you have identified as +> causing the bug, and potential solutions (and your opinions on their +> merits). + + + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to *you* to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + + + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic +help. They should remain focused in scope and avoid containing unrelated +commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code), otherwise you risk spending a lot of +time working on something that the project's developers might not want to merge +into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following this process is the best way to get your work +included in the project: + +1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork, + and configure the remotes: + + ```bash + # Clone your fork of the repo into the current directory + git clone https://github.com//happyplan + # Navigate to the newly cloned directory + cd happyplan + # Assign the original repo to a remote called "upstream" + git remote add upstream https://github.com/happyplan/happyplan + ``` + +2. If you cloned a while ago, get the latest changes from upstream: + + ```bash + git checkout master + git pull upstream master + ``` + +3. Create a new topic branch (off the main project development branch) to + contain your feature, change, or fix: + + ```bash + git checkout -b + ``` + +4. Make sure to update, or add to the tests when appropriate. Patches and + features will not be accepted without tests. Run `npm test` to check that + all tests pass after you've made changes. + +5. Commit your changes in logical chunks. Please adhere to these [git commit + message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) + or your code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/interactive-rebase) + feature to tidy up your commits before making them public. + +6. Locally merge (or rebase) the upstream development branch into your topic branch: + + ```bash + git pull [--rebase] upstream master + ``` + +7. Push your topic branch up to your fork: + + ```bash + git push origin + ``` + +8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) + with a clear title and description. + +9. If you are asked to amend your changes before they can be merged in, please + use `git commit --amend` (or rebasing for multi-commit Pull Requests) and + force push to your remote feature branch. You may also be asked to squash + commits. + +**IMPORTANT**: By submitting a patch, you agree to license your work under the +same license as that used by the project. + + + +## Maintainers + +If you have commit access, please follow this process for merging patches and cutting new releases. + +### Reviewing changes + +1. Check that a change is within the scope and philosophy of the project. +2. Check that a change has any necessary tests and a proper, descriptive commit message. +3. Checkout the change and test it locally. +4. If the change is good, and authored by someone who cannot commit to + `master`, please try to avoid using GitHub's merge button. Apply the change + to `master` locally (feel free to amend any minor problems in the author's + original commit if necessary). +5. If the change is good, and authored by another maintainer/collaborator, give + them a "Ship it!" comment and let them handle the merge. + +### Submitting changes + +1. All non-trivial changes should be put up for review using GitHub Pull + Requests. +2. Your change should not be merged into `master` (or another feature branch), + without at least one "Ship it!" comment from another maintainer/collaborator + on the project. "Looks good to me" is not the same as "Ship it!". +3. Try to avoid using GitHub's merge button. Locally rebase your change onto + `master` and then push to GitHub. +4. Once a feature branch has been merged into its target branch, please delete + the feature branch from the remote repository. + +### Releasing a new version + +1. Include all new functional changes in the CHANGELOG. +2. Use a dedicated commit to increment the version. The version needs to be + added to the `CHANGELOG.md` (inc. date) and the `package.json`. +3. The commit message must be of `v0.0.0` format. +4. Create an annotated tag for the version: `git tag -m "v0.0.0" v0.0.0`. +5. Push the changes and tags to GitHub: `git push --tags origin master`. +6. Publish the new version to npm: `npm publish`. diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 0000000..9abe4f5 --- /dev/null +++ b/LICENSE-MIT @@ -0,0 +1,20 @@ +The MIT License (MIT) + +Copyright (c) 2014 "MoOx" Maxime Thirouin + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7ab3861 --- /dev/null +++ b/README.md @@ -0,0 +1,487 @@ +# Pjax + + + +> When Ajax navigation meets Push State + +Pjax is ~~a jQuery plugin~~ **a standalone JavaScript module** that uses +ajax (XmlHttpRequest) and +[pushState()](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history) +to deliver a fast browsing experience. + +_It allow you to completely transform user experience of standard websites +(server side generated or static ones) to make them feel they browse an app._ + +## How Pjax works + +Pjax loads page using ajax & updates the browser's current url using pushState without reloading your page's layout or any resources (js, css), giving a fast page load. +_But under the hood, it's just ONE http request with a pushState() call._ +Obviously, for [browsers that don't support pushState()](http://caniuse.com/#search=pushstate) Pjax fully degrades (yeah, it doesn't do anything at all). + +It simply works with all permalinks & can update all parts of the page you +want (including html metas, title, navigation state). + +- It's not limited to one container, like jQuery-Pjax is, +- It fully support browser history (back & forward buttons), +- It **will** support keyboard browsing (@todo), +- Automatically fallback to classic navigation for externals pages (thanks to Capitain Obvious help), +- Automatically fallback to classic navigation for internals pages that will not have the appropriated DOM tree, +- You can add pretty cool CSS transitions (animations) very easily. +- It's around 3kb (minified & gzipped). + +### Under the hood + +- It listen to every clicks on links _you want_ (by default all of them), +- When a internal link hitted, Pjax grabs HTML from your server via ajax, +- Pjax render pages DOM tree (without loading any resources - images, css, js...) +- It check if all defined parts can be replaced: + - if page doesn't suit requirement, classic navigation used, + - if page suits requirement, Pjax does all defined DOM replacements +- Then, it updates the browser's current url using pushState + +## Overview + +Pjax is fully automatic. You won't need to setup anything on the existing HTML. +You just need to designate some elements on your page that will be replaced when +you navigate your site. + +Consider the following page. + +```html + + + + + + +
+
+ Sha blah blah. +
+ +
+ + + + +``` + +We want Pjax to grab the url `/blah` then replace `.my-Content` with whatever it gets back. +Oh and the `