Blog

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.

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:

location ~ .*/wp-appkit/app/config.(js|xml) {
    try_files $uri /index.php?$args;
}
location ~ .*/wp-appkit/app/themes/.* {
    try_files $uri /index.php?$args;
}
location ~ .*/wp-appkit/app/addons/.* {
    try_files $uri /index.php?$args;
}

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:

location ~ ([_0-9a-zA-Z-]+/)?.*/wp-appkit/app/config.(js|xml) {
    try_files $uri /index.php?$args;
}
location ~ ([_0-9a-zA-Z-]+/)?.*/wp-appkit/app/themes/.* {
    try_files $uri /index.php?$args;
}
location ~ ([_0-9a-zA-Z-]+/)?.*/wp-appkit/app/addons/.* {
    try_files $uri /index.php?$args;
}

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

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

//In theme's functions.js for example:
//Set our custom template using the 'template' filter:

App.filter( 'template', function( template, current_screen ) {

    //Use the [your-theme]/special-category-template.html template
    //when rendering 'special-category' screen :
    if( TemplateTags.isCategory('special-category', current_screen) ) {
        template = 'special-category-template'; //Don't need .html here.
    }

    return template;
} );

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:

//In your theme's functions.js
define( [ 'core/theme-app', 'core/modules/persistent-storage' ], function( App, PersistentStorage ) {
    
    App.filter( 'template-args', function( template_args, view_type, view_template ) { 

        //Make "special_data" available in the "special-category-template.html" template:
        if( view_template == 'special-category-template' ) {
            template_args.special_data = PersistentStorage.get( 'special_data' );
        }

        return template_args;
    } );

} );

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

//In [your-theme]/special-category-template.html

<h1><%= list_title %></h1>
<div class="my-special-data">
    <p>First things first: <%= special_data.first_thing %></p>
    <div>
        And let the second thing be a list:
        <ul>
            <% _.each( special_data.second_thing, function( item ) { %>
                <li><%= item.name %>: <%= item.value %></li>
            <% } %>
        </ul>
    </div>
</div>

// And then display your category's posts looping on "posts" as you would do in the default "archive.html" template ...

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:

• Navigation
• Routing

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 🙂

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:

openssl genrsa -out rsa_1024_priv.pem 1024

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:

-----BEGIN RSA PRIVATE KEY-----
MIICWgIBAAKBgQCoLQvcggQflUc5ug9Ti10tcrKr9DVn/huAZquQ+XrjLBdJMXC/
l3mcL+J7svjbr0+f+JAPrUeSFB3yiGiIISLDxsbQmDaujKkZT+yTXfJ3uJFjppNP
Bdbk626MbPnRUKoWgMPlAxjYemoBV6Tg9AFcC2q8oCUD+SDbpKR2rfddHwIBJQKB
gCRcxEtaYcGjvF+CLNPLGxC+2oYLSdFLsutUeB9YiUXgBQjoGGDGzi+bppdJSpBd
QaYMOtL1CI5Jie9AFpn5U5+ZRSobz4v3RgCHBkvZsbAP1ararV1yCuDFyYIbQRg/
+pYltCfctB0teRiIq6j8fz07/gh/bElTdPA5mT2dJLGtAkEA6ZkqhIN4MOp9SGSZ
pqJPrR8qZ3NBNM04LlHg4rrnk7kZJfjWeS2iuKX4e8RfsAEhV5ZuRnpGxRs7vntg
ba5+PwJBALhNw1MTTwQa2ZcK2uh6WcI2Awu+PaGXXSpYscwx2ZUKBuxp1i0qLs9z
92PGk7Qzv35dZwxV6hIIyNvEWUl/KSECQEvC+Qhh/Xel/x5l0PfF8FPSwaUCyQo0
uEZfvo65KILv7HsEmJYA9oETO9UdGB1oJn1Fi4x6rysrbVKI4QD6UnUCQHeMYwV0
Tu3n5xXdhxNWSA9FoRxfuUY4qyJjC4temvjj6NCzWn4pMx7HwxBJdJCQRNxYQteR
rJYTiTSbCXvIGq0CQQDVnF8XYGUGjL16R0VbSOjmpizAtEQNDguLTPpHPP6w8UC3
m8NgYZ+Ht3+D1YsQ7zbc9M0J8XrfU1tiXnoQZZrl
-----END RSA PRIVATE KEY-----

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:

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:

//In functions.js
define( [ ..., 'core/modules/authentication', ... ], function( ..., Auth, ... ) {

    $( '#login-form' ).on( 'click', '#go-login', function( e ) { 
        e.preventDefault(); 
      
        //Log the user in! 
        Auth.logUserIn( 
            $('#userlogin').val(), //from form text input#userlogin 
            $('#userpass').val(), //from form password input#userpass 
            function( user_data_and_permissions ) { 
                //Do something when authentication went ok 
            }, 
            function( error) { 
                //Do something when authentication failed 
                //(wrong login, wrong password etc)
            } 
        ); 

    } );

} );

Then you can retrieve the currently logged in user:

var current_user = Auth.getCurrentUser();

check the WordPress user’s capabilities:

if ( Auth.currentUserCan( 'premium_access' ) ) { ... }

log the user out:

Auth.logUserOut();

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 :

//In functions.js
App.filter( 'template-args', function( template_args, view_type, template ) {
    if( template == 'my-user-page' ) {
        template_args.user = Auth.getCurrentUser();
    }
    return template_args;
} );

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

//In "my-user-page.html" template:
User login: <% user.login %><br>
User capabilities:
<ul>
    <% _.each( user.permissions.capabilities, function( capability ){ %>
        <li><%= capability %></li>
    <% } ); %>
</ul>

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

Happy user authentication folks!