Skip to content

Mobile Development Guide

Jump to bottom
Chen Yanyu edited this page Apr 13, 2021 · 8 revisions

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 "Install app" 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.

Mobile Developer Guide

Packages

  • react-responsive (for responsive browser features, such as breakpoint detection)
  • react-draggable (for the draggable Repl component)
  • react-simple-keyboard (for custom keyboard row)

Current mobile-friendly features

  • Introduced responsiveness to the Playground workspace.
  • Users are able to add Source Academy as a Progressive Web App to their mobile home screen.
  • Collapsible Custom Keyboard which allows user to key in symbol more easily on mobile devices.

Current Implementation

rendering mobile workspace

  • There is currently one breakpoint handled inside the React app (768px)
    • We are currently using react-responsive (useMediaQuery and MediaQuery) to detect when the browser width goes below 768px
    • Components are conditionally rendered based on this boolean
    • A quick search of useMediaQuery, MediaQuery or the isMobileBreakpoint boolean inside the src directory will show all the places where components are conditionally rendered based on this breakpoint

Mobile Keyboard

  • Uses react-simple-keyboard, see the documentation
  • uses only the onKeypress method so keyboard buffer is not stored unlike the usual implementation given in the documentation.
  • only target at the editorRef being passed to it, currently there are Workspace Editor(Playground/Mission), Repl Editor and SourceCast Editor
    • rely on the AceEditor insert and navigate method. In the future, if more AceEditor input field are needed, pass the ref to the keyboard.
    • If it is a normal input field, additional implementation is needed. (This decision is made for simplicity so that we do not need to keep different buffer for different editor. Also, in SourceAcademy, code/symbol input are rare except AceEditor)

Challenges

Some major challenges are listed here:

  • Android soft keyboard up causes the viewport height to shrink (iOS does not have this issue). We cannot use viewport units to style the mobile related components. Also, the bottom MobileSideContentTabs will be pushed up together with the Android keyboard.
    • This is currently handled by a series of React effects inside Mobile Workspace to update the browser meta viewport height, and CSS on Android devices
  • There is an evolving myriad of mobile and tablet devices with everchanging screen sizes and dimensions. What is applicable today, may change in the future.
  • Different mobile browser behaviour across OS and browsers.
  • Changing mobile browser standards.

Future Extensions

  • The addition of a tablet breakpoint, and tablet friendly features
  • Offline Playground in the progressive web app
  • UI and UX improvements based on user feedback
  • New ideas for utilising the new Modules System (e.g. QR code scanner, camera related features, etc.)

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 in major PRs 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

    • Editor breakpoints work as expected, and the 'Resume' and 'Stop' buttons (under the settings tab) work properly.

  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!" (this will not popup if landscape orientation width >768px and loads the normal desktop workspace)
    • Refreshing the page while in landscape should still display the above message.
    • The message should disappear upon returning to the portrait orientation.

  7. Android Keyboard Up

    • Reason: The Android soft keyboard affects the mobile browser viewport height, which may cause UI bugs. These tests ensure that such bugs do not resurface.
    • The bottom MobileSideContent tab bar does NOT float on top of the Android keyboard when the Android keyboard is up (i.e. it remains at the bottom of the screen, and can only be seen when the user scrolls down)
Clone this wiki locally