Phalanxpress allows you to create a backbone app using Wordpress as a back end. So you can easily create a single page wordpress.
It provides a complete set of collections and models that automatically connects to your wordpress installation so you can freely use them with your views structure.
With this plugin you can:
- Retrieve posts, attachments, pages and custom post types.
- Retrieve the categories and tags and items from all types of taxonomies.
- Retrieve a page content.
- Retrieve the list of pages for navigation proposals.
- Retrieve the list of authors.
- All data and metadata associated for the post: author, comments, tags, etc.
- Keep a cache using localStorage for faster browsing.
You must have the json-api plugin installed in your wordpress. This plugin is provided with the repository.
To install it, just copy the folder json-api to your plugins folder. Usually in wp-content folder in your wordpress file structure.
You have to activate the plugin in your wordpress. Go to the plugins page and click on activate.
This plugin is a modified version of json-api plugin. Please refer to doc page for more information about how to use it.
This modified version implements custom taxonomies and custom post types. If you want to get a post corresponding to a custom taxonomy just add the parameter taxonomy in your url queries.
For example, to get all posts of type portofolio_project from custom taxonomy portfolio_category whose slug is user-experience, the url should be:
http://www.mywordpress.com/api/get_category_posts?slug=user-experience&taxonomy=portfolio_category&post_type=portfolio_project
The only dependency is the backbone library and its own dependency, the underscore library.
You have to include the phallanxpress.js or phallanxpress.min.js file included in the deploy folder. Please, always include this file after Backbone and Underscore libraries.
<body>
...
<script src="scripts/phallanxpress.js" type="text/javascript"></script>
...
</body>You can initialize the api just giving the url pointing to your wordpress json api. You can define this url in your json-api plugin settings page in your wordpress admin.
phallanx = new Phallanxpress.Api('http://www.mywordpress.com/api')Phallanxpress uses the localStorage attribute to save cache data by default. You can use also sessionStorage
You can enable or disable it with the next methods:
phallanx.cache.enable(); // Enables localStorage for cache
phallanx.cache.enable({sessionStorage: true}) // Enables sessionStorage for cache
phallanx.cache.disable();Cache is always enabled by default with localStorage, if it is supported by the browser.
You can control the expire time for each call with variable expireTime.
phallanx.cache.expireTime = 2 // Time for the cache to expire (in hours)Default expire time is 24 hours
You can force the request passing the variable forceRequest in every api call in order to skip the cache.
phallanx.post(10, { forceRequest: true })You can force a cleaning to remove all expired items with the method
// Cleans all expired items according to current expire time
phallanx.cache.cleanStorage()Or you can force to remove all items stored, even if they are not expired
// Cleans all items, expired or not
phallanx.cache.cleanStorage(true)If the quota is exceeded, it will automatically clean all expired calls and it will trigger a quota exceeded event.
phallanx.cache.on('quota exceeded', function(){
alert("Quota has been exceeded");
});Returns a Phallanxpress.Posts instance or a view object associated with the collection containing all recent posts ordered by date:
// Last 30 posts
phallanx.recentPosts({ view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Posts instance or a view object associated with the collection containing all posts matched with a search criteria
// Search all posts containing key 'javascript'
phallanx.searchPosts('javascript', {view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Posts instance or a view object associated with the collection containing all posts published on a given date
// Search all posts published on March, 7th 2012
phallanx.datePosts('2012-03-07', {view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Post instance or a view object associated with the model containing post given an id or a slug.
// Retrieve a post with slug 'phallanxpress-library'
phallanx.post('phallanxpress-library', { view: App.Views.Post });If a view object is passed, it returns an instance of this object passing the model as model variable.
If a view instance is passed in the options object, then the model is assigned to the view and the view's render method is binded to change event.
Returns a Phallanxpress.Categories instance or a view object associated with the collection containing all the categories or all items for a given taxonomy.
// Retrieve a list of all categories from taxonomy 'project_category'
phallanx.categoryList({ taxonomy: 'project_category', view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Posts instance or a view object associated with the collection containing the posts from a given category id or category slug.
// Posts from category with id 7
phallanx.categoryPosts(7, { view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Categories instance or a view object associated with the collection containing all the pages.
// Search all posts published on March, 7th 2012
phallanx.pagesList({ view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Page instance or a view object associated with the model containing a page with a given id or slug.
// Retrieve a page with slug 'about-us'
phallanx.page('about-us', { view: App.Views.Page });If a view object is passed, it returns an instance of this object passing the model as model variable.
If a view instance is passed in the options object, then the model is assigned to the view and the view's render method is binded to change event.
Returns a Phallanxpress.Tags instance or a view object associated with the collection containing all the tags or all items for a given taxonomy.
// Retrieve a list of all tags
phallanx.tagList({ view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Posts instance or a view object associated with the collection containing the posts from a given category id or category slug.
// Posts from tag with slug 'backbone'
phallanx.tagPosts('backbone', { view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Authors instance or a view object associated with the collection containing all the tags or all items for a given taxonomy.
// Retrieve a list of all authors
phallanx.authorList({ view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
Returns a Phallanxpress.Posts instance or a view object associated with the collection containing the posts from a given author.
// Posts from author with id 1
phallanx.authorPosts(1, { view: App.Views.Collection });If a view object is passed, it returns an instance of this object passing the collection as collection variable.
If a view instance is passed in the options object, then the collection is assigned to the view and the view's render method is binded to reset and add events (fired when request is finished);
You can use the api that automatically returns the objects or use the structure stand alone according to your needs.
These are the existing models.
- Post:
Phallanxpress.Post - Page:
Phallanxpress.Page - Category:
Phallanxpress.Category - Tag:
Phallanxpress.Tag - Base model:
Phallanxpress.Model. If you want to make your own model please extend from this object. Set theapiCommandandparseTagparameter.
All models can be retrieved using fetch() method given an id or an slug.
If you want to make your own models based on custom post types or custom taxonomies, you can add the variable postType and/or taxonomy.
All the collections extends from Phallanxpress.Collection object.
They implement the method:
getBySlug(slug): Returns the model associated with the given slug. Returnsnullif not found or throws an error if more than one are found.
Implements the methods recentPosts, searchPosts, datePosts, categoryPosts, tagPosts, authorPosts.
Implements a pagination:
posts = new Phallanxpress.Posts();
posts.recentPosts()
posts.on('reset', function(){
posts.page; // Current page
posts.pages; // Total number of pages
posts.count; // Number of posts per page
posts.pageUp(); // Get the next page
posts.pageDown(); // Get the previous page
posts.page(3, options); // Go to page 3
})You can always pass an object with different options and this will be passed to the fetch method. For example, to make and infinite scroll:
posts.pageUp({add: true}); This will add the new results to the previous results and a add event will be triggered.
If the passed contains a params object this will be the parametes for the api query. For example, to get the custom fields of the posts:
posts.pageUp({ params: { custom_fields: 'city, street' } });If no results are found it triggers a no posts event.
In case of an error an error event is triggered.
Implements the method pagesList.
Implements the method categoriesList.
Implements a method topCategories that returns a new category collection with the categories with no parent item in the collection.
Implements the method tagsList.
Implements the method authorsList.
If you want to make your own model please extend from this object. Set the apiCommand and parseTag parameter.
Added localStorage cache.
Initial release of phallanxpress.js.
You can fork the repository, make your contribution to the code and asking for a merge request.
All source files are in the folder src. Coffeescript is used and a classical class structure is followed.
You can run this command in your terminal from the respository root folder:
$ cake watch
And your coffee files will be automatically compiled to deploy folder everytime they change.
If you add some files to the library, you should add it to the output array in the Cakefile file. The order must be considered.
To build the library you have to run the next command in your terminal from the repository root folder:
$ cake build
This will create to files in the deploy folder: phallanxpress.js, the all-in-one-file development library; and phallaxpress.min.js, the minified and compressed version of the library.
The Jasmine suite is used for running spec tests for BDD.
To run the tests, just drag and drop the file index.html in the tests folder to your browser.
The tests and specs are in the specs folder. Specs are written in Coffeescript. Run in your terminal:
$ cake test
To automatically compile coffeescript files.
For more info about how to use Jasmine, please go to the Jasmine wiki.
Open an issue if you find a bug or if you miss something you want to be implemented or any suggestion you want to make.
If you develop something using this library, please let us know so we can make a showcase.
Send us the url of your work with some info about it to: info@aerstudio.com.
Anyway, thanks!
We would like to thank to:
- Wordpress.org: You know why.
- dphiffer: Creator of the well designed json-api wordpress plugin.
- Jeremy Ashkenas: The name under backbone.js and coffeescript.
Copyright (c) 2012 Hector Sanchez-Pajares, Aer Studio
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.