Mobile Development Guide

Setting up the Progressive Web App on your mobile device

For the optimal mobile experience, it is highly recommended to add Source Academy as a Progressive Web App (PWA) on your mobile device. This way, the browser interface will not hinder in-app navigation features.

Android Devices

1. Navigate to https://sourceacademy.nus.edu.sg on your mobile Chrome browser.
2. Click on the dropdown menu at the top right corner.
3. Select the "Add to Home screen" option and add the icon to your Home screen.

IOS Devices

1. Navigate to https://sourceacademy.nus.edu.sg on your mobile Safari browser.
2. Click on the share menu at the bottom browser navigation bar.
3. Select the "Add to Home Screen" option and add the icon to your Home screen.

Pull Request Review Guide

With the introduction of the Mobile Workspace component, contributors and reviewers are required to perform the following manual browser resizing checks to ensure that the responsive features of the app are working as intended. This is an additional step on top of the current UI snapshot testing suite with Jest and Enzyme.

Setting up a local live demo on your mobile device

1. Set up cadet-frontend on your computer (see the README.md file).
2. yarn run start on your computer to start the server on localhost:8000.
3. After successfully starting the server, you should see a line "On your network: http://your_local_ip_address:8000" in your terminal.
4. Ensure that your computer and mobile device are on the same network. Point your mobile browser at the above URL.
5. Follow steps 2 and 3 of the PWA Setup Guide above.

Manual Browser Resizing Checks

Currently, there is a single breakpoint at 768px. Manual resizing checks should toggle between the desktop and mobile versions at this breakpoint and check for the following:

App-wide features

1. Application Navbar:
   • Desktop Navbar collapses into a mobile hamburger menu and vice versa.

Playground features

1. Side Content Tabs:

   • Desktop Side Content Tabs collapses into a row of tabs at the bottom of the page and vice versa.
   • Toggle between tabs and resize the browser while in different tabs.
   • Expected behaviour:
     • 'Introduction' and 'Remote Execution' tabs are not rendered in the mobile Playground.
     • 'Editor' and 'Run' tabs are rendered at the left and right end of the row respectively in the mobile Playground.
     • Resizing from 'Introduction' or 'Remote Execution' tab on desktop Playground to mobile Playground should automatically toggle to the 'Editor' tab.
     • Resizing from 'Editor' or 'Run' tab on mobile Playground to desktop Playground should automatically toggle to the 'Introduction' tab.
     • All other tabs should remain as is when toggling from desktop Playground to mobile Playground and vice versa.

2. Ace Editor

   • Input a long program (or newlines) such that you can scroll vertically within the editor input. Mobile soft-keyboard up events should not break the UI.
   • Input a single long line in the editor such that you can scroll horizontally within the editor input. Mobile soft-keyboard up events should not break the UI.

3. Draggable Repl

   • The Repl should be vertically draggable via the horizontal bar located above the row of tabs in the mobile Playground.
   • The only exception is when the 'Stepper' tab is selected. The Repl is not draggable when the 'Stepper' tab is selected.

4. Program Execution

   • Upon clicking the 'Run' tab, the draggable Repl should 'pop up', displaying the Repl output.
   • Upon clicking other tabs, the draggable Repl will be automatically 'closed'.
   • The only exception is when the 'Stepper' tab is selected. When clicking the 'Run' tab while on the 'Stepper' tab, the app will remain on the 'Stepper' tab and display the Stepper output instead.

5. Setting Editor Breakpoints

   • (this feature has yet to be tested and documented on the mobile playground)

6. Orientation Change

   • Rotating the device from portrait to landscape should trigger a Blueprint Dialog component with the following message: "Please turn back to portrait orientation!"
   • Refreshing the page while in landscape should still display the above message.
   • The message should disappear upon returning to the portrait orientation.