Angular Wagtail 1.0 and getting started

Angular Wagtail and Wagtail Single Page App Integration are officially 1.0 and stable. It’s time for a more complete getting started guide. Let’s build a new app together. Our goal will be to make a multi-site enabled Wagtail CMS with a separate Angular front-end.  When done, we’ll be set up for features such as

  • Map Angular components to Wagtail page types to build any website tree we want from the CMS
  • All the typical wagtail features we expect, drafts, redirects, etc. No compromises.
  • SEO best practices including server side rendering with Angular Universal, canonical urls, and meta tags.
  • Correct status codes for redirects and 404 not found
  • Lazy loaded modules
  • High performance, cache friendly, small JS bundle size (In my experience 100kb – 270kb gzipped for large scale apps)
  • Absolutely no jank. None. When a page loads we get the full page. Nothing “pops in” unless we want it to. No needless dom redraws that you may see with some single page apps.
  • Scalable – add more sites, add translations, keep just one “headless” Wagtail instance to manage it all.

Start with a Wagtail project that has wagtail-spa-integration added. For demonstration purposes, I will use the sandbox project in wagtail-spa-integration with Docker. Feel free to use your own Wagtail app instead.

  1. git clone https://gitlab.com/thelabnyc/wagtail-spa-integration.git
  2. Install docker and docker-compose
  3. docker-compose up
  4. docker-compose run –rm web ./manage.py migrate
  5. docker-compose run –rm web ./manage.py createsuperuser
  6. Go to http://localhost:8000/admin/ and log in.

Set up Wagtail Sites. We will make 1 root page and multiple homepages representing each site.
Screenshot from 2019-10-20 12-08-46

You may want to rename the “Welcome to Wagtail” default page to “API Root” just for clarity. Then create two child pages of any type to act as homepages. If you don’t need multi-site support, just add one instead. Wagtail requires the Sites app to be enabled even if only one site is present. The API Root will still be important later on for distinguishing the Django API server from the front-end Node server.

Next head over to Settings, Sites. Keep the default Site attached to the API Root page. Add another Site for each homepage. If you intend to have two websites, you should have three Wagtail Sites (API Root, Site A, Site B). Each hostname + port combination must be unique. For local development, it doesn’t matter much. For production you may have something like api.example.com, http://www.example.com, and intranet.example.com.

Screenshot from 2019-10-20 15-13-39

Next let’s set up the Wagtail API. This is already done for you in the sandbox project but when integrating your own app, you may follow the docs here. Then follow Wagtail SPA Integration docs to set up the extended Pages API. Make sure to set WAGTAILAPI_BASE_URL to localhost:8000 if you want to run the site locally on port 8000. Here’s an example of setting up routes.

api.py

from wagtail.api.v2.router import WagtailAPIRouter
from wagtail_spa_integration.views import SPAExtendedPagesAPIEndpoint

api_router = WagtailAPIRouter('wagtailapi')
api_router.register_endpoint('pages', SPAExtendedPagesAPIEndpoint)

urls.py

from django.conf.urls import include, url
from wagtail.core import urls as wagtail_urls
from wagtail_spa_integration.views import RedirectViewSet
from rest_framework.routers import DefaultRouter
from .api import api_router

router = DefaultRouter()
router.register(r'redirects', RedirectViewSet, basename='redirects')

urlpatterns = [
    url(r'^api/v2/', api_router.urls),

Test this out by going to localhost:8000/api/ and localhost:8000/api/v2/pages/

If you’d like to enable the Wagtail draft feature – set PREVIEW_DRAFT_CODE in settings.py to any random string. Note this feature will generate special one time, expiring links that do not require authentication to view drafts. This is great for sharing and the codes expire in one day. However if your drafts contain more sensitive data, you may want to add authentication to the Pages API. This is out of scope for Wagtail SPA Integration, but consider using any standard Django Rest Framework authentication such as tokens or JWT. You may want to check if a draft code is present and only check authentication then, so that the normal pages API is public.

Angular Front-end

Now let’s add a new Angular app (or modify an existing one).

  1. ng new angular-wagtail-demo
  2. cd angular-wagtail-demo
  3. npm i angular-wagtail –save

In app.module.ts add

import { WagtailModule } from 'angular-wagtail';
WagtailModule.forRoot({
  pageTypes: [],
  wagtailSiteDomain: 'http://localhost:8000',
  wagtailSiteId: 2,
}),

In app-routing.module.ts add

import { CMSLoaderGuard, CMSLoaderComponent } from 'angular-wagtail';
const routes: Routes = [{ path: '**', component: CMSLoaderComponent, canActivate: [CMSLoaderGuard] }];

This is the minimal configuration. Notice the domain and site ID are set explicitly. This is not required as Wagtail can determine the appropriate site based on domain. However, it’s much easier to set it explicitly so that we don’t have to set up multiple hostnames for local development. Next let’s add a lazy loaded homepage module. Making even the homepage lazy loaded will get us in the habit of making everything a lazy loaded module which improves performance for users who might not visit the homepage first (Such as an ad or search result to a specific page).

ng generate module home --routing
ng generate component home

In app.module.ts add a “page type”. An Angular Wagtail page type is a link between Wagtail Page Types and Angular components. If we make a Wagtail page type “cms_django_app.HomePage” we can link it to an Angular component “HomeComponent”. Page types closely follow the Angular Router, so any router features like resolvers will just work with exactly the same syntax. In fact, angular-wagtail uses the Angular router behind the scenes.

pageTypes: [
  {
    type: 'sandbox.BarPage',
    loadChildren: () => import('./home/home.module').then(m => m.HomeModule)
  },
]

This maps sandbox.BarPage from the wagtail-spa-integration sandbox to the HomeModule. “sandbox” is the django app name while BarPage is the model name. This is the same syntax as seen in the Wagtail Pages API and many other places in django to refer to a model (app_label.model). “loadChildren” is the same syntax as the Angular Router. I could set the component instead of loadChildren if I didn’t want lazy loading.

Next edit home/home-routing.module.ts. Since our homepage has only one component, set it to always load that component

home-routing.module.ts with WagtailModule.forFeature

const routes: Routes = [{
  path: '',
  component: HomeComponent
}];

To test everything is working run ​”npm start” and go to localhost:4200.

Screenshot from 2019-10-20 14-47-23

We now have a home page! However, it doesn’t contain any actual CMS data. Let’s start by adding the page’s title. We could get this data on ngOnInit however this would load the data asynchronously after the route is loaded. This can lead to jank because any static content would load immediately on route completion but async data would pop in later. To fix this, we’ll use a resolver. Resolvers can get async data before the route completes.

Edit home-routing.module.ts

import { GetPageDataResolverService } from 'angular-wagtail';
const routes: Routes = [{
  path: '',
  component: HomeComponent,
  resolve: { cmsData: GetPageDataResolverService }
}];

This resolver service will assign an Observable with the CMS data for use in the component. We can use it in our component:

home.component.ts

import { ActivatedRoute } from '@angular/router';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import { IWagtailPageDetail } from 'angular-wagtail';

interface IHomeDetails extends IWagtailPageDetail {
  extra_field: string;
}

@Component({
  selector: 'app-home',
  template: `
    <p>Home Works!</p>
    <p>{{ (cmsData$ | async).title }}</p>
  `,
})
export class HomeComponent implements OnInit {
  public cmsData$: Observable<IHomeDetails>;

  constructor(private route: ActivatedRoute) { }

  ngOnInit() {
    this.cmsData$ = this.route.data.pipe(map(dat => dat.cmsData));
  }
}

Going top to bottom, notice how IHomeDetails extends IWagtailPageDetail and adds page specific fields. This should mimic the fields you added when defining the Wagtail Page model. Default Wagtail fields like “title” are included in IWagtailPageDetail.

The template references the variable cmsData$ which is an Observable with all page data as given by the Wagtail Pages API detail view.

ngOnInit is where we set this variable, using route.data. Notice how cmsData is available from the resolver service. When you load the page, you should notice “Home Works!” and the title you set in the CMS load at the same time. Nothing “pops in” which can look bad.

Screenshot from 2019-10-20 15-15-59.png

At this point, you have learned the basics of using Angular Wagtail!

Adding a lazy loaded module with multiple routes

Sometimes it’s preferable to have one module with multiple components. For example, there may be 5 components and two of them represent route-able pages. Keeping them grouped in a module increases code readability and makes sense to lazy load the components together. To enable this, make use of WagtailModule.forFeature. Let’s try making a “FooModule” example to demonstrate.

ng generate module foo
ng generate component foo

Edit foo.module.ts

import { NgModule, ComponentFactoryResolver } from '@angular/core';
import { CommonModule } from '@angular/common';
import { WagtailModule, CoalescingComponentFactoryResolver } from 'angular-wagtail';
import { FooComponent } from './foo.component';

@NgModule({
  declarations: [FooComponent],
  entryComponents: [FooComponent],
  imports: [
    CommonModule,
    WagtailModule.forFeature([
      {
        type: 'sandbox.FooPage',
        component: FooComponent
      }
    ])
  ]
})

export class FooModule {
  constructor(
    coalescingResolver: CoalescingComponentFactoryResolver,
    localResolver: ComponentFactoryResolver
  ) {
    coalescingResolver.registerResolver(localResolver);
  }
}

FooComponent is added to both declarations and entryComponents as it’s not directly added to the router. WagtailModule.forFeature will link the wagtail page type with a component. You can also add a resolver here if needed. Lastly, the constructor adds coalescingResolver. This enabled dynamic component routing between modules and likely won’t be needed in Angular 9 with Ivy and future versions of Angular Wagtail.

Add as many types of page types as desired.

Angular Universal

Angular Universal can generate pages in Node (or prerender them). This is nice for SEO and general performance. The effect is to generate a minimalist static view of the page that runs without JS enabled. Later the JS bundle is loaded and any dynamic content (shopping carts, user account info) is loaded in. Because the server side rendered static page is always the same for all users, it works great with a CDN. I’ve found even complex pages will be around 50kb of data for the first dom paint. Installation is easy.

ng add @nguniversal/express-engine --clientProject angular.io-example

Compile with npm run build:ssrand serve with npm run serve:ssr​. Angular Wagtail supports a few environment variables we can set in node. Setting the API server domain and site per deployment is possible:

export WAGTAIL_SITE_ID=2
export CMS_DOMAIN=http://localhost:8000

Confirm it’s working by disabling JavaScript in your browser.

Angular Wagtail provides a few extras for Angular Universal when run in Node (serve:ssr). You can return 404, 302, and 301 status codes by editing server.ts as documented. You can also add the wagtail generated sitemap. Not directly related to Wagtail, but I found helmet and adding a robots.txt pretty helpful too. Angular Univeral just runs express, so anything possible in express is possible in Angular Universal.

Bells and whistles – not found and more SEO

For a real site, consider adding a 404 not found component, setting page meta tags and canonical url. Edit the WagtailModule.forRoot configuration to modify this however you wish. If you followed the server set up from above then Wagtail redirects and drafts should “just work”. Any time Angular Wagtail can’t match a url path to component, it will query the Wagtail SPA Integration redirects API and will redirect if it finds one. If not, Angular Wagtail will show the 404 not found component to the user.

You can find the full angular wagtail demo source on gitlab.

More uno reports

I’ve been playing around more with openoffice.org’s uno api for making reports. Since I’ll be making more updates I’ll just post a link to the Google Code site

http://code.google.com/p/student-worker-relational-database/source/browse/#svn/trunk/ecwsp/uno_report

My latest improvement is supporting tables. It’s probably best to just show what it does.

Now a user could just download the report, change fonts, layout, etc, and reupload it. It does have it’s limitations and is a work in progress but it’s already pretty cool. As a developer I can just define what variables can be used and let someone else make the report (and change it around later). To use it you just have to make the proper data structures, so really this could be ported to any data driven application, not just Django.

Django Hack: adding extra data to admin interface

A common need I have for Django’s admin interface is to show a little more data for convenience right on the edit page. For example showing a link to a foreign key’s edit page right there. The way I do this is by setting the help_text field in the render_change_form function. I create a new function in my admin class to override render_change_form

class whateverAdmin(admin.modelAdmin):
 def render_change_form(self, request, context, *args, **kwargs):
  context['adminform'].form.fields['someField'].help_text = "Go to edit page " + str(context['original'].anyFunction()) + " (will discard changes)"
  return super(whateverAdmin, self).render_change_form(request, context, args, kwargs)

the anyFunction() is just a function I made to display a URL in my model. Notice the allow_tags line to allow the function to return the html <a> tag

def anyFunction(self):
 try:
  field = self.someField
  urlRes = urlresolvers.reverse('admin:appName_someField_change', args=(field.id,))
  return '</a><a href="http://example.com' + urlRes + '">' + str(field) + '</a>'
 except:
 return ""
anyFunction.allow_tags = True

This link is then very convenient when using the admin interface just to look up information. The render_change_from function is also useful to editing about the admin page. I use it to modify queryset’s for foreign key data as well.

Django

I mentioned the Django app I made in the previous post so I thought I would provide some info about what it is. Essentially the goal was to reduce duplicate work everywhere possible be moving data from spreadsheets and other database’s into one central database. Also to allow a non skilled worker to edit this data, then allow for reporting to remake all the excel sheets that were originally needed. Here’s my setup

Ubuntu 9.04 server running Django, MySQL, and Apache (LAMD?) Data models are defined in Django which automatically makes an Admin interface with some customization options.

data entry

Django also makes short work of authentication with is done against Active Directory. Reporting is done with PyExcelerator and pyRTF to make downloadable excel and rtf documents.

reporting

It’s a pretty basic database but it really saves a lot of time compared to maintaining lots of xls documents and mail merges. Also it allows a technical worker to import exported data from other database into MySQL. Ideally this program could also be linked with other MySQL backend programs. So say I want to use SugarCRM I could symlink the contacts table so both Sugar and Django use the same one for perfect 2-way syncing. The real beauty of this is that it was so quick to develop. This is just been a side project for me. Doing it in PHP or .NET would have easily taken 3 times as long.

Working away

Well I’ve been in nyc for a month now. The first few weeks have been hell with 60+ hour weeks at Cristo Rey but things are finally starting to calm down. At work I’m coordinating transportation for students to get to their work placements.

I’ve completely redid the process in a short time I was there from a bunch of random Excel files and proprietary databases to something more maintainable, a MySQL database with Django. I’m impressed with Django’s ability allow me to make good data centric websites in only a few days. Django’s philosophy of defining data “models” once and having it create the database and administration page automatically is great. I’m then using pyRTF and pyExcelerator to generate reports from the data. We can now enter student, company, and contact data in at one place and have it reflect to all relevant reports such as daily attendance. The admin interface is easy enough to use that students can do data entry with it.

Other new fronts include the possibility of moving from Act by Sage to SugarCRM should further streamline the process. The idea here would be that Sugar has more features and could integrate with my Django database, Outlook, and a smart phone. With some hacking around it looks like I can symlink(yay unix) a “contacts” table used in both Django and SugarCRM to keep them perfectly synced and keep Django happy in it’s data model land without manual SQL needed. I’m happy to be using my skills at the new placement, while also running the day to day activities at the school. Though it’s still a 10+ hour day with some Saturdays making it rather stressful.

Other thing’s I’m looking into are Alfresco content management system, Zimba email server, and SchoolTool. SchoolTool is a decent school administration management tool. It’s written in Zope which is a python based framework. Python is quickly becoming my favorite language. It’s missing a few key features so I might hack on it to make it work. One unsolvable(?) problem with SchoolTool is that it uses ZODB, an object oriented database. This means it would be really hard to integrate it with the other databases I’m using. ln -s can’t save me this time..