Making a new Materia widget can be complicated, but the Template Widget has everything you need to get started. This issue serves as a beginner's task for learning how widget dev works, what essential pieces are needed, and the tools at your disposal.
Make sure your development environment is set up ahead of time. We recommend installing the development version of Materia ahead of time, though widget dev is mostly self-contained.
The Template Widget can be daunting because it showcases a fully formed widget with all the additional accoutrements like tests, snapshots, a custom score screen, and more. The required components of a widget are far smaller in size. Consult the Widget Developer's Guide for a breakdown of a widget's core components.
Let's Make a Widget
For this task, let's use the Template Widget as a starting point to create a simple quiz tool. In a nutshell, we'd like a widget that does the following:
- Allows widget authors to create simple multiple choice questions via the creator. Each should consist of a question ("What was the name of the spaceship Han Solo flies?") and at least two possible answers ("Millenium Falcon, USS Enterprise".) A question should have a correct option, with the remaining options considered incorrect. The widget should let you create multiple questions.
- Allow users to play an instance of the widget with the customized questions in the player. The widget should inform them if their choices are correct or incorrect, and then send them to the score screen when they answer the last one.
- As a bonus, if you'd like to make additional question types besides multiple choice - feel free!
The template widget implements the three main interfaces - the Creator, Player, and Score Screen - using different types of javascript code. We recommend you pick a javascript framework - or none at all! - and stick with it for the Player and Creator. Don't worry about authoring a custom score screen just yet, the default will work fine.
Remember that the Player and Creator interfaces are their own little standalone web applications. Both will need HTML, CSS, and JS files to work. Don't worry though; you'll find that it doesn't take much to get a very basic widget up and running!
Steps to get started
- Make sure you have the prerequisite tools installed: node, yarn, Docker, etc.
- Make sure your SSH keys are set up with GitHub.
- Make a fork of this repository by clicking the Fork button on the top-right.
- Clone your fork locally using
git clone.
- Check out the
starter-scaffold branch, which only has the essentials you need to get started.
- Create your issue branch from the scaffold branch - a handy command for that is
git checkout -b issue/issue-number-followed-by-issue-title
Once your project is set up, you can initialize the dev kit with the following:
- In the root directory of the widget repo, run
yarn install followed by yarn start
- Visit
localhost:8118 to see your widget!
Making a new Materia widget can be complicated, but the Template Widget has everything you need to get started. This issue serves as a beginner's task for learning how widget dev works, what essential pieces are needed, and the tools at your disposal.
Make sure your development environment is set up ahead of time. We recommend installing the development version of Materia ahead of time, though widget dev is mostly self-contained.
The Template Widget can be daunting because it showcases a fully formed widget with all the additional accoutrements like tests, snapshots, a custom score screen, and more. The required components of a widget are far smaller in size. Consult the Widget Developer's Guide for a breakdown of a widget's core components.
Let's Make a Widget
For this task, let's use the Template Widget as a starting point to create a simple quiz tool. In a nutshell, we'd like a widget that does the following:
The template widget implements the three main interfaces - the Creator, Player, and Score Screen - using different types of javascript code. We recommend you pick a javascript framework - or none at all! - and stick with it for the Player and Creator. Don't worry about authoring a custom score screen just yet, the default will work fine.
Remember that the Player and Creator interfaces are their own little standalone web applications. Both will need HTML, CSS, and JS files to work. Don't worry though; you'll find that it doesn't take much to get a very basic widget up and running!
Steps to get started
git clone.starter-scaffoldbranch, which only has the essentials you need to get started.git checkout -b issue/issue-number-followed-by-issue-titleOnce your project is set up, you can initialize the dev kit with the following:
yarn installfollowed byyarn startlocalhost:8118to see your widget!