Introduction to contexts

In the previous section of the quick start tutorial, you learned about remixing and some of the terms that we use to talk about Koji’s ecosystem. In this section, you’ll explore contexts and how they enable the remixing experience on Koji.

By the end of this section, you should feel comfortable:

Understanding what contexts are.
Understanding the different types of contexts and when they’re applicable.
Determining the initial context.

What are contexts?

Many software applications provide different views, depending on what the user is doing.

Think of a typical banking application. It probably provides an accounts overview, an account detail view, a transaction detail view, and a section for other features like transfers. The application looks and behaves differently, often with UI and UX patterns that are optimized for particular tasks, depending on which view the user is in.

Koji does something very similar. The platform provides many different views that look and act differently. We call these views contexts.

Let’s take a look at the most basic and important contexts:

Default - The default experience for a template. When you previewed the Bouncy Blast game in the last section, you experienced the default context for that template. When you publish a remix, the live version of the remix is also using the default context.
Remix - The creator’s experience when they are in the process of remixing a Koji. When you customized Bouncy Blast by selecting new images and music, you experienced the remix context for that template.

Let’s see how we can use contexts to build a remix experience.

Determining the initial context

Go back to your project in the code editor. If you’ve closed the code editor since the last section, remember that you can see and open your projects from the Developer Portal.

You can use the @withkoji/core package to determine the initial context that is loaded when your project is viewed by a user.

Open frontend/src/App.js and update it to look like the following.

import Koji from '@withkoji/core';
import { useState } from 'react';
import './App.css';

function App() {
  const [logoSrc, setLogoSrc] = useState('https://upload.wikimedia.org/wikipedia/commons/a/a7/React-icon.svg');

  const { context } = Koji.playerState;

  const captureImage = async () => {
    const src = await Koji.ui.capture.image();

    if (src) setLogoSrc(() => src);
  };

  if (context === 'remix') {
    return (
      <div className="App">
        <header className="App-header">
          <button onClick={captureImage}>Capture Image</button>
        </header>
      </div>
    );
  }

  return (
    <div className="App">
      <header className="App-header">
        <img src={logoSrc} className="App-logo" alt="logo" />
        <p>Some New Text</p>
      </header>
    </div>
  );
}

export default App;

You’ve added a number of things here. First, you get a value from Koji.playerState.context by using object destructuring. The variable context is set to a string value that represents the initial context. In our current project, the value should be default or remix, depending on whether the user is consuming or remixing the template.

You’re also doing some conditional rendering. If you’re in a remix context, you want to show the button to capture an image. If you’re not in a remix context, you can assume that you’re in the default context and show the rotating image, as well as some paragraph text.

Make sure to save your updates using Cmd+S or Ctrl+S, depending on your operating system.

Using the preview to test contexts

You’ll obviously want to test your code before publishing it. The preview in the code editor makes testing easy.

You can toggle back and forth between the default and remix contexts by using the tabs at the top of the preview pane.

Clicking the Remix tab causes the content in the if (context === 'remix') code block to be displayed. Note that the return statement causes the program to exit from the method, so the block of code after the if statement does not get executed.

Clicking the Default tab causes context === 'remix' to be false, so the content of the if statement is skipped, and the content in the next code block is returned instead.

Additional contexts

There are additional contexts for more specific template use cases, including contexts to help with purchase and receipt flows, administrator access, and even a context to help improve the presentation of a rich preview image.

As you explore more of the platform and features that Koji offers, you’ll encounter more of these contexts, as well as some best practices about how to make them an integral part of the user experience.

Wrapping up

In this section, we explored the idea of contexts, and why they’re so important to delivering a good experience on Koji. You should feel comfortable distinguishing between the default and remix contexts, and using the @withkoji/core package, with some conditional logic, to present different experiences to the user.

In the next section, you learn about storing, retrieving, and using the customizable data that powers the remix experience.