1. UI and UX

2. Frameworks & Tools

3. Code Style

3.1. Objective-C

  • To document the Web APIs, we follow the APIDOC standards.

    apidoc -f ".*\\.m" -i UI -o Documentation/JSON-API
  • When returning JSON from an object extending UIxComponent, use the following method:

    • (WOResponse *) responseWithStatus: (unsigned int) status andJSONRepresentation: (NSObject *) contentObject;

3.2. HTML

  • Localize your strings:

    <var:string label:value="I'm localized!"/>
  • Localize your attributes:

    <input type="text" label:placeholder="I'm localized!"/>
  • Reuse existing localized strings as much as possible. Otherwise don’t forget to update the English Localizable.strings file of the appropriate module.

3.3. JavaScript

3.3.1. Models (facades)

  • Move business logic into models and share them.

  • Keep it simple, separate server interaction and error handling from the model. That way model only handle data processing and code is easier to maintain.

3.3.2. Controllers

  • Functions not exposed in the controller must be prefixed with an underscore.

3.4. SASS/CSS

A @mixin is like a stamp: it creates a duplicated version of the property block (optionally) with arguments provided. An @extend appends the element you are extending to the property block. It is your "yes, and _" statement.

4. Building frontend

  • Install the latest stable release of Node.js

  • Install grunt

    npm install -g grunt-cli
    npm install -g bower
  • We need the SASS files of Angular Material to build our CSS. The git repository of Angular Material is included as a submodule of SOGo:

    git submodule init
    git submodule update
  • Generate the JavaScript and CSS files

    cd UI/WebServerResources
    npm install
    bower install
    grunt build

4.1. Defining an alternate color theme

SOGo relies on the theming system of Angular Material to define the colors of the Web interface.

To overwrite the default theme in SOGo, set the following parameter in /etc/sogo/sogo.conf:

SOGoUIAdditionalJSFiles = (js/theme.js);

Edit theme.js under /usr/lib64/GNUstep/SOGo/WebServerResources/js or /usr/lib/GNUstep/SOGo/WebServerResources/js depending on your platform and restart sogod.

If the configuration parameter SOGoUIxDebugEnabled is unset or set to NO in /etc/sogo/sogo.conf, you’ll need to generate a new theme-default.css stylesheet for the new theme.

  1. Temporarily set SOGoUIxDebugEnabled to YES;

  2. Restart sogod;

  3. From your favorite browser, open the JavaScript console and type the following:

    copy([].slice.call(document.styleSheets)
      .map(e => e.ownerNode)
      .filter(e => e.hasAttribute('md-theme-style'))
      .map(e => e.textContent)
      .join('\n')
    )
  4. Overwrite the content of WebServerResources/css/theme-default.css with the content of the clipboard;

  5. Restore the value of SOGoUIxDebugEnabled (NO or unset);

  6. Restart sogod.

5. Version Control

6. Testing

6.1. JSON API

One practical way to test the JSON API is to use curl. To do so, you need to enable SOGoTrustProxyAuthentication and configure HTTP authentifcation in Apache. You can pipe the result to jq to nicely format and filter the output:

curl -u username:password http://localhost/SOGo/so/username/Calendar/calendarslist | jq '.'
curl -u username:password -H 'Content-Type: application/json' -d '{}' http://localhost/SOGo/so/francis/Calendar/personal/71B6-54904400-1-7C308500.ics/save