WISE5 Design Documentation and Notes
- WISE Architecture
- New Features in WISE5
- Git Workflow
- Coding Conventions
- Unit and Integration Tests
- Troubleshooting
WISE is comprised of many components in one easy-to-install package. WISE solves common problems like user management, grouping, content delivery, student and teacher data management, and event data logging, and makes them available via applications like the Portal, Student Virtual Learning Environment, Teacher Classroom Monitor, Project Authoring Tool, and Researcher Tool. Most of the components are loosely coupled and can be extended or swapped with another similar implementation.
The server-side is written using the Spring Framework (Java), and communicates to the databases (MySQL, HSQLDB) using Hibernate/JDBC. It also stores static files like project content and students' uploaded assets in the file system. The client-side is written with HTML/JavaScript/CSS.
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. You can see the javadoc 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 is a web application written in Java using the Spring Framework. It connects to the underlying database using Hibernate and currently supports MySQL and HSQLDB.
WISE supports different user types (e.g. students, teachers, researchers, admins) and permissions (e.g. who can view/edit/share projects). The WISE portal handles user account registration and authentication by using 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 below).
The project is stored as a JSON object and saved in a project.json text file, along with resources like images and animations which are stored in the "assets" folder. Since the project can be stored on a file system, it can be compressed and shared between multiple WISE instances. Version control systems like Git can 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.
Periods, Workgroups
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 primary VLE is written as a client-side javascript application.
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, 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 with various useful features and shortcuts.
A teacher can launch the Classroom Monitor Tool to grade student work and manage student groups.
WISE5's primary Classroom Monitor Tool is written as a client-side javascript application.
WISE stores user information, classroom data, and event logs in the database. WISE supports MySQL and HSQLDB.
WISE stores curriculum and students' uploaded files (images, videos) on the filesystem.
Component Work
Events
Uploaded files
Annotations
Events
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/
We try to follow
- 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. 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...