WISE5 Design Documentation and Notes
- WISE Architecture
- New Features in WISE5
- Git Workflow
- Development Workflow
- Coding Conventions
- Unit and Integration Tests
- Troubleshooting
WISE server-side application (aka "Portal") solves common problems like user management, grouping, content delivery, student and teacher data management, and event data logging, and makes them available to client-side applications via a REST API. The Portal is written in Java using the Spring Framework, and communicates to the databases (MySQL, HSQLDB) using Hibernate and JDBC. It also stores static files like project content and students' uploaded assets in the file system.
WISE client-side applications are written with HTML/JavaScript/CSS using libraries like Angular and Material Design. These include the Student Virtual Learning Environment (VLE), Teacher Classroom Monitor, Project Authoring Tool, and Researcher Tool.
Read about the details of the database that is used in WISE here: https://github.com/WISE-Community/WISE/wiki/Database-Description
The server-side code, aka "Portal", is written in Java using the Spring Framework. This section describes the different components that comprise the Portal in more detail. You can see the JavaDoc for the Portal here: http://wise-community.github.io/WISE/apidocs/index.html
The portal manages user accounts and classroom runs and acts as a launch point for client-side applications like the VLE, Authoring Tool, and Classroom Monitor Tool. It connects to the underlying database for data storage and manages real-time communication between the different tools using WebSockets.
The key components in the portal are users, authentication, authorization, groups, projects, and runs. Projects can be authored by users with authoring permissions and run in classrooms by groups of students.
The WISE Portal supports different user types (e.g. students, teachers, researchers, admins) and permissions (e.g. who can view/edit/share projects and runs), user account registration and authentication by building on Spring Security.
A WISE Project contains the curriculum content and how they are sequenced together. For example, a project about Global Climate Change contains many activities in linear and non-linear order that the students must complete. The Portal keeps track of all projects in the database and displays them to the teachers so they can run them in classrooms (see "Runs" section).
Each WISE project is contained inside a folder. The main "manifest file" that describes the structure and content is stored in a JSON format in a text file named "project.json". Resources like images, videos, and animations are stored in the "assets" folder and can be referenced from the project manifest file.
Since the project is stored on a file system, it can be compressed and shared between multiple WISE instances. Version control systems like Git can also be used to track changes to a project and allow authors to revert to a previous version or allow researchers to see how the teachers changed the project over time.
You can download sample projects from wise5.org.
Once a teacher chooses a Project to use in their classroom, they can set up a Run of the Project. Their students can add themselves to this new Run and work on the Project using the Student Virtual Learning Environment (see below). Students can work alone or with their classmates. A student can be associated with multiple Runs by different teachers and carry over their account from year-to-year, which allows longitudinal studies.
WISE supports grouping users into 'Workgroups' (one or more students work together on the project) and 'Periods' (one or more students that belong in a teacher's class).
WISE stores student work in its own table as NodeState and ComponentState. There is also a table for storing user events like button clicks and interactions with the simulations. Students can also uploaded files like pictures and audio that they captured on their phone. These files are stored in the "studentuploads" directory on the server filesystem.
When teachers give scores and feedback to students, they are stored as "Annotations". How teachers interact with the Classroom Manager tool is stored in the events table for research.
A student's typical interaction with WISE begins with a student logging into the portal using a browser, finding the run that they're working on, and clicking on the "run project" button. This launches the Student VLE application, where the student can view the project content and answer questions.
The VLE can be implemented in many ways. WISE5's VLE is written as a client-side javascript application using Angular and Material Design.
A WISE author, typically a researcher or a teacher, can launch the Authoring Tool and make changes to a project.
A WISE Project is simply a collection of files (see "Projects" section), so in theory a text editor can be used to make changes to the project. WISE5's primary Authoring Tool is written as a client-side javascript application using Angular and Material Design.
A teacher can launch the Classroom Monitor Tool to view/grade/download student work and manage student accounts and groups.
WISE5's Classroom Monitor Tool is written as a client-side javascript application using Angular and Material Design.
The researcher can export student work for any run that they have been shared with via the researcher portal.
WISE5 is a major improvement of the Student Virtual Learning Environment (VLE), Teacher Classroom Management Tool, and the Project Authoring Tool. Many new features have been added, including adaptive navigation, planning activities, student notebooks, and real-time collaboration and notification tools. The new projects allow more customization and work across different device types and sizes. Changes to the portal expand WISE’s capabilities to interoperate with outside systems. You can read the WISE5 goals here.
The new student virtual learning environment (VLE) initializes the project, loads components (see below), and manages student data. The new responsive interface is designed to work across multiple devices and screen sizes. The VLE can also run in standalone mode inside a web page or be embedded in another learning management system.
The new authoring tool allows authors to create and edit WISE5 projects. WISE5 projects have a different project structure than WISE4. Various navigation mechanisms like branches, groups, and constraints can be authored.
The new grading tool allows teachers to easily see student progress and student work and get an overview of the class in the Dashboard view. You can read more on the WISE5 Grading Tool here.
Students can take notes, write reports, save bookmarks, and ask questions in their notebook as they work through the project. Students save their observations and ideas using text, image attachments, or image snippets of models and graphs in the project. Students can work on a report during the course of the project using the notes. A bookmark can be used to remember markers in the project so that the students can jump to it quickly. A question can be used to remember questions that students have, or places where they need help. You can read more about the notebook here.
Students can customize project structure and plan their activity by selecting and ordering from a collection of pre-authored steps. Planning activities are used in design projects where students choose the process for building their model. Authors can scaffold planning by giving students choices of items to add, and the choices can be constrained.
A "component" (equivalent to a "step" in previous versions of WISE) is an activity in WISE5 that allows students to read text, watch videos, draw diagrams, answer multiple choice questions, fill out a table, plot a graph, and more. Multiple components of same or different types can be displayed in the same page (aka "Step" in WISE5), and components can share data with each other (ex: between simulation and graph). You can read more about WISE5 components here.
WISE5 projects are no longer confined to the linear structure that WISE4 projects were restricted to. A step can now transition to any other step in the project when the next button is clicked. Authored "transition logic" chooses which step the student should go to next. Transition logic can be based on many parameters like whether they visited a certain step, whether they completed a certain step, what score they received on a certain step, whether they answered a certain step correctly, and others. This allows the project to support a choose your own adventure style of navigation.
The transition functionality allows WISE5 projects to properly support branching. A branch can be created by authoring a step that has multiple next transitions. Take for example a step with a multiple choice component that has 3 choices (Choice A, Choice B, Choice C). The step is authored so that it has 3 next steps (Step Apple, Step Banana, Step Coconut). The transition logic can be authored such that if the student chose Choice A and then clicked next, they would be transitioned to Step Apple. If the student chose Choice B and then clicked next, they would be transitioned to Step Banana. If the student chose Choice C and then clicked next, they would be transitioned to Step Coconut. Transition logic can be based on all sorts of parameters as mentioned in the Transitions section above.
The new event-logging system in WISE5 allows collection of detailed events that happen as the students work through the project, as the teacher uses the grading tool, and as the author edits the project content. Examples of events include when the student entered/exited a step, which controls the students used on a simulation, and when teachers provided feedback to students. The events can then be exported and analyzed by researchers for their study. You can read more about events here.
The new notifications system in WISE5 alerts students about new events as they are working on the project. These include new comments from their classmates on their discussion posts, new feedback from their teachers, and results of auto-scored items. In the Classroom Monitor tool, it alerts teachers about steps where students are getting stuck or individual students' performance based on certain criteria. The real-time communication system (see below) sends notifications to users in real-time.
WISE5 auto-saves students' work at set intervals to minimize lost work. WISE treats each save as a revision, and allows students to view and revert to previous revisions. Teachers and researchers can see how the students changed their work over time. The authoring tool and classroom monitor also save more frequently.
WISE5 tools allow students to have discussions and teachers to monitor students' progress in real-time. These tools are built on the WebSocket protocol and allows better collaboration between classmates.
WISE5 works on tablets and desktops of different screen sizes. On smaller screens, the interface adapts to fit and show only the important views. We use the Material Design framework to create modern, intuitive designs.
The student VLE, the teacher classroom monitor tool, and the authoring tool have all been re-built using AngularJS and share a lot of the codebase. This allows re-use of code and styles across the different tools.
WISE5 client-side applications are written with ECMAScript6 and makes use of the new features of the modern javascript language. We use the Babel transpiler to support older browsers. Go here to learn more about ES6.
We follow the git workflow model that is described on this blog: http://nvie.com/posts/a-successful-git-branching-model/. Basically, we commit to the 'develop' branch as we develop, and merge to the 'master' branch when we're ready to release.
The tech team at Berkeley loosely follows the Scrum practice. We practice code reviews, daily standups, and pair programming. We also try to write unit tests. Our sprint is generally two weeks long, and you can see our current sprint and product backlog here.
The general workflow for an issue goes like this:
- Person A creates a new branch with the name convention issue-XYZ-description
- Person A completes the issue, commits, and pushes to upstream
- Person A creates a Pull Request (PR) and assigns to Person B
- Person B reviews the PR and accepts or requests changes.
- When Person B accepts the PR, the changes are merged into the 'develop' branch and the issue is closed.
We try to follow these coding style guides:
- Google's Javascript coding style guide
- Google's Java coding style guide
- Google's HTML and CSS style guide
- Unit test naming conventions
WISE5 has unit tests and integration tests written using Karma, Jasmine, Protractor and AngularMock. We use a pre-commit hook to test changes before they are committed. Also, every commit to the code repository is tested using Travis CI and SauceLabs. You can see the builds here: here.
Behavior:
VLE does not load. The URL flickers. In the network tab, you see files loaded repeatedly.
Places to look:
- app.js. Make sure that the order of the elements in the list for require (in define([angular,... ) are the same as the order of the elements in the list in function(angular...