Quickstart: Adding a new route

Adding a new route requires you to edit both the Scala app and the React app

🗣 You might find it more straightforward to check out this real-world PR with all the bits and bobs and internationalisation #1127

Scala

Edit the /routes file to add your new route and bind it to a function. You can name your function however you want but try to put it in a relevant controller (or create a new one!)

GET  /subscribe/guardian-fortnightly    controllers.Subscriptions.fortnightly()

Then on your controller handle your route. For a GET route you'll need to return the main view with at least a title, id, JS entry point, and CSS entry point. (More on those two on a moment).

Notice the id parameter. We will be using that later!

def fortnightly(): Action[AnyContent] = CachedAction() { implicit request =>
  implicit val settings: Settings = settingsProvider.settings()
  val title = "Guardian Fortnightly"
  val id = "fortnightly-landing-page"
  val js = "guardianFortnightly.js"
  val css = "guardianFortnightly.css"
  Ok(views.html.main(title, id, js, css)).withSettingsSurrogateKey
}

React & CSS

In assets/pages create a directory to hold your JS entry point and any supplying files such as the main CSS file. As a convention, they should be camelcase versions of the directory name.

You should also include your styles here. Webpack will create a CSS entry point named after the js entry point for you and will include all the styles you link from this CSS file plus the styles from the modules you import.

🌟 Tip! We are migrating all modules to bundle their own styles but not all of them do that yet. If they don't do that yet, you can include their styles from your main CSS file. You can update the components you use so they bundle their styles. it's a one-liner!

assets/pages/guardian-fortnightly/guardianFortnightly.jsx

// @flow

// ----- Imports ----- //
import React from 'react';

import Page from 'components/page/page';
import SimpleHeader from 'components/headers/simpleHeader/simpleHeader';
import Footer from 'components/footer/footer';

import { statelessInit as pageInit } from 'helpers/page/page';
import { renderPage } from 'helpers/render';

import `guardianFortnightlyStyles.scss`;


// ----- Page Startup ----- //

pageInit();

// ----- Render ----- //

const content = (
  <Page
    header={<SimpleHeader />}
    footer={<Footer />}
  >
    <div class="guardian-fortnightly-emoji">👍</div>
  </Page>
);

renderPage(content, 'fortnightly-landing-page');

The second argument to renderPage is the id we set up before in Scala. It needs to match or the page won't render!

assets/pages/guardian-fortnightly/guardianFortnightlyStyles.scss

// -----  gu-sass ----- //

@import '~stylesheets/gu-sass/gu-sass';

// ----- Legacy Shared Components ----- //
@import '~components/footer/footer';
@import '~components/headers/simpleHeader/simpleHeader';

// ----- Page styles ----- //
.guardian-fortnightly-emoji {
  font-size: 90px;
}

Nothing shocking here, just include more modules as you use them!

Webpack

Now that we have set up our client-side entry point we need to tell webpack to use it! To do this you have to edit webpack.common.js. You'll see a quite long list of entry points under entry. Just add yours like so:

entry: {
    ...
    fortnightlyLandingPage: 'pages/guardian-fortnightly/guardianFortnightly.jsx',
    ...
}

The identifier on the left-hand side is the final bundle name. It needs to match your Scala controller.

That's it!

You might need to rerun both sbt and webpack to see your changes. Try opening your new route in the browser to see it live!