WP-AppKit 0.5: Devil is in The Details

The 0.5 is here! Today, we’re pleased to release a new version of WP-AppKit. It should make the themers’ life better. There’s no killer feature but a series of careful enhancements as devil is in the details.

TLTR: download WP-AppKit 0.5.

More Than 30 Enhancements For Themers

After the hard work on the user authentication for version 0.4, we wanted to focus on making app theming as smooth as possible for the 0.5. So we reviewed the whole process of creating an app theme and made changes wherever it was needed. Of course we came out with bug fixes but especially with enhancements as diverse as:

  • Better iOS9 support
  • Better WordPress Multisite support
  • Enhancements of the WordPress admin panel
  • Template loading performance
  • Timezone offset management
  • Better transition directions naming
  • Better PhoneGap CLI support

Check all of them (31).

Icons and Splashscreens

Among all changes, you’ll find specific enhancements for splashcreens. Now, we handle a lot better splashscreen duration and fading. We also provide default icons and splashscreens if you don’t specify them (which is often the case during development).

Backward Compatibility

Quick warning about the backward compatibility for this version. During the process of building WP-AppKit 0.5, and considering we’re still in beta, we’ve made the choice to break backward compatibility on minor features.

Those changes are all listed here: https://github.com/uncatcrea/wp-appkit/blob/development/CHANGELOG.md#backward-compatibility-note.

Please take time to review them to see if it could have an impact on your apps.
If you used the Bootstrap theme, please be sure to update to the last version.

We hope that this version will ease the work of creating app themes as much as possible.

As usual, a complete changelog is available (https://github.com/uncatcrea/wp-appkit/blob/master/CHANGELOG.md) and the documentation has been updated accordingly (https://uncategorized-creations.com/wp-appkit/doc/).

So what are you waiting for? Download WP-AppKit 0.5 and have fun coding 🙂

How To Install WP-AppKit With Nginx

If you wonder why we are writing this post about Nginx, and nothing about Apache, the reason is simple: WP-AppKit is compatible with Apache, by default. Well, it will be completely with version 0.5 (see https://github.com/uncatcrea/wp-appkit/issues/167), coming soon.

TL;DR: If you directly want to know what to do with your Nginx configuration, go to the corresponding chapter.

Doing It The WordPress Way

So, does this means WP-AppKit is not fully compatible with Nginx? Of course not. But Nginx works a bit differently than Apache, especially regarding configuration and rewrite rules.

WordPress itself doesn’t handle automatically Nginx configuration, and if you try to activate permalinks on such an installation, you’ll be redirected to this codex page, explaining how you can make it work correctly.

This post does the same thing about WP-AppKit.

Under The Hood

You may (or may not) know that WP-AppKit provides 2 main features:

  1. previewing an app directly in the browser
  2. exporting all needed files to create a real app, connected to your WordPress website

Plus, we allow you to create and/or install your own theme to manage the look and feel of your app.

These features all need data coming from your website: your content of course, and also what you configured in the app edit screen or even your theme’s files (templates, scripts, images). In a preview context, be able to retrieve everything correctly requires us to define URLs where we can go get it.

Let’s take an example: config.js file. It is needed by WP-AppKit app core to set some important values. In fact, you are partially setting these values from the backoffice form, for example by choosing which theme you want to use.
When you export your app to build it with PhoneGap Build, it’s automatically generated and included into the zip you download.
But, when you’re previewing your app in a browser, it’s retrieved thanks to a given URL. This URL looks like wp-content/plugins/wp-appkit/app/config.js?wpak_app_id=my-app where wp-content/plugins/wp-appkit/ is WP-AppKit’s folder of installation, and my-app is your app slug.

To be honest, all other files are retrieved thanks to similar URLs. For example, require.js is taken from wp-content/plugins/wp-appkit/app/vendor/require.js.

Then, what’s the difference and what’s so special with config.js? The reality of it! Indeed, config.js doesn’t really exist. It’s dynamically generated, on demand.

And that’s where WordPress rewrite rules don’t play in our favor, because they enforce each file within wp-content/ folder to be real, or they’ll trigger a 404 error. You know, the ugly one, even before WordPress is called at all.

404_nginx

Note: it’s even true for both wp-admin/ and wp-includes/ folders as well.

We Will Rule The World

All that being said, the solution to make your browser preview work as expected is to add some rewrite rules before WordPress-related ones.

Single Site Install

If you run WordPress in a single site (standard) install, here are the rules you’ll have to add:

Multisite Install

As of now, we didn’t test this type of installation on Nginx. Our guess is that the previous rules will work for subdomain configurations, and that you’ll have to add a prefix for subfolder configurations:

Please feel free to comment on this post if you already tested it and you have some inputs for us about that.

Coding Chewbacca at the WPTech

This weekend (12/05/2015), Mathieu and I, we’ve attended the WPTech event. WPTech is a French WordPress event dedicated to technical topics and held in Nantes, a city in the western part of France.

240 people have attended 10 talks on various technical topics. There was a wide range of talks, from technical SEO to how to create proper hooks. But we all agree that it is the REST API & Javascript year for the WordPress world. So we had a great talk from Maxime Bernard-Jacquet on the REST API. As WP-AppKit uses a REST API and Javascript for 2 years now, I must say that it is great to be mainstream 🙂

As usual, it has been also a great opportunity to meet people, learn and share.

For the second edition, the organizers have created a coding room where in-depth technical workshops were held. We’ve been lucky enough to present during 2 hours WP-AppKit and how to code an app theme. We’d like to thank all the workshop attendees. It has been a great moment to build with you this little app using the Star Wars API 🙂

For those who have asked:

At last, kudos to the organizers! It has been a great event.

Happy coding!

Customize WP-AppKit Templates

By default, each WP-AppKit app’s screen has a corresponding template associated to it:

  • post lists render using the archive.html template
  • post details render using the single.html template
  • etc.

And each of those templates receives a set of  pre-defined variables that you can use to display your screen data:

  • in archive.html you can use list_title (the title of the post list screen), posts (array of posts to display), and total (total number of posts in the post list).
  • in single.html you can use the post object that contains post’s title, content, date, featured image, etc.

But what if you want to go further than this default behavior?
Let’s see how you can define your own templates and customize the data that is passed to them.

Define a Specific Template For a Given Category

Using the archive.html template for all categories is so boring… Here’s how you can define you’re own custom template to render your “Special” category (slug “special-category”):

Then in your special-category-template.html you can use list_title, posts and total variables just as you would do in the default archive.html template.

In this example we’ve seen how to use the “template” filter to set a custom template for a category screen, but the same applies if you want to set a specific template for:

  • a particular post screen: you would test if current_screen.item_id == my_post_id,
  • a particular post type screen: test if TemplateTags.isPostType( ‘my-post-type’ )
  • a particular component screen: test if current_screen.component_id == ‘my-component-slug’,
  • and any other app screen you may think of…

See the doc to learn more about what you can do with the “template” filter.

And How Can I Pass Special Data To My Special Template ?

Of course your special category is linked to some special data (other than list_title, posts and total) that you would like to see available in your custom template.
That’s fair. Let’s see how you can handle this using the “template-args” filter:

The “template-args” filter is a pretty useful tool that allows to pass any data (numbers, strings, JSON Objects, JS modules) to any of your templates.
This applies to native templates (‘archive.html’, ‘single.html’, ‘layout.html’, ‘menu.html’ etc) and to any custom template you define.

Here we suppose that you had special_data (JSON object) stored in Local Storage (using the Persistent Storage module) and that you want to pass this data to your special-category-template.html template:

Then in your special-category-template.html template you can now use “special_data“:
here we suppose that your special_data object contains special_data.first_thing (string) and special_data.second_thing (list of items):

Those are only simple examples.
Combining “template” and “template-args” filters is quite powerful and allows to implement nearly any template configuration and customization.

Thanks for reading and have fun with templates! 🙂

Navigation And routing In WP-AppKit Apps

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:

In most cases, you won’t build those “links” manually though. You’ll use template tags that build them for you:

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):

Or use “launch-route” if you need to reserve “default-route” for an “after refresh” and “route not found” usage:

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 🙂

WordPress User Authentication in WP-AppKit

As of version 0.4, WP-AppKit handles secured user authentication that allows to:

  • log in WordPress users from you app,
  • restrict some part of your app content to authenticated users with given permissions,
  • post comments from your app,
  • make authenticated queries to WordPress,
  • secure download links,
  • and any other cool stuff you can think of when you can authenticate users from apps.

WP-AppKit leverages the RSA public key encryption to encrypt all sensible data (password at handshake for example) and secret key based HMAC controls for all authenticated communications between the app and the WordPress server.

Here are the basic steps that will bring user authentication to your WP-AppKit app:

Create a RSA Private Key

On Windows the easiest way is to use PuTTY (see the private key generation doc for detailed steps).

On iOS/Unix based systems, simply use the “openssl” command:

Then, open the generated private key file (rsa_1024_priv.pem) in a text editor, and copy its content to your clipboard. This is your private key, which should be something like:

Link the Private Key to Your App

In your WordPress Back Office, go edit your App and paste your private key into the “Authentication Settings” > “App Private Key” field:

App private key

Save your app. It is now ready for secured user authentication.

Log Your Users In

To authenticate users from your app’s theme, you’ll use the WP-AppKit User Authentication JS API (JS module used as Auth var in the following examples).

Here is a login example (in the theme’s functions.js), where we suppose that the theme includes a login form (#login-form) where the user fills in his/her login (input#userlogin) and password (input#userpass), and submits with a #go-login button:

Then you can retrieve the currently logged in user:

check the WordPress user’s capabilities:

log the user out:

And many other things that you’ll find in the doc 🙂

To display user data in your templates, add the user object to your template vars using the “template-args” filter :

Then, the currently logged in user object is available as “user” var in your “my-user-page.html” template:

You can also check a complete implementation example in the “User Authentication Demo” version of our Q for Android theme.

Happy user authentication folks!

User Login Just Landed in WP-AppKit 0.4!

Aaaand we’re back! Version 0.4 is ready for you to download: https://github.com/uncatcrea/wp-appkit/releases/tag/v0.4.

User Authentication

This new version is a major step for WP-AppKit as it brings a long awaited feature: WordPress user login support. It means that you can now log users and get their capabilities right from your apps. We believe that user authentication is a major feature for content based apps. It allows countless applications from commenting to premium content. You asked us to implement that feature for a long time now but we had to find a way to have it secured and easy. So we spent the necessary time to search for the right solution and at the end, we chose to implement an RSA encrypted user authentication. We think that’s a convenient and easy way to have user login secured.

More info on user login in the doc:

You’ll also find an example of its implementation in the dedicated branch of our Bootstrap theme on Github: https://github.com/uncatcrea/wpak-theme-bootstrap/tree/feature-user-login.

WP CLI Support

Until now, exporting your app’s project to get it compiled in PhoneGap Build could be only done in the Applications admin panel. Now you can do it with WP CLI.

Hungry dev, doc about your new toy is here: https://uncategorized-creations.com/wp-appkit/doc/#2213-wp-cli-export.

Revised Demo Themes

From day 1, we have a series of demo themes to help you get started with WP-AppKit. However, we were not satisfied with the way they were handled in Github. We also thought that they needed more comments love to do a better job helping users. Now, each demo theme has its own repository. Off-canvas and Tabs themes have been recommented from scratch and Off-canvas themes got a serious code lifting.

Currently, there’s 3 demo themes (for both iOS and Android):

Want to see themes in action? Check the 1 minute videos!

All videos are available on our YouTube channel:

https://www.youtube.com/channel/UCk6cVcBuESc9iQGfg7bbOBA.

As usual, we hope that you will enjoy this new version and make great apps! BTW don’t hesitate to tell us what you do with WP-AppKit. More and more of our users are showing us what they’ve done and it feels warm to see them creating awesome apps 🙂

Speaking at WordCamp Lyon

Back in January, we were celebrating the past year at WordCamp Paris. Now is the time to celebrate the first half of 2015 at WordCamp Lyon!

But first, let’s celebrate the birth of the second official WordCamp in France. Kudos to the team that seems to have prepared what surely be a great WordPress event. One day full of very interesting talks about business, eCommerce, technology, use cases… That’s what I like about WordCamps they’re not only technical events (for that we have the great WPTech which should have its second edition at the end of the year). And all of that on a… boat! We couldn’t miss that, could we?

la-plateforme

La Plateforme, the boat where the first WordCamp Lyon is held

Develop an app in 40 minutes, on stage

So  this time, we’ve proposed to develop an app in 40 minutes, on stage 🙂 And we are honored that WordCamp Lyon organizers have accepted our proposal. We had a lot of fun preparing this talk and we really hope to see you there. It will a semi-serious talk as we propose to “überize the fortune cookies market“. So the subject is fun but you’ll get a bunch of insights on how you can use WP-AppKit to create your mobile apps: app’s configuration, theme’s development, how to use PhoneGap plugins, compiling with PhoneGap Build and more!

That’s our way to celebrate the last months achievements. Since January we’ve released 2 new versions of WP-AppKit. It has been also a year since we announced the first beta of WP-AppKit and we’d like to thank you for your support and feedback. It helps us everyday to make a better product. Stay tuned as the second half of this year will see some major announcements about WP-AppKit.

So if you attend WordCamp Lyon, don’t hesitate to say hi to Mathieu and Lionel!

EDIT: the workshop we held in now online on WordPress TV (in French): http://wordpress.tv/2015/06/17/lionel-pointet-and-mathieu-le-roi-40-minutes-pour-construire-une-application-mobile-reliee-a-wordpress-avec-wp-appkit/. You can also find the presentation (in French): http://fr.slideshare.net/uncatcrea/construire-une-application-mobile-en-30-minutes-avec-le-plugin-wpappkit.

That’s WP-AppKit 0.3

Done! After weeks of work, the new shiny O.3 version is finally here 🙂

App’s Panel Reinvented

10 months ago, Lionel joined us on this crazy project. He has worked on many aspects of the plugin since but we are very proud to announce that he has led the 0.3. Lionel has done a marvelous work on the app’s panel to offer a much better user experience. I am sure you will like it.

Let’s take a look in video! (turn sound on and double-click for fullscreen.)

As Usual, you can download WP-AppKit from GitHub: https://github.com/uncatcrea/wp-appkit.

Better Theme API

Along with the UI redesign, Mathieu also took time to enhance the theme API.

  • You can now pass any custom JavaScript variable or module to app templates using the new template-args JavaScript filter. For example if you develop a custom Javascript module in your theme, you can now use it anywhere in your templates.
  • All app jQuery AJAX calls (for web services) can now be customized. Thanks to the new ajax-args JavaScript filter, any setting from the jQuery.ajax() function can be set on WP-AppKit web services. Very useful to pass HTTP authentication data along with web services for example.
  • And last but not least, it is now possible to pass any custom data from your app to the server when calling a web service. Using the web-service-params JavaScript filter, you can now send any parameter that is specific to your current app state (like an app user setting) along with web services and filter your component query accordingly on server side.

For example, to filter a Post List component on categories that the app user would choose on app side: in functions.js, add your user categories to the web service using the web-service-params JavaScript hook.

On server (WordPress) side use the wpak_posts_list_query_args filter and the new WpakWebServiceContext class to filter your component content with the user categories received from the app.

We really hope that 0.3 will allow you to shape better apps 🙂

WP-AppKit 0.2 is out!

If you head to our GitHub repository today, you’ll find a fresh new version of Wp-AppKit.

A New Themes’ Folder

Version 0.2 prepares the plugin for the WordPress.org repository. Let people download WP-AppKit from WordPress.org is definitely one our major goal for our project. For that, we had to modify the way themes are stored.

  • Before 0.2, themes were stored in a folder located in the plugin’s folder (/app/themes).
  • Beginning with version 0.2, themes are now stored in the /wp-content/themes-wp-appkit folder.
  • This new folder is created when the plugin is activated.

Migrating from 0.1 to 0.2

When migrating from the 0.1 to the 0.2, please be sure to follow the below steps:

  • Backup your theme (located in the /wp-content/plugins/wp-app-kit/app/themes)
  • Deactivate version 0.1 in WordPress
  • Uninstall version 0.1 (simply delete or delete the wp-app-kit plugin folder)
  • Don’t worry, apps’ configuration is preserved
  • Install version 0.2 (drop the wp-appkit folder in your plugins folder and acticate wp-appkit in WordPress)
  • It creates a new folder (themes-wp-appkit) in wp-content which is the new home for your app themes
  • Note that sample themes are not delivered any more with the plugin itself
  • You may find them in their own repository: https://github.com/uncatcrea/wp-appkit-themes
  • Finally you have to save at least one time any apps done with the 0.1 to migrate them

Beyond themes’ folder, 0.2 brings its set of new things and among them persistent local storage and… a nice changelog 🙂 We hope it will be a useful resource for you to follow the evolutions of WP-AppKit.

Next Steps

Of course, we still have a long road to 1.0. Our next step will be to enhance the admin panel UI and the sample themes GitHub repository. We’re already working on these. So be prepared for the 0.3!

And again thank you for using and testing WP-AppKit 🙂

Download WP-AppKit 0.2

 

Having questions?

FAQ | Tutorials | Documentation

Or

Contact Us