Skip to content

Modifying LETICIA's Source Code

Jump to bottom
Daniel Gacitúa edited this page Sep 26, 2022 · 5 revisions

Languages and Frameworks

Regarding the programming languages used in LETICIA, most of the code base uses JavaScript following the ECMAScript 6 standard (ES6). For the frontend, Vue templating format is used for the views (composed by HTML5, CSS3, and JavaScript ES6).

LETICIA uses the following major frameworks:

Directory description

LETICIA has the following directory layout:

├── docs                   // LETICIA Documentation
├── extras                 // Extra scripts
│   └── databaseScripts     // Database cleaning and populating scripts
└── src
    ├── client          // Frontend code
    │   ├── assets       // Frontend file assets
    │   ├── models       // Database model representations from backend
    │   ├── modules      // Frontend core modules (auth, event bus, routes, store, translations)
    │   ├── services     // Frontend core services (mainly connectors with API)
    │   ├── templates    // Frontend Vue templates
    │   │   ├── auth           // Authentication templates
    │   │   ├── formElements   // Form element templates
    │   │   ├── hubs           // User hub and admin hub templates
    │   │   ├── queryPlanning  // 'Short challenge' templates
    │   │   ├── questionnaires // Form templates
    │   │   └── search         // 'Extended challenge' templates
    │   └── trackers      // Frontend tracking services (keyboard, mouse, and scroll)
    └── server          // Backend code
            ├── assets        // Backend file assets
            │   ├── documents // Downloaded documents (scraped web sites)
            │   └── preview   // Preview documents
            ├── components    // Backend main components (web scraper and inverted index connector)
            ├── config        // Authentication configs
            ├── controllers   // Authentication controllers
            ├── middlewares   // Authentication middlewares
            ├── models        // Database model files (Mongoose)
            └── routes        // API routes (Express.js)

Considerations

LETICIA is released as open-source software and can be modified to tailor researchers' needs. In case of need to edit LETICIA's source code, please fork this repository. Pull requests of new functionalities and translations are welcome.

To deploy LETICIA locally in development mode, run the following command on the project's root directory:

$ npm run dev

Frontend

All frontend files are located on the client/ directory. They can be either .js or .vue files. Assets for images, JSON files, and PDF documents are stored on client/assets/ directory. Translation strings are stored on client/modules/translations.js file. The main frontend file is located on client/index.html.

Creating or editing view templates

All view templates must follow the Vue.js v2 format and must be located in the client/templates/ directory. View templates can import modules, services, or trackers if needed. For visual styling and layouts, the BootstrapVue framework must be used.

This is an example of a view template:

<template>
  <!-- HTML code -->
  <b-container id="new-template">
    <b-row class="text-center">
      <b-col>
        <h1 class="main-title">
          My new template
        </h1>
        <img :src="newImage"></img>
      </b-col>
    </b-row>
  </b-container>
</template>

<script>
/* JS code */
import Image01 from '../assets/image01.jpg';

export default {
  name: 'new-template',

  /* Reactive variables */
  data() {
    return {
      newImage: Image01
    }
  },

  /* Computed values */
  computed: {
    // Checks if user is logged in (or not)
    loggedIn() {
      return this.$store.state.auth.status.loggedIn;
    },
    // Returns current user object
    currentUser() {
      return this.$store.state.auth.user;
    }
  },
  
  /* Code that runs when the view template is created */
  created() {
    // (...)
  },

  /* Code that runs before the template is rendered in browser */
  mounted() {
     // (...)
  },

  /* View auxiliary functions */
  methods: {
    isUserLogged(): {
      return this.loggedIn;
    }
  }
}
</script>

<style scoped>
/* CSS code */
.main-title {
  font-weight: bold;
  color: #FF0000;
}
</style>

Event Bus

LETICIA uses the Event Bus pattern to transfer data between view components, especially between the main activity window and the navbar component. The Event Bus pattern is very similar to the publish-subscriber pattern, using a string identifier to determine to which event the event handler must react.

This is an example of an event emitter (using the leticia-current-task identifier):

import EventBus from '../modules/eventBus';

EventBus.$emit('leticia-current-task', { currentTask: true });

This is an example of an event handler (using the leticia-current-task identifier):

import EventBus from '../modules/eventBus';

EventBus.$on('leticia-current-task', (data) => {
  this.showCurrentTask = data.currentTask;
});

Backend

All backend code is located on the server/ directory, using JavaScript with ES6 syntax.

Extending the REST API

All endpoints of LETICIA's REST API are located in the server/routes/ directory. Endpoints are implemented using Express.js and use the async/await directive to run asynchronous code. The server/api1.js imports all endpoints and makes them available to the server/index.js main file.

Extending the database

In case of need to add additional collections/tables to the database, use the Mongoose framework and follow the schema available on server/models/ and server/db.js. LETICIA by default generates two databases: The "user" database for all login and sensible data about the participants and the "data" database for all the experimental data obtained from participants' usage of the platform.

OAuth login

LETICIA is compatible with OAuth SSO Login using one of these two providers: Google or Facebook. All relevant code can be found in the following files/directories:

  • server/config/
  • server/controllers/
  • server/middlewares/
  • server/oauth.js
Clone this wiki locally