Our users have been asking lately about how navigation among different app screens works in WP-AppKit apps and how to deal with it the right way when implementing app themes.
We recently updated our doc regarding this matter:
Here are the answers to the most commonly asked questions about routing in WP-AppKit:
Do App Screens Have Corresponding URLs?
Yes! We just don’t call them “URLs”, we call them “fragments” (fragments are what’s after “#” in URLs) because we’re in a “single page app” and not on a website.
For example, this is a valid “internal app link” to a single post:
<a href="#single/posts/123">The post title</a>
In most cases, you won’t build those “links” manually though. You’ll use template tags that build them for you:
<a href="<%= TemplateTags.getPostLink(post.id) %>" >The post title</a>
Can I Set a Default Page For My App?
To define what’s showing on app launch you can use the “default-route” filter or the “launch-route” filter (certainly along with the refresh-at-app-launch parameter).
Be sure to note the difference between those two “launch-route” and “default-route”. In a nutshell:
- “default-route” = route triggered after app content refresh and when trying to navigate to an inexistent route (equivalent to HTTP 404).
- “launch-route” = route triggered at app launch. If not specified, it takes the value of “default-route”.
Here is how to set a custom page that appears at app launch (in your theme’s functions.js):
// Simple way: use of "default-route" (by default, "launch-route" = "default-route").
// This is if you don't need to differentiate your "launch route" from your "default route"
//Add our home page (will have the #my-home-route fragment and use the "my-home-template" to render):
App.addCustomRoute( 'my-home-route', 'my-home-template' );
App.filter( 'default-route', function( default_route ) {
default_route = 'my-home-route';
return default_route ;
} );
Or use “launch-route” if you need to reserve “default-route” for an “after refresh” and “route not found” usage:
//First, deactivate auto refresh at app launch or we will be redirected
//to "default-route" after refresh, which will appear as if our "launch route"
//has no effect :
App.setParam( 'refresh-at-app-launch', false );
//Add our home page, associated to #my-home-route fragment and "my-home-template.html" template:
App.addCustomRoute( 'my-home-route', 'my-home-template' );
//Set our home page route as launch route:
App.filter( 'launch-route', function( launch_route ) {
launch_route = 'my-home-route'
return launch_route;
} );
Can I Totally Customize Navigation Among App Screens?
Making a really custom navigation among your app is possible using the get*Link() template tags family, building fragments manually, and use App.navigate() as explained in the Navigation section of the doc.
However, be aware that navigation is also linked to app’s History management (what allows to implement the “Back button” functionality).
If you don’t break the default List > Single > Comments navigation logic you should not have to worry about it though.
But if you need to customize this default History management for your specific navigation needs, you’ll have to use History JS hooks.
In Conclusion
Building hybrid apps is really different than building websites. And that’s true for so many aspects of app development and design.
Regarding navigation and routing in WP-AppKit apps, once you:
- replaced “URL” by “fragment” and “rewrite rules” by “routing”,
- know how to play with default/launch routes,
- and know how to build your own screen fragment and navigate to it manually,
you’re pretty good to go! Happy coding folks 🙂
Hello, could you tell me how I can put a link to a particular category? where I can filter the posts only a certain category?
Hi Mário,
First, thanks for your interest in WP-AppKit and for your comment.
Create a list of posts filtered by a specific category can be done natively in WP-AppKit thanks to “Posts List” component. You can see in the doc that you can filter by post type and taxonomy (category is a taxonomy).
Once you created your component, either you include it into the app navigation, or you create a custom link as explained here in this post, or in the doc.
Don’t hesitate to give us some feedback about your WP-AppKit usage, we’ll be glad to see what you accomplish!
I want menu to appear when the screen is swipe to right, Whats the easiest way to do this, I found a tutorial thou but it uses jquery mobile library….
Touch gestures can be tricky to implement. I’d recommend you use HammerJS: http://hammerjs.github.io/.
@Benjamin please help me with how to implement it…And if possibly the code to make it swipe, Knowing 90% of android apps support swipe for menu, Lets make WP APP KIT the number one plugin for creating an app from wordpress..Thanks
It is definitely on our roadmap. However, we have several points to tackle before that. Stay tuned!
Yaaaay you guys are the best, Please whiles we wait for the upcoming version kindly help me with a little something to make it work for me…Thanks
Hi. I create a custom component for an about page of the app. Just the html, no need for server data. Added it as a custom fixed link on the menu, and add the route to it. It all works, if I open the menu and the the about, the page open. But pressing the physical back button on phone make the app stay in the about page. I made some dubug and see that in the make history filter, when I press the back button both the queried and the previous screen are filled with the same about-app component. If I’m on a page, instead, the previous component is filled with the post list one. When I first enter in the about page, in the make history arrive the same parameter that when I enter on a page, so the page itself, the list as previous. The history action is correctly set to empty thatn push. Could this be a bug of the framework? Or is there something more need to be done?
Hi Luca, could you please forward your question to our support on support[at]uncategorized-creations.com so that we can help you better?
If it comes out that this is a bug, we’ll handle it as a github issue, then post any useful information that may come out of it back here.