Skip to content

Mobile Development Guide

Jump to bottom
Joven Soh edited this page Apr 9, 2024 · 8 revisions

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

  • Responsive Playground, Assessment and Sourcecast workspaces.
    • Collapsible Draggable REPL component to maximise screen estate during editor input
    • Collapsible Custom Keyboard to improve accessibility to commonly used symbols.
  • Users are able to add Source Academy as a Progressive Web App to their mobile home screen.

Current Implementations

Mobile Navigation Bar

  • Staff routes are intentionally excluded from the mobile navigation bar.

Rendering the mobile workspace

  • There is currently one breakpoint handled inside the React app (768px)
    • Currently, react-responsive (useMediaQuery and MediaQuery) is used 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
    • The value of 768 is stored as a constant in commons/utils/Constants.ts and accessed from there

Mobile Keyboard

  • Uses react-simple-keyboard, see the documentation
  • This component uses react-simple-keyboard's onKeypress method to fire our handlers to update AceEditor. Thus, the keyboard buffer is not stored in react-simple-keyboard, unlike the usual implementation given in the documentation.
  • Only inputs into the Ace Editor that is in focus:
    • This is achieved through the passing of the editorRef from the corresponding AceEditor component to our custom keyboard component
    • The custom keyboard input is handled via the AceEditor's insert and navigate methods.
  • If the custom keyboard has to support more AceEditor input fields in the future, please create a new ref in MobileWorkspace.tsx, update the React Effect that handles keyboardInputRef, and pass this ref to the newly added AceEditor component.
  • Does not support input into non AceEditor fields (This decision is made for simplicity so that we do not need to keep different buffers for different editors. Also, in Source Academy, code/symbol input is rare except in the AceEditor)
  • Side note: Text would only be inserted after the touch event ends as we have to differentiate between a 'swipe' action and a 'tap' action.

Things to note

Some useful things to note when dealing with the mobile browser:

  • Android soft keyboard up causes the viewport height to shrink (iOS does not have this issue), thus we cannot use viewport units to style the mobile related components. This also causes the bottom MobileSideContentTabs to 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 ever-changing 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:

Playground features/ Intended behaviour

  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. 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' and 'CSE Machine' tab is selected. The Repl is not draggable when these tabs is selected.

  3. 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' and 'CSE Machine' tab is selected. When clicking the 'Run' tab while on the those tabs, the app will remain on the same tab and display the respective output instead.

  4. Setting Editor Breakpoints

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

  5. Orientation Change

    • Orientation changes (regardless of whether the soft keyboard is up) should not break the UI of the app in both the mobile browser and progressive web app.

  6. 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