Building a PWA
with Aurelia & Plone-Rest-API
#ploneconference2018 - Tokyo
Maik Derstappen
Empower small-scale farmers
What is gaipa?
gaipa is a global farmer empowerment community equipping farmers to create self-determined and sustainable livelihoods.
Project goals
mobile app
with accessible information for farmers
target markets
India & Sambia
target platforms
Android/PC
Offline support
It has to work also offline
Project goals
- mobile app
- target markets: India & Sambia
- target platforms: Android/PC
- Offline support
Technologies
- Browser based
- Progressive Web App (PWA)
- Aurelia JavaScript framework
- powerful Plone Rest-API
Why a Progressive Web App?
- runs on many OS
- runs on many modern browsers
- fast deployment, not like in app stores
- easy to build with web technologies
- offline support
- push notification support
Why Plone as the backend?
- solid storage for structured content
- confident permission and workflow system
- power full and flexible Restful-API
- existing UI for backend editing
Why Aurelia
- simple and clean HTML based templates
- less code >> good default conventions
- full featured - batteries included
- relatively small footprint
- stay's out of your way >> focus on your code
- great core team and community
- real release management
Demo time
How to build an PWA?
- first, use HTTPS!
- use a manifest file
- use service worker
- optionally: use workbox to setup service worker
- add push notifications, if needed
Manifest file
- App short name
- App Name
- icons
- orientation
- background color (for splash screen)
- theme color
Splash/Home screen
Manifest
{
"short_name": "MyApp",
"name": "My App, which does something",
"icons": [
{
"src": "/images/icons-512.png", "type": "image/png", "sizes": "512x512"
}
],
"orientation": "portrait",
"start_url": ".",
"background_color": "#9b924c",
"display": "standalone",
"theme_color": "#9b924c"
}
service worker
- Offline support
- Caching
- Performance - cache first, network second
Example service worker registration
if (workbox) {
workbox.routing.registerRoute(
new RegExp("(https?:\/\/gaipa\.org(\/app\/)()?)"),
workbox.strategies.staleWhileRevalidate()
);
workbox.precaching.precacheAndRoute([]);
}
Aurelia
add a project
yarn global add aurelia-cli
au run --watch
Aurelia
generate component
au generate component simple-top-bar
This will generate a Aurelia component, consisting of a template and a JavaScript file.
├── app.html
├── app.js
├── environment.js
├── main.js
├── resources
├── simple-top-bar.html
└── simple-top-bar.js
Aurelia JavaScript
export class SimpleTopBar {
constructor() {
this.message = 'Hello world';
this.friends = ['Chuck Norris', 'John Rambo']
}
}
Aurelia template file
<template>
<h1>${message}</h1>
</template>
Clean and simple templates
<template>
<ul class="friends">
<li repeat.for="friend of friends">Hello, ${friend}!</li>
</ul>
</template>
If you like Zope Page Templates, you might like Aurelia templates too ;).
Real Aurelia component JS
import { inject } from "aurelia-framework";
import {ContentApi} from './api';
@inject(ContentApi)
export class SolutionService {
constructor(gaipaContentApi) {
this.contentApi = gaipaContentApi;
}
activate(params) {
this.providerId = params.providerId;
this.serviceId = params.serviceId;
}
bind() {
let path = '/provider/' + this.providerId + '/service/' + this.serviceId;
this.getServiceData(path);
}
getServiceData(path) {
this.contentApi.getService(path)
.then(
service => this.service = service
)
.catch(error => {
this.error = error.message;
});
}
}
Real Aurelia component HTML
<template>
<article>
<h1>${service.title}</h1>
<span>${service.description}</span>
<span
innerhtml.bind="service.text.data | sanitizeHTML"
>${service.text.data}</span>
<a href.bind="service.url"
target="_blank"
title.bind="service.title">open external service website</a>
</article>
</template>
Aurelia service
import {HttpClient} from 'aurelia-fetch-client';
import {inject} from 'aurelia-framework';
@inject(HttpClient)
export class BookApi{
constructor(http){
this.http = http;
}
getBooks(){
return this.http.fetch('books.json')
.then(response => response.json())
.then(books => { return books; });
}
}
Enough Aurelia for now
You can find good documentation online or in books.
Plone Restful-API
By default you have access to all content and almost every other peace of Plone thru the Restful-API.
Great flexibility
If you need something in a different way, you can highly customize the Restful-API.
Customizing
- Serializer
- Deserializer
- Services (Components)
Serializer
The API automatically converts all field values to JSON compatible data, whenever possible.
Custom Serializer
@adapter(IChoice, IDexterityContent, Interface)
@implementer(IFieldSerializer)
class ChoiceFieldSerializer(BaseFieldSerializer):
def get_value(self, default=None):
value = getattr(
self.field.interface(self.context),
self.field.__name__,
default,
)
if not value:
return
term = _get_vocab_term(self.context, self.field.vocabularyName, value)
return term
registering the serializer
<configure xmlns="http://namespaces.zope.org/zope">
<adapter factory=".choice_field.ChoiceFieldSerializer" />
</configure>
Services
With services, you can get non-content data, as the Navigation or Breadcrumb info's.
JSON Response - Plone Page
GET /plone/front-page
{
"@components": {
"breadcrumbs": {
"@id": "http://localhost:55001/plone/front-page/@breadcrumbs"
}
},
"@id": "http://localhost:55001/plone/front-page",
"@type": "Document",
"UID": "SomeUUID000000000000000000000001",
"allow_discussion": false,
"changeNote": "",
"contributors": [],
"created": "2016-01-21T01:14:48+00:00",
"creators": [
"test_user_1_"
],
"description": "Congratulations! You have successfully installed Plone.",
"effective": null,
"exclude_from_nav": false,
"expires": null,
"id": "front-page",
"is_folderish": false,
"language": "",
"layout": "document_view",
"modified": "2016-01-21T01:24:11+00:00",
"parent": {
"@id": "http://localhost:55001/plone",
"@type": "Plone Site",
"description": "",
"title": "Plone site"
},
"relatedItems": [],
"review_state": "private",
"rights": "",
"subjects": [],
"table_of_contents": null,
"text": {
"content-type": "text/plain",
"data": "<p>If you're seeing this instead of the web site you were expecting, the owner of this web site has just installed Plone. Do not contact the Plone Team or the Plone mailing lists about this.</p>",
"encoding": "utf-8"
},
"title": "Welcome to Plone",
"version": "current",
"versioning_enabled": true
}
Getting the Breadcrumbs
GET /plone/front-page/@breadcrumbs
{
"@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
"items": [
{
"@id": "http://localhost:55001/plone/front-page",
"title": "Welcome to Plone"
}
]
}
Getting Breadcrumbs and Page data together
GET /plone/front-page?expand=breadcrumbs
{
"@id": "http://localhost:55001/plone/front-page",
"@type": "Document",
"@components": {
"actions": {
"@id": "http://localhost:55001/plone/front-page/@actions"
},
"breadcrumbs": {
"@id": "http://localhost:55001/plone/front-page/@components/breadcrumbs",
"items": [
{
"title": "Welcome to Plone",
"url": "http://localhost:55001/plone/front-page"
}
]
},
"navigation": {
"@id": "http://localhost:55001/plone/front-page/@navigation"
},
"schema": {
"@id": "http://localhost:55001/plone/front-page/@schema"
},
"workflow": {
"@id": http://localhost:55001/plone/front-page/@workflow"
},
},
"UID": "1f699ffa110e45afb1ba502f75f7ec33",
"title": "Welcome to Plone"
}
This combination is powerful
- custom service to get related content, for example by a catalog query
- use expand to include this information with the current content
- only one request needed
- much simpler client code
Example custom service
create the following structure in our Plone package
services/
├── configure.zcml
├── __init__.py
└── related_articles
├── configure.zcml
├── get.py
├── __init__.py
<configure xmlns="http://namespaces.zope.org/zope">
<include package=".related_articles" />
</configure>
Register the custom service
<configure xmlns="http://namespaces.zope.org/zope"
xmlns:plone="http://namespaces.plone.org/plone">
<adapter factory=".get.RelatedArticles" name="related-articles"/>
<plone:service
method="GET"
for="zope.interface.Interface"
factory=".get.RelatedArticlesGet"
name="@related-articles"
permission="zope2.View"
/>
</configure>
Service implementation 1/2
@implementer(IExpandableElement)
@adapter(Interface, Interface)
class RelatedArticles(object):
def __init__(self, context, request):
self.context = context
self.request = request
def __call__(self, expand=False):
result = {
'related-articles': {
'@id': '{}/@related-articles'.format(
self.context.absolute_url(),
),
},
}
if not expand:
return result
solution_categories = [c for c in self.context.solution_category]
article_brains = api.content.find(
portal_type="Chapter",
solution_category={
'query': solution_categories,
'operator': 'and',
}
)
items = []
for article in article_brains:
items.append({'title': article.Title, '@id': article.getURL()})
result['related-articles']['items'] = items
return result
Service implementation 2/2
class RelatedArticlesGet(Service):
def reply(self):
related_articles = RelatedArticles(self.context, self.request)
return related_articles(expand=True)['related-articles']
GET /plone/some-content?expand=related-articles
"@components": {
"breadcrumbs": {
"@id": "http://localhost:7080/plone/some-content/@breadcrumbs"
},
"navigation": {
"@id": "http://localhost:7080/plone/some-content/@navigation"
},
"related-articles": {
"@id": "http://localhost:7080/plone/some-content/@related-articles",
"items": [{
"@id": "http://localhost:7080/plone/articles/harvesting",
"title": "Harvesting"
}]
}
},
Any questions?
Thank you!
Maik Derstappen - Derico - md@derico.de
- Twitter: @tangoman78
- GitHub: MrTango
Slides online: http://derico.de/talks
Building a PWA
with Aurelia & Plone-Rest-API
#ploneconference2018 - Tokyo
Maik Derstappen