Add guide for using GitHub Codespaces

.devcontainer/devcontainer.json

@@ -0,0 +1,65 @@
+{
+  "name": "NHS Prototype Kit",
+  "image": "mcr.microsoft.com/devcontainers/universal:2",
+  // codespaces seems to have an issue using port 2000 so setting to 2001 for the NHS Prototype Kit
+  "runArgs": ["--env", "PORT=2001"],
+  "portsAttributes": {
+    "3001": {
+      "label": "Running prototype",
+      // --------------------------------
+      // onAutoForward possible options
+      // --------------------------------
+      // you can change the value to one of the following possible options:
+      // 'notify' (shows a prompt),
+      // 'silent' (does nothing)
+      // 'openBrowser' (opens the prototype URL in a browser window/tab)
+      // 'openPrview' (opens the codespaces preview window to present the running prototype to the user)
+      "onAutoForward": "openPreview"
+    }
+  },
+  // forward the port for the browersync process
+  "forwardPorts": [3001],
+  "otherPortsAttributes": { "onAutoForward": "ignore" },
+  // when created - sets the git merge statergy to rebase to hopefully make easier time of merging
+  "onCreateCommand": "git config --global pull.rebase true",
+  // after creation - installs the node packages
+  "postCreateCommand": "npm install",
+  // A command to run each time a tool has successfully attached to the container
+  "postAttachCommand": {
+    "server": "npm run watch"
+  },
+  // codespace customisations
+  "customizations": {
+    // Configure properties specific to VS Code web-basde IDE used within codespaces.
+    "vscode": {
+      // editor settings
+      "settings": {
+        // uncomment the following lines to hide files not needed to update content
+        // "files.exclude": {
+        //   "{docs,lib,linters,middleware,node_modules,public,tests,NHS111.Shared.Frontend}/": true,
+        //   "*{CHANGELOG,CONTRIBUTING}.md": true,
+        //   "app/{data,assets}/": true,
+        //   "app/*.js": true,
+        //   "*.{js,yml,json}": true,
+        //   ".*": true,
+        //   "LICENSE": true
+        // },
+        // make emmet work within nunjucks
+        "emmet.includeLanguages": {
+          "njk": "html",
+          "nunjucks": "html",
+          "erb": "html",
+          "jinja": "html",
+          "jinja-html": "html",
+          "markdown": "html"
+        },
+        "html.suggest.html5": true
+      },
+      // bundle the following editor extensions
+      "extensions": [
+        // nunjuck syntax highlighting
+        "douglaszaltron.nunjucks-vscode-extensionpack"
+      ]
+    }
+  }
+}

app/views/how-tos/index.html

@@ -40,7 +40,10 @@ <h2 class="nhsuk-heading-s">Download and install</h2>
           <a href="/install/advanced">Advanced install guide</a>
         </li>
         <li>
-          <a href="/install/nhs-england-windows-laptops">Set up the prototype kit on an NHS England Windows laptop</a>
+          <a href="/install/nhs-england-windows-laptops">Set up the kit on an NHS England Windows laptop</a>
+        </li>
+        <li>
+          <a href="/install/codespaces">Install and use the kit with your web browser</a>
         </li>
         </ul>
       </li>

app/views/install/check-it-works.html

@@ -28,7 +28,7 @@
     <div class="nhsuk-grid-column-two-thirds">
 
       <h1>
-        <span class="nhsuk-caption-l">Step 8 of 8{{[":", operatingSystem ] | join(" ") if operatingSystem }}</span>
+        <span class="nhsuk-caption-l">Step 8 of 8{{[":", installEnvironment ] | join(" ") if installEnvironment }}</span>
         Check it works
       </h1>
 

app/views/install/codespace.html

@@ -0,0 +1,41 @@
+{% set installEnvironment = "Codespaces" %}
+{% set steps_total = "2" %}
+
+{% extends 'layout.html' %}
+
+{% block beforeContent %}
+    {{ breadcrumb({
+    items: [
+      {
+        href: "/",
+        text: "Home"
+      },
+      {
+        href: "/install/",
+        text: "Get started"
+      }
+    ],
+    href: "/install/codespaces/",
+    text: "Install and use the kit with your web browser"
+  }) }}
+{% endblock %}
+
+{% block content %}
+    <div class="nhsuk-grid-row">
+        <div class="nhsuk-grid-column-two-thirds">
+
+            <h1>
+                <span class="nhsuk-caption-l">Step
+                    {{ current_step }}
+                    of
+                    {{ steps_total }}{{[":", installEnvironment ] | join(" ") if installEnvironment }}</span>
+                {% block stepHeader %}{% endblock %}
+            </h1>
+
+            {% block page_content %}{% endblock %}
+
+            {% block pagination %}{% endblock %}
+
+        </div>
+    </div>
+{% endblock %}

app/views/install/codespaces/create-a-codespace.html

@@ -0,0 +1,86 @@
+{% set installEnvironment = "Codespaces" %}
+{% set current_step = '1' %}
+
+{% block pageTitle %}
+  Create a codespace - NHS prototype kit
+{% endblock %}
+
+{% extends 'install/codespace.html' %}
+
+{% block beforeContent %}
+  {{ breadcrumb({
+    items: [
+      {
+        href: "/",
+        text: "Home"
+      },
+      {
+    href: "/install/codespaces/",
+    text: "Install the kit in your web browser"
+      }
+    ]
+  }) }}
+{% endblock %}
+
+{% block stepHeader %}
+  Create a Codespace
+{% endblock %}
+
+{% block page_content %}
+
+  <p class="nhsuk-lede-text">To use the kit within a Codespace you will first need to create one.</p>
+
+  <h2>1. Go to the prototype repository</h2>
+
+  <p>Go to the GitHub repository for the prototype you wish to use. For this guide we will be starting a new prototype, using the
+    <a href="https://github.com/nhsuk/nhsuk-prototype-kit">NHS prototype kit repository</a>.
+  </p>
+
+  <p>If you using an existing prototype, go to step 2.</p>
+
+  <p>If you are starting a new prototype, follow the [get started guide](/install) to set up a new prototype and then publish it to GitHub.</p>
+
+  <p><img class="app-img-guide nhsuk-u-margin-bottom-0" alt="Location of the fork button on the repository page" src="/images/codespaces/fork-button.png"></p>
+
+  <p>Ask your development team or technical leadership where you should store your prototype and how to get access.</p>
+
+  <h2>2. Create a new Codespace</h2>
+
+  <p>On every Github repository page is a 'Code' button which is used to get a copy of or to use the code held within the git repository.</p>
+
+  <p>Locate the button, click it, a dialogue box will open, at the top of the dialogue click the 'Codespaces' tab.</p>
+  <p>Next click on the 'Create codespace on main' button. Which will open your new codespace in a new browser tab or window.</p>
+
+  <p><img class="app-img-guide nhsuk-u-margin-bottom-0" alt="Screenshot of the location of create a codespace on main button" src="/images/codespaces/create-a-codespace.png"></p>
+  <p>The 'Create codespace on main' button will either be shown as a large button or a small plus symbol after the label 'your workspaces in the cloud'.</p>
+
+  <h2>3. Wait for the Codespace setup to finish</h2>
+
+  <p>The Codespace will open in a new tab (or window) and begin the setup process.</p>
+
+  <p>You will see an interface building with a progress message showing that the space (known as a 'container') is being created or rebuilt.</p>
+
+  <p>This can take between 30 seconds and 5 minutes.</p>
+
+  <h2>4. Check that it has worked</h2>
+
+  <p>Once the Codespace has been created, you will then see the 'terminal' tab with commands being exectuted to start the prototype kit.</p>
+  <p>When the prototype has started it will open a preview window displaying the homepage of the prototype.</p>
+
+
+  <p><img class="app-img-guide nhsuk-u-margin-bottom-0" alt="Screenshot of the running codespace" src="/images/codespaces/running-codespace.png"></p>
+
+  <p>You now have a copy of the NHS prototype kit installed and running within a new GitHub Codespace.</p>
+
+  <p>This means you can create and edit prototypes entirely in your browser.</p>
+
+{% endblock %}
+
+{% block pagination %}
+  {{ pagination({
+    "previousUrl": "/install/codespaces/index",
+    "previousPage": "Get started",
+    "nextUrl": "/install/codespaces/working-with-codespaces",
+    "nextPage": "Step 2: Working with Codespaces"
+  }) }}
+{% endblock %}

app/views/install/codespaces/index.html

@@ -0,0 +1,65 @@
+{% extends 'layout.html' %}
+
+{% block pageTitle %}
+  Install and use the kit with your web browser - NHS prototype kit
+{% endblock %}
+
+{% block beforeContent %}
+  {{ breadcrumb({
+    items: [
+      {
+        href: "/",
+        text: "Home"
+      },
+      {
+        href: "/install/",
+        text: "Get started"
+      }
+    ]
+  }) }}
+{% endblock %}
+
+{% block content %}
+  <div class="nhsuk-grid-row">
+    <div class="nhsuk-grid-column-two-thirds">
+
+      <h1 class="nhsuk-heading-xl">Install and use the kit with your web browser</h1>
+
+      <p class="nhsuk-body-l">If you cannot install the kit on your computer (for example, beause you are not allowed to install Node.js) you can use an online service to edit and run code using your web browser.</p>
+
+      <p>Services that you can use include:<p>
+
+      <ul>
+        <li>
+          <a href="https://github.com/features/codespaces">GitHub Codespaces</a> – free for around 60 hours per month
+        </li>
+        <li>
+          <a href="https://www.gitpod.io/">Gitpod</a> – free for around 50 hours per month
+        </li>
+        </ul>
+
+        <p>For this guide we are using GitHub Codespaces.</p>
+
+      <h2 class="nhsuk-heading-l">Before you begin</h2>
+
+      <p>You do not need any technical knowledge to use this guide.</p>
+
+      <p>You will need a
+        <a href="https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out">GitHub account</a>.
+      </p>
+
+      <p>We will show you how to:</p>
+      <ul class="nhsuk-list nhsuk-list--bullet">
+        <li>set up the Codespace
+          </li>
+        <li>work with the Codespace</li>
+        </ul>
+      <p>
+        Installation usually takes up to 5 minutes.
+      </p>
+
+      {{ actionLink({ text: "Start guide for using the kit in a web browser", href: "/install/codespaces/create-a-codespace", classes: "nhsuk-u-margin-top-x nhsuk-heading-l" }) }}
+
+    </div>
+  </div>
+{% endblock %}

app/views/install/codespaces/working-with-codespaces.html

@@ -0,0 +1,66 @@
+{% set installEnvironment = "Codespaces" %}
+{% set current_step = 2 %}
+
+{% block pageTitle %}
+  Editing the kit with Codespaces -  NHS prototype kit
+{% endblock %}
+
+{% extends 'install/codespace.html' %}
+
+{% block beforeContent %}
+    {{ breadcrumb({
+    items: [
+      {
+        href: "/",
+        text: "Home"
+      },
+      {
+    href: "/install/codespaces/",
+    text: "Install the kit in your web browser"
+      }
+    ]
+  }) }}
+{% endblock %}
+
+{% block stepHeader %}
+    Editing the kit with Codespaces
+{% endblock %}
+
+{% block page_content %}
+
+    <p class="nhsuk-lede-text">If you are using the browser to edit the kit, you need to manage changes in Codespaces.</p>
+
+    <h2>Save changes</h2>
+
+    <p>Any changes you make are not shared with anybody else until you commit them to Git and push them to the repository.</p>
+
+    <p>You can use the Codespace code editor and user interface to manage changes with GitHub. You can use the
+        <a href="https://docs.github.com/en/codespaces/getting-started/quickstart">quickstart guide for working with Codespaces</a>
+    </p>
+
+    <h2>Manage prototypes</h2>
+
+    <p>When a Codespace is deleted, you will lose any uncommitted and unpushed changes.</p>
+    <p>GitHub Codespaces are automatically deleted after they have been stopped and have remained inactive for a defined number of days, by default this is 30 days.</p>
+
+
+
+    <h2>Publish prototypes online</h2>
+
+    <p>Codespaces are temporary and do not usually have passwords. Do not use them to <a href='/how-tos/publish-your-prototype-online'>publish your prototypes online</a>.</p>
+
+    <h2>Get going</h2>
+
+    <p>
+        <a href="/how-tos/build-basic-prototype/index">Build a basic prototype</a>
+        or
+        <a href="/how-tos/index">view other guides</a>.</p>
+
+{% endblock %}
+
+{% block pagination %}
+    {{ pagination({
+    "previousUrl": "/install/codespaces/create-a-codespace",
+    "previousPage": "Step 1: Create a Codespace"
+  }) }}
+{% endblock %}

app/views/install/download.html

@@ -28,7 +28,7 @@
     <div class="nhsuk-grid-column-two-thirds">
 
       <h1>
-        <span class="nhsuk-caption-l">Step 4 of 8{{[":", operatingSystem ] | join(" ") if operatingSystem }}</span>
+        <span class="nhsuk-caption-l">Step 4 of 8{{[":", installEnvironment ] | join(" ") if installEnvironment }}</span>
         Download and decide where to keep your prototypes
       </h1>