Starting Development

Starting the agent for the first time

The first thing you need to do is follow the instructions for installing Pixelated for development.

After that take some minutes to familiarize yourself with the user interface! ☺️

Show me the code

To get a better feeling for the code base, let's try some smaller changes. Let's assume that we'd like to change the way subjects are displayed in the mail list. First we want to find the location in the code that renders the subjects. Start your favorite text editor and open pixelated-user-agent/web-ui/app/js/mail_list/ui/mail_items/mail_item.js. Find the method named render. This seems to be the right location. To verify our assumption, let's change the html content.

  this.render = function () {
      this.attr.tagsForListView = _.without(this.attr.tags, this.attr.tag);
      var mailItemHtml = templates.mails[this.attr.templateType](this.attr); // <-- here
      this.$node.html(mailItemHtml);                                         // <-- and here
      this.$node.addClass(this.attr.statuses);
      if(this.attr.selected) { this.doSelect(); }
      this.on(this.$node.find('a'), 'click', this.triggerOpenMail);
    };

Set the mailItemHtml to a fixed string like "found the subject location". The render method should then look like this:

  this.render = function () {
      this.attr.tagsForListView = _.without(this.attr.tags, this.attr.tag);
      // start of our change
      var mailItemHtml = "<span>found the subject location</span>";
      // end of our change
      this.$node.html(mailItemHtml);
      this.$node.addClass(this.attr.statuses);
      if(this.attr.selected) { this.doSelect(); }
      this.on(this.$node.find('a'), 'click', this.triggerOpenMail);
    };

Now let's make sure that all our changes in the front-end are automatically reflected on the page, by running:

vagrant ssh
cd /vagrant/web-ui
npm run watch

Go back to your browser and refresh the page. You should immediately see that your change is active.

Now that's nice. Congratulations. But what we really want is to change the way the subjects are displayed on every mail in the list, not to substitute the entire thing by a string. The template line we removed seems to produce some more html. But where to find it? As it says template perhaps the file views/templates.js might be start. The code snipped mentions templates.mails and in the mails declaration we see references to four files. The single.hbs is the one we are looking for, so let's open it.

<span>
    <input type="checkbox" {{#if isChecked }}checked="true"{{/if}} />
</span>
<span>
    <a href="/#/{{ tag }}/mail/{{ ident }}">
        <span class="received-date">{{ header.formattedDate }}
          {{#if attachments}}
            <div class="attachment-indicator">
              <i class="fa fa-paperclip"></i>
            </div>
          {{/if}}
        </span>
        <div class="from">{{#if header.from }}{{ header.from }}{{else}}{{t "you"}}{{/if}}</div>
        <div class="subject-and-tags">
          {{ header.subject }}
        </div>
        <div class="subject-and-tags">
          <ul class="tags">
            {{#each tagsForListView }}
                <li class="tag" data-tag="{{this}}">{{ this }}</li>
            {{/each }}
          </ul>
        </div>
    </a>
</span>

Lets undo the changes in mail_item.js and instead add a span around the header.subject and set the class to 'search-highlight'. It should look like this:

...
        <div class="subject-and-tags">
          <span class='search-highlight'>{{ header.subject }}</span>
        </div>
...

Now refresh your browser again to see the changes in effect.

Finally we would like to change the color of the highlighting. The pixelated user agent uses SASS to make handling styles a little bit easier. You can find the style sheets for the inbox in web-ui/app/scss/. The search-hightlight is defined in styles.scss:

.search-highlight {
  background-color: $search-highlight;
}

It references a color variable defined in _colors.scss

 $search-highlight: #FFEF29;

Change the color value to something else. You should be able to see the changes as you refresh the page. If the page is not automatically updated, make sure to rerun npm run watch.

For all Python changes, you will need to kill (Ctrl-C) the server and start the pixelated user agent again.

For most JavaScript or HTML changes, you will just need to reload the browser.

For most CSS or Handlebars templates changes, you will also need to run: $ cd /vagrant && make install_js

Next steps

The pixelated user agent is based on the reactive [FlightJS] (https://github.com/flightjs) framework and uses events as the primary way of control flow. New components are built with ReactJS.

The life of mail

How does that list of mails get populated? We only had look onto the JavaScript side of things, there is also the Python side for the service. When we say service we mean a python application that delivers not only the resources for the web application but also provides a REST api to access and send mails.

To give you a brief overview lets follow an email through the service.

• Some javascript calls the MailsResource in service/pixelated/resources/mails_resource.py
• The render_GET method asks the search engine for a list of matching mail ids. These mails are then request from the mail service.
• The mail service asks the soledad querier.
• The soledad querier fetches the mails from the soledad backend

For a broader view of the architecture, keep reading on.