Versions Compared

Version Old Version 21 New Version 22
Changes made by

Joanna Lin

Edward Qian

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
breakoutModewide
languagebash
client/
    package.json
    src/
        App.scss                # Contains styles that we want globally applied, eg. scrollbar styles, default fonts, etc.
        App.tsx                 # The root React UI component. This is where you should add new routes.
        assets/                 # A bunch of images, fonts and other static content that you wouldn't put next to your source code
        components/             # All our React components (minus the pages themselves - those belong in the 'views' directory!)
            Autocomplete            # Basically a dropdown that suggests autocompletion results. See mui.com/components/autocomplete/.
            CarouselFeatures                # A slide-like UI that showcases a bunch of cards that you can swipe through. See react-slick.neostack.com/.Some components used to help showcase our project features on the landing page.
            FloatingWindow    Code      # The collapsible floating window on the visualiser, used for the operations menu and #the Codecode snippets.
            ContentManagementFooter       # A bunch of forms for creating/managing content. This is a bit# ofFooter aelement hellhole,at beware.the bottom of some pages, showing social links and links to other places.
Features            Frame    # Some components used to help showcase our project features on the landing page.  # Literally like picture 'frames', used to decorate showcase images 
Footer            Gallery      # Footer element at the bottom of some pages, showing social links# andA linkspretty tocontainer otherfor placespictures. Used to showcase a collection of items that have pictures. See mui.com/components/image-list/.
 Frame           HorizontalRule        # Literally like# picture 'frames', used to decorate showcase imagesBasically prettier <hr /> components. See mui.com/components/dividers/.
            Loader Gallery                 # ASome prettyfancy containerspinners, forused pictures.to Usedshow tosome showcasecontent a collection of items that have picturesis loading. See mui.com/components/image-listprogress/.
            Navbars HorizontalRule          # Basically prettier <hr /> components. See mui.com/components/dividers/.
   # Top navbar and side navbar
        Lesson    PageLayout              # Renders markdown lessons for a given topic Contains some fundamental UI that is reused by our pages. Eg. Given "Linked Lists"the topnav, itsome talkscontainer topadding, ouretc.
API to fetch the linked list lessons we have in the database. Tags             Loader       # A list of 'chip' components. It's mainly used to show #tags Somefor fancya spinners,topic used to show some content is loadinglike "COMP2521", "COMP1511", etc. See mui.com/components/progresschips/. 
           MarkdownEditor Topics          # A markdown editor and renderer. See npmjs.com/package/rich-markdown-editor.
            Modal      # Contains the UI cards for all the topics (linked list, BST, etc.) that appear on the homepage.
            Visualiser # Popups components - useful for showing registration forms, user confirmation popups, etc. # Our visualiser UI. This includes the controller UI, terminal, GUI form, Navbarsetc. 
               # Top navbar and side navbar             Panes   # This DOES NOT include any visualiser implementation! This is purely the surrounding UI. For the #actual Theimplementation, collapsible and resizable panes used in the visualiser pages. See npmjs.com/package/react-collapse-pane.see 'visualiser-src'
           constants/ Particles               # TheContains fancyglobal floatingconfig particles you see on the landing page. See github.com/matteobruni/tsparticles.
            Quiz                    # The quiz components used by lessons. Has variants like multiple choice quiz, true/false quiz, etc.
            SplashScreen            # That in-your-face splash screen you see when you visit the landing page.
            Tabs                    # Just like Chrome tabs. It's used to organise our educational content (eg. lessons, code, videos, etc.). See mui.com/components/tabs/.
            Tags                    # A list of 'chip' components. It's mainly used to show tags for a topic like "COMP2521", "COMP1511", etc. See mui.com/components/chips/. 
            Video                   # An embedded video player for playing youtube videos, for example.
            Visualiser              # Our visualiser UI. This includes the controller UI, terminal, GUI form, etc. 
                                    # This DOES NOT include any visualiser implementation! This is purely the surrounding UI. For the actual implementation, see 'visualiser-src'
        constants/              # Contains global config and values that would otherwise be hard-coded in our source code.   
            api.ts              # This contains important API connection info, eg. what the API URL is.
            cookies.ts          # This contains the names of cookies we're using. Eg. We need a name for the cookie that tracks whether the user should have dark mode on or off.
 and values that would otherwise be hard-coded in our source code.   
   index.tsx         api.ts      # The REAL root UI component. This should rarely# beThis touchedcontains unlessimportant we'reAPI doingconnection fundamentalinfo, changeseg. See 'App.tsx'.
  what the API URL is.
     layout/       cookies.ts          # This contains the names of  cookies we're using. Eg. We need #a Containsname somefor fundamentalthe UIcookie that istracks reusedwhether bythe ouruser pages.should Eg.have thedark topnav,mode someon container padding, etcor off.
        main.tsx     HomepageLayout.tsx          # The REAL root UI component. This should rarely be touched unless we're doing fundamental changes. See  VisualiserDashboardLayout'App.tsx'.
        structsThemes.ts        # Our colour palette! It sets dark mode and light mode colours
separately.         utils/                  # A bunch of reusable functions.
            apiRequests.ts          # Contains all the functions you need to grab or change content from the API. Eg. there's functions for fetching lessons, topics, etc.
            markdown-util.ts        # Some functions for working with markdown.
            Notification.ts         # Spawns a small notification/popup. Great for non-invasive error messages and communicating short messages with the user.
            url.ts                  # Some string manipulation functions, specifically for working with URL-like strings.
        viewspages/                  # Our pages. These are React components that specifically define page layout and content. For specific UI elements, see 'components'.            
            AboutUs.tsx                      
            ContentManagementDashboard.tsx   
            Feedback.tsx                     
            HomePage.tsx                     # Our landing page.
            Page404.tsx                      # A cool 404 page for when the user navigates to a route that we haven't defined. Eg. structs.sh/non-existent-page.
            VisualiserDashboardVisualiserPage.tsx
        visualiser-src/                      # Our visualiser source code. All the internal visualiser magic happens here. This does NOT define anything related to UI - for that, see 'components/Visualiser'. 
            binary-search-tree-visualiser/   # BST visualiser layout and operations. Includes things like insertion, rotation, etc. and drawing the tree.  
            controller                       # Executes controller operations like play, pause, speed change, etc. and manages state such as the animation timeline and operations history.
            linked-list-visualiser           # Linked list visualiser layout and operations. Includes things like insertion, deletion, etc. and drawing the linked list. 
            typedefs.ts                      # Custom data types used by the Visualiser implementation.

...

Using global CSS/SCSS is a nightmare in a large project because you will likely encounter name collisions and CSS specificity issues. With SCSS modules, every classname you define is 'mangled' so that it is always unique and is guaranteed to never
conflict with any other classname in the project.

How this works:

  1. Suppose you're working on LinkedList.jsx. Add a new file called LinkedList.module.scss

  2. Write your SCSS code in that file. Remember SCSS is a superset of CSS so you can just write regular CSS.

    Code Block
    languagescss
    .container {
    margin: 10px;
}

  3. Import the scss module in LinkedList.jsx and apply the style like this:

    Code Block
    languagejs
    import styles from './LinkedList.module.scss';

const LinkedList = () => {
    return <div className={styles.container}>...</div>;
};

React Visualiser UI:

This section provides an overview of the visualiser UI components hierarchy. This is probably the most complex part of the React codebase and deserves its own clarification section.

...

To make it show up on the React client, you must

  1. Add an entry for the visualiser into the ‘Topics’ section of the database

  2. Add an entry for the visualiser in the DataStructure enum type under visualiser-src/common/typedefs.ts (make sure the name is consistent with the lowercase version of the database topic title)

  3. Add a case statement for your data structure under visualiser-src/common/GraphicalDataStructureFactory.ts to return your GraphicalDataStructure.

Adding a New Operation to a Visualiser:

Creating the logic of the animations

  1. Code up the operation in the corresponding Graphical[DataStructure] in a new method. Add documentation for the arguments it accepts.

    1. Note: for now, arguments are non-negative integers between 0 and 999 only.

  2. Write up a code snippet in a separate file (in C, as a multi-line string). This should look similar to what you wrote in step 1.

  3. Identify the lines you want to animate and design the look of the animation

    1. This is up to you (be as creative as you want!), but make sure it’s consistent with the rest of the visualiser, and make sure it is true to the steps of the operation.

  4. Add a [DataStructureOperation]AnimationProducer class file under the animation-producer directory in the corresponding data structure directory in visualiser-src

  5. Code up the SVG animations for each line you want to animate – one method corresponding to each code snippet line you identified in step 3.

    1. Write a method that renders a code snippets you wrote in step 2. Make use of the renderCode(code: string) method.

    2. This involves calling addSequenceAnimation for animations that happen at the same time.

    3. TIP: Name AnimationProducer methods after the semantics of each line as opposed to its visuals. For example, .appendNode() as opposed to .showSVGAtLastPosition(). This will guide you on what the animation looks like, and decrease your chances of creating animations that are misleading.

    4. TIP: Before writing an AnimationProducer method, have a look to see whether other operations already have it.

  6. Instantiate the [DataStructureOperation]AnimationProducer class in the method you wrote in step 1 and render the code snippets.

  7. Call doAnimation (in the case that there is no corresponding code snippet line) or doAnimationAndHighlight (to highlight a code snippet line for the duration of your animation) on the AnimationProducer method and its arguments.

  8. Return the AnimationProducer from the method.

Info

If unsure, check out the linked list and binary search tree visualiser as reference.

...

Structs.sh features a RESTful API for content management, supporting the retrieval, creation, updating and deletion of lessons and quizzes as well as the management of users.

Endpoint Documentation

Our endpoint documentation is not on Confluence. To see it, start up the backend server (eg. on port 8080), then navigate to http://localhost:8080/.

...