Developer’s Guide

Version 5.10.0 - février 2023

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

The fonts used in this guide are licensed under the SIL Open Font License, Version 1.1. This license is available with a FAQ at: http://scripts.sil.org/OFL

1. UI and UX

https://material.io/design/

2. Frameworks & Tools

2.1. GNUstep

2.2. SOPE

2.3. JavaScript libraries

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

http://eslint.org/
http://standardjs.com
https://github.com/toddmotto/angularjs-styleguide
https://github.com/angular/material/blob/master/docs/guides/CODING.md
http://jshint.com/
https://github.com/angular/material/tree/master/docs/guides
We conform to Airbnb coding standards. Use jscs with the airbnb preset to validate your code style:
```
jscs -p airbnb *.js
```

For documentation, we follow the JSDoc3 standards:

jsdoc UI/WebServerResources/js/{Common,Contacts,Mailer,Preferences,Scheduler}/*.js -d Documentation/JavaScript-API

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.

For documentation, we follow SassDoc annotations.
FlexBox compatibility http://caniuse.com/#feat=flexbox

3.4.1. Fonts

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.

Temporarily set SOGoUIxDebugEnabled to YES;
Restart sogod;

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')
)

Overwrite the content of WebServerResources/css/theme-default.css with the content of the clipboard;
Restore the value of SOGoUIxDebugEnabled (NO or unset);
Restart sogod.

5. Version Control

https://devcharm.com/articles/46/improve-your-git-workflow/
https://github.com/angular/material/blob/master/docs/guides/CONTRIBUTING.md#-commit-message-format
Each commit should cover only one thing;
Begin the commit message with a single short (less than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description;
When fixing a bug, commit to the devel branch as well as the maintenance branch of the latest release version (named maintenance/x.y). When a ticket is associated to the bug, add to the description a line saying Fixes #1234.
git pull may introduce inconsistencies and problems. Replace it with the following alias:
```
git config --global alias.up '!git remote update -p; git merge --ff-only @{u}'
```

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