spa Architekturführer Köln - SPA in the front, ProcessWire in the back

[schwarzdesign]

We recently rebuilt the Architekturführer Köln (architectural guide Cologne) as a mobile-first JavaScript web app, powered by VueJS in the frontend and ProcessWire in the backend. Concept, design and implementation by schwarzdesign!

The Architekturführer Köln is a guidebook and now a web application about architectural highlights in Cologne, Germany. It contains detailled information about around 100 objects (architectural landmarks) in Cologne. The web app offers multiple ways to search through all available objects, including:

• An interactive live map
• A list of object near the user's location
• Filtering based on architect, district and category
• Favourites saved by the user

The frontend is written entirely in JavaScript, with the data coming from a ProcessWire-powered API-first backend.

Frontend

The app is built with the Vue framework and compiled with Webpack 4. As a learning exercise and for greater customizability we opted to not use Vue CLI, and instead wrote our own Webpack config with individually defined dependencies.

The site is a SPA (Single Page Application), which means all internal links are intercepted by the Vue app and the corresponding routes (pages) are generated by the framework directly in the browser, using data retrieved from the API. It's also a PWA (Progressive Web App), the main feature of which is that you can install it to your home screen on your phone and launch it from there like a regular app. It also includes a service worker which catches requests to the API and returns cached responses when the network is not available. The Architekturführer is supposed to be taken with you on a walk through the city, and will keep working even if you are completely offline.

Notable mentions from the tech stack:

• Vue
• Vue Router for the SPA functionality
• VueX for state management and storage / caching of the data returned through the API
• Leaflet (with Mapbox tiles) for the interactive maps
• Webpack 4 for compilation of the app into a single distributable
• Babel for transpilation of ES6+
• SASS & PostCSS with Autoprefixer as a convenience for SASS in SFCs
• Google Workbox to generate the service worker instead of writing lots of boilerplate code
• Bootstrap 4 is barely used here, but we still included it's reboot and grid system

Backend

The ProcessWire backend is API-only, there are no server-side rendered templates, which means the only PHP template is the one used for the API. For this API, we used a single content type (template) with a couple of pre-defined endpoints (url segments); most importantly we built entdpoints to get a list of all objects (either including the full data, or only the data necessary to show teaser tiles), as well as individual objects and taxonomies. The API template which acts as a controller contains all the necessary switches and selectors to serve the correct response in <100 lines of code.

Since we wanted some flexibility regarding the format in which different fields were transmitted over the api, we wrote a function to extract arbitrary page fields from ProcessWire pages and return them as serializable standard objects. There's also a function that takes a Pageimage object, creates multiple variants in different sizes and returns an object containing their base path and an array of variants (identified by their basename and width). We use that one to generate responsive images in the frontend. Check out the code for both functions in this gist.

We used native ProcessWire data wherever possible, so as to not duplicate that work in the frontend app. For example:

• Page names from the backend translate to URLs in the frontend in the form of route parameters for the Vue Router
• Page IDs from ProcessWire are included in the API responses, we use those to identify objects across the app, for example to store the user's favourites, and as render keys for object lists
• Taxonomies have their own API endpoints, and objects contain their taxonomies only as IDs (in the same way ProcessWire uses Page References)

Finally, the raw JSON data is cached using the cache API and this handy trick by @LostKobrakai to store raw JSON strings over the cache API.

Screenshots

[netcarver]

Looks great - thanks for the write-up.

[bernhard]

This looks absolutely brilliant! Congratulations for this great work and thanks for sharing it with us!

I've also tried it on my phone and everything just worked ? One thing that was counter intuitive for me was the left arrow icon on the top left corner of the frontpage. On all other pages this icon means "back", on the frontpage there is no "back" of course, but I didn't realize that I was on the frontpage, so it might make sense to remove the icon there?

Another thing: I wanted to share the app with a friend, but the share icon is only available on sub-pages.

[pwired]

Beautiful color contrasts and switching between them
Responsive made with proportional resizing
Pictures going out of focus into the background
The first not irritating popups I have ever seen
-- Einfach WoW --

[schwarzdesign]

@netcarver Thanks!

@bernhard Thank you for the QA ? Regarding the "back" button, I tried to make it more intelligent, but I got stuck on the history API not having a reliable way to check the last items. I thought about turning it off only on the homepage, but I wanted to have a way to go back to the last page if you go e.g. from an object detail page to the homepage and want back to the object. I'd have to track the last history states manually, since the Vue Router just wraps around the history API and doesn't keep a memory of itself. I'll put that back on the to do list!

As for the share button, we only have that on the object pages in the subnavigation; it would take up to much space too have it on the bottom all the time. Maybe we can put it at the end of every page, or in the navigation. Though it's only supported in Chrome on Android and Safari at the moment, and most browsers have their own native sharing button, so it wasn't the most important feature to us.

@pwired Thank you so much! ?

[bernhard]

I understand, thx for the explanation ? What program did you use for the mobile screenshots?

[schwarzdesign]

38 minutes ago, bernhard said:

I understand, thx for the explanation ? What program did you use for the mobile screenshots?

@bernhard It's a little trick you can do with Google Chrome: In the responsive view mode, select one of the iPhone models in the responsive mode settings bar. In the flyout menu on the upper right, there's an option "show device frame". Only works with some of the devices, I've used "iPhone 6/7/8 Plus". If you take a screenshot (via the same flyout menu) while in responsive design mode with the show device frame option turned on, the device frame will be included in the screenshot.

[tpr]

Nice site, the only issue I came across is scrolling over the map is impossible with the mouse (the map gets zoomed instead).

[schwarzdesign]

13 minutes ago, tpr said:

Nice site, the only issue I came across is scrolling over the map is impossible with the mouse (the map gets zoomed instead).

@tpr Thanks! I see your point; I recently wrote a little snippet for leaflet to only activate mouse scrolling after clicking anywhere inside the map, maybe that would make sense here too. I'll put in on the to do list!

[bernhard]

1 hour ago, tpr said:

Nice site, the only issue I came across is scrolling over the map is impossible with the mouse (the map gets zoomed instead).

Yes. Same here. Also on mobile it is a little annoying. Google does it like this:

Ctrl+Scroll for Desktop:

2-finger-scroll for mobile:

[wbmnfktr]

Sorry for being late to the party but I had to look around on that site.

As already said here... Awesome!

 

[schwarzdesign]

Thanks for the feedback everyone, I just made some updates to the app! You may have to fully clear the cache to see the changes immediately, as with the service worker the caching is pretty aggressive.

@bernhard I have tweaked the functionality of the back button. The app now keeps track of the page history independently of the browser history API and only displays the back button if there are at least to items in the history stack. So you shouldn't see the back button on the first page visit, regardless of which route you're on.

@tpr @bernhard For now, I have just disabled scroll wheel zoom for most of the embedded maps; this way, the map won't interfere with the normal page scrolling. The map can still be zoomed with the buttons to the left, and scrool zooming activates after clicking inside the map. Pinch zooming on touch devices should also work as normal. The only exception is the map page (architekturfuehrer.koeln/karte) which can always be zoomed with the scroll wheel; but that page should always fill the entire viewport with nothing to scroll below that, so it shouldn't be an issue there.

[Moebius]

Congrats, looks amazing and performs super fast.

Just a short question. Did you have any concerns about SEO impact since everything is done through VUE and there is no real source coude there?

[dragan]

5 minutes ago, Moebius said:

concerns about SEO impact

Googlebot is clever these days. JS-content is no problem for indexing anymore (React, Angular, Vue etc.). Meta tags and page titles are adjusted for every page-view (something a lot of developers simply forget when building SPAs). Of course, you could always improve SEO, e.g. creating a sitemap.xml...

https://www.smashingmagazine.com/2019/05/vue-js-seo-reactive-websites-search-engines-bots/

^ a good read about the subject

 

[wbmnfktr]

Mh... makes we wonder.

[totoff]

hey @schwarzdesign, so pleased to see you finally found your way to processwire! awesome work i enjoy frequently on my mobile.

[bernhard]

Same experience I got when I wanted to try it on mobile. I thought that was because it was too new when I tried first ? 

[schwarzdesign]

@Moebius @dragan @bernhard Well, Google's crawlers can run JS, they even updated the Chromium version their crawlers run on a couple of weeks back, so it should have no problem with the app. architekturfuehrer.koeln ist also an entirely new domain we set up for the app, so there was nothing in the index to begin with. We'll see how the coverage is progressing going forward. I did built a sitemap to help with indexing the site by the way: https://architekturfuehrer.koeln/sitemap. This one is created server-side, though ...

[charger]

Thanks for the detailed write-up! Would you mind sharing how exactly you sync the PW routes with Vue router?

[schwarzdesign]

I just published another update that makes full use of the Add to Home Screen functionality in Chrome (though the app is installable in Android Chrome, Android Firefox, iOS Safari and regular Chrome). In particular, there's a new page that explains how to install the PWA on different devices, with a button that triggers the system dialogue for installing the PWA on supported browsers (only Chrome at the moment). This was a bit difficult to implement since there's little common ground between browsers in this regard at the moment, so let me know if you find any bugs or other errors!

@charger ProcessWire only handles specific paths, everything else is routed to the frontend app and handled by the router. A normal ProcessWire installation uses the .htaccess rules to redirect all requests to it's index.php file. Meanwhile, the Vue SPA uses one single index.html as it's entry point and performs all further routing inside the visitor's browser. Since I want most visitors and paths to go to the frontend app, I modified the .htaccess file ProcessWire comes with to only forward specific routes to ProcessWire, and route all other requests to the Vue app:

# .htaccess

# Requests to the root domain without a path should go to the Vue app (index.html) instead of ProcessWire (index.php)

DirectoryIndex index.html index.php index.htm


# This additional RewriteCond comes right before the main RewriteRule from ProcessWire
# It lets ProcessWire handle only calls to specific paths (in this case, the admin url (/cms), the API endpoint and the sitemap which is generated server-side)

RewriteCond %{REQUEST_URI} (^|/)(api|cms|sitemap)
RewriteRule ^(.*)$ index.php?it=$1 [L,QSA]


# Everything else is routed to index.html, so the Vue app will receive the request and the vue-router can show the appropriate page

# Redirect index.html to /
RewriteRule ^index\.html$ / [L,R=301]

# Redirect everything else to the app
FallbackResource /index.html

 

[charger]

@schwarzdesign I’m sorry, but I think I wasn’t specific enough. How does your router.js look like? ?

As you say the routing is handled by Vue. However, I wonder how Vue knows about the routes that exist. Do you manually add the routes to router.js? Or do you grab existing routes via API and then include them in the Vue router config?

[dragan]

@charger 

If you're looking at the JS in Chrome inspector, you'll see

	  , le = new ue("https://architekturfuehrer.koeln/api/v".concat(ae.API_VERSION, "/"),{
		objects: {
			path: "objects"
		},
		object: {
			path: "objects/{identifier}"
		},
		taxonomies: {
			path: "taxonomies"
		},
		walks: {
			path: "walks"
		},
		pages: {
			path: "pages"
		}
	})
	  , he = new ue("https://architekturfuehrer.koeln/",{
		magazin: {
			path: "magazine/results.json"
		}
	});

These are simply JSON that store all the necessary infos, e.g. https://architekturfuehrer.koeln/api/v1/objects

See the OP under "Backend", 1st paragraph.

[schwarzdesign]

@charger Oh I see ?  Well, frontend routing is completely handled by Vue, so there are no existing routes (as in, provided by ProcessWire). The only routes ProcessWire knows about are the different API endpoints. One of the screenshots in my post shows the URL segments configuration for the API template. Besides that, @dragan's explanation is spot on; since there are only a handful of API endpoints, those are configured manually. It's not inside the vue-router, since that one is only concerned with routes the visitor sees in their browser; I just wrote a little API class that takes a list of endpoints and made an instance available globally through the Vue prototype. For reference, this is the original unminified code with the endpoint definitions:

export const api = new Connector(
    `https://architekturfuehrer.koeln/api/v${config.API_VERSION}/`,
    {
        objects: {
            path: 'objects',
        },
        object: {
            path: 'objects/{identifier}',
        },
        taxonomies: {
            path: 'taxonomies',
        },
        walks: {
            path: 'walks',
        },
        pages: {
            path: 'pages',
        }
    }
);

As for the frontend routes, they are also configured natively inside the Vue app, here's an excerpt:

import ObjectList from './pages/ObjectList.vue';
import SingleObject from './pages/SingleObject.vue';

export default new VueRouter({
	// ...
  	routes: [
      {
            name: 'objects',
            path: '/objekte/:taxonomy([-_.a-zA-Z0-9]+)?/:term([-_.a-zA-Z0-9]+)?',
            component: ObjectList,
        },
        {
            name: 'object',
            path: '/objekt/:object([-_.a-zA-Z0-9]+)',
            component: SingleObject,
            }
        },
      	// ...
    ],
  	// ...
});

 

[dragan]

@schwarzdesign I just noticed that you block /api with your robots.txt: https://architekturfuehrer.koeln/robots.txt

Don't do that. This is most probably the reason Google can't index your Vue-powered site.

You can check what Googlebot really sees here: https://search.google.com/test/mobile-friendly

In your case, it's the empty, unpopulated Vue app tag. Not even the app shell is visible.

When I checked another Vue site earlier this week, Google actually reported issues when confrontend with a bot-blocking robots.txt rule. (another one was a missing cross-origin HTTP header, which doesn't apply for your site, since you're not loading anything from another domain)

[schwarzdesign]

@dragan Thanks for the tip, I fixed this alongside with a couple of other issues. The tool was throwing JavaScript errors that I couldn't figure out. For some reason one of my non-Vue components wasn't being transpiled by babel at all, so Google had trouble with the syntax. I have now rewritten the component as a native Vue SFC and added some more polyfills. Now it's finally working for me, and the mobile-friendly checker shows the rendered page correctly ... Hopefully it will improve the indexing situation ?