A1: Roll Your Own - Button

A1: Roll Your Own - Button#

Overview#

Today we have a vast ecosystem of toolkits and frameworks to draw (pun intended, sort of.) upon when building a software user interface. Frameworks like Angular and React rely upon layers of abstraction to render visual components to a particular viewstate. While these abstractions make it possible for us to quickly build powerful user interfaces, they mask the underlying logic required to perform the most basic interactions. In this assignment, we will be peeling back the layers to improve our understanding of the fundamental logic that make graphical widgets work.

Assignment Introduction#

When you build a user interface, you might decide that you need a button, a checkbox, a way to capture text input, or one of the many other widgets provided to you by your chosen toolkit. To accomplish this task, you will likely create that widget by writing some code similar to the following (assuming our toolkit of choice is HTML):

 <button type="button">Click</button> 

When rendered in a browser we would see something similar to this:

Pretty straightforward, right? Write some code, build it, and view it. The end result is a nice graphical widget that changes in visual appearance when we interact with it using a mouse or keyboard. But how is this widget actually created?

Clearly, it is a graphical element displayed on a screen, but the button HTML tag does not describe it’s shape, colors, and behaviors. What operations take place to compose a button into what we see and interact with on the screen? For this assignment you will answer these questions by building your own custom button widget using drawing primitives.

Although there are many tools available for building a button widget, we will use the Javascript library for Scalable Vector Graphics called SVG.js. SVG.js provides us with the basic primitives that we need to create custom widgets in a nice programmatic library that renders to the browser.

Assignment Details#

This is the first of a series of assignments through which you will develop a mini graphical toolkit. Eventually, you will expand your toolkit to include common widgets like a text box, scroll bar, check box, and radio buttons. But for now, your goal is to focus on a design style and visual aesthetic for your toolkit.

A starter repository has been created for you that includes a basic graphical toolkit framework, a widget template, a simple heading widget, and a functional button widget.

Starter Code#

A starter repository has been created for you and is available on GitHub Classroom.

If you are not familiar with how to use GitHub Classroom repositories, we will go over the setup process in class.

Repository Structure#

The repository contains some basic files to help get you started. You are free to explore all of them, but you should only need to directly edit button.ts for this assignment.

File Overview#

Files you do not have to edit: dist/bundle.js: The bundled javascript that contains all code necessary to deploy your program. This file is autogenerated by webpack and won’t appear until you build.; dist/index.html: The HTML page used to load your widgets into the browser. This simply provides an HTML wrapper for bundle.js, you should not have to edit (but you might want to if you think of a name for you toolkit).; src/core/ui.ts: The base classes required to build a widget. You will eventually import from this file but you should not have to change it.; src/widgets/template.ts: A minimal widget implementation. You can use this file as a reference (or copy, paste, and rename) for all new widgets that you create.; src/widgets/heading.ts: A simple heading widget.
Files you do have to edit: src/index.ts: This file is used to build your ‘GUI’. You will instantiate and use your widgets from this file.; src/widdgets/button.ts: A single button type widget. The button class in this file is incomplete, but we will walkthrough how to get it working together in class.

Setting up your Workspace#

The repository makes use of npm, webpack, and TypeScript to function. So the first thing you will want to do after cloning the repository is install these tools. All of the config files are prepared for you, so you should only need to install the tools in order to run the project. We will install these tools using NPM. If you do not have NPM installed, follow these instructions to install npm: npm installation instructions.

After cloning the repository, open it up in your prefered code editing tool. If you are using an editor with a built-in terminal, then you can enter the following commands from within your tool. Otherwise, you will have to open your OS’s default terminal and CD into the directory where you placed the repository.

First, install webpack. A detailed overview of getting started with webpack can be found at their website: Getting Started | webpack

npm install webpack webpack-cli --save-dev

If all goes well you should not see any critical errors in the post-installation output. If you do, reach out to your instructors for assistance. Next, install TypeScript and the TypeScript loader:

npm install typescript ts-loader --save-dev

Once you have the required tools installed, run install on the repository to setup the rest of the build environment:

npm install

Again, you should not see any critical errors after install. Once complete, you should be able to run the project using npm:

npm run build

This command might take a few seconds the first time you run it, but when complete you should see something similar to the following:

> erasmas@1.0.0 build
> webpack

asset bundle.js 510 KiB [compared for emit] (name: main)
runtime modules 670 bytes 3 modules
cacheable modules 186 KiB
  ./src/index.ts 272 bytes [built] [code generated]
  ./src/core/ui.ts 6.54 KiB [built] [code generated]
  ./src/widgets/button.ts 5.62 KiB [built] [code generated]
  ./node_modules/@svgdotjs/svg.js/dist/svg.esm.js 173 KiB [built] [code generated]
webpack 5.68.0 compiled successfully in 1973 ms

Note

In the output above, the name “erasmas” is the name of the professor’s version of the toolkit. If you would like to personalize the name of your toolkit, you can edit the name property in the package.json file of the starter code.

You are now ready to run the program. The simplest way is to open the index.html file in the dist directory. However, you may prefer to setup a live server to host your program. To save you from having to build after every change, you can issue the following command, which takes advantage of the watch feature of webpack to keep your transpiled JavaScript file up to date.

npm run watch

Assignment Requirements#

For this assignment, you will primarily be tasked with learning how to make use of the toolkit and the SVG.js library. So rather than ask you to build your own widget from scratch, you will only be required customize the appearance of the button widget.

You are free to add as many features to your button widget as you like, but to receive full credit your button must support the following features:

Button: Be visually distinct from the default button provided in the starter code.; Visually change for at least three states (e.g., color change on hover).; Expose a custom label property to get and set the text on the button.; Expose a custom size property to get and set the height and width of the button.; Expose an event handler that notifies consuming code when the button is clicked.; Apply the event handler to a heading widget to indicate the click event occurred from the user interface.

Submission#

For this assignment you will submit the following items as a zip file to Canvas:

Your completed widget .ts file along with the rest of the starter code as a zip file to Canvas.
A screenshot of your widget and UI as it is rendered in the browser. Name your screenshot widget_demo.png (or .jpg, .gif, etc) and place it in the root of your project folder.

Remember to delete all generated files during the setup process (e.g., node_modules) to keep your file size small.

For Your Consideration

A good practice to make habit is to regularly commit your code to a source control system like GitHub as you make progress. You are free to use your github repository as often as you like as you work on the assignment, however, if you need assistance from the course instructors we will ask that you provide us with a link to your GitHub repository and a running instance of your program first.

Grading#

Your assignment will be given an overall grade that is based on the completeness of the following items:

All materials submitted correctly and on time: 1 pt
Documentation: 2 pts
- Is a screenshot of the widget and UI included?
Completeness of button widget : 7 pts
- Are all required widget features complete?

Total: 10 pts