This document contains all the requirements, constraints and the software architecture for the next release of MobileOrg.
All the links in this document are Org mode links. These are not resolved properly if you read this document in GitHub webview.
A view for habits should be available. The view should mimic like the completion view in agenda.
| References: | |
|---|---|
| GitHub | #103 |
| Architecture |
Markup supported by Org should be also supported by MobileOrg. A preview should be presented to the user whilst editing a note.
Org on the mac can link to Apple Mail messages. Those links could be used on iOS to link to the according message in iOS Mail.
Links to other Org files must resolve on iOS as long as those files are present resp. reachable.
Checkboxes should be displayed as actual checkboxes and should be checkable.
| References: | |
|---|---|
| GitHub | #36 |
| Architecture |
Properties known to org like tags or internal links should be autocompleted in the editor.
List of properties for autocompletion:
- tags
- internal links (using internal id or name)
- dates
- Keywords
- scheduled
- deadline
- name
- id
| References: | |
|---|---|
| GitHub | #149 |
| Architecture |
Configurable Agenda views must be provided to the user.
Furthermore Agenda views already configured in Org mode should be transfered to MobileOrg.
| References: | |
|---|---|
| GitHub | #145 |
| Architecture | agenda |
Agenda should also integrate with iOS Calendar/Reminders. The integration works only
in one way - it just shows items from Calendar/Reminders. It neither does modify user’s
org-mode files nor it modifies iOS Calendar/Reminders.
Home screen of MobileOrg consists of different widgets that can be enabled/disabled and rearranged by user. Generally there are two types of widgets - buttons (that just lead to another view) or mini-views.
On the example image there are 5 widgets. One named ‘Forecast’ is a widget with a custom view. The others are simple button widgets that when clicked open another view.
Notes:
- Names used in this mockup are just examples.
- Mockup is heavily inspired by OmniFocus home screen (especially ‘Forecast’ widget).
Transitions between views behave in the same way as they behave in current version of MobileOrg.
Also iOS Calendar should have special widget view for home screen (similar to the ‘Forecast’ widget on Home Screen Mockup).
Clicking ‘Files’ button opens ‘Files’ view containing the list of all files and navigate/edit them. Useful for people with tons of org files.
Custom view is just a list of files. It’s like ‘Files’ view is injected to Home Screen. Useful for users with few org files.
Clicking ‘Refile’ button opens ‘Refile’ view where user can refile items from the ‘inbox’. Usually inbox is used as a target for capturing and contains items that user should refile (move to a proper place).
Some people use separate file for the inbox. But others use special heading in general org file.
So we should allow users to configure inbox file name (defaulting to
inbox.org) and optionally header containing inbox items (for example,
General/Inbox).
Also possible to implement inline widget variant.
Note that Inbox can be used as a target for Capturing.
| References: | |
|---|---|
| GitHub | |
| Requirements | refiling |
| Architecture |
Clicking ‘Tags’ button opens ‘Tags’ view containing the list of all tags. Clicking on any of the tags opens all of items tagged with clicked tag.
Also possible to implement inline variant.
Clicking ‘Nearby’ button opens ‘Nearby’ view containing the list of all
items that are tied to certain location near current location. Item is
tied to certain location via LOCATION property. We might also use
LOCATION_RADIUS (with the default set to 500 m).
With iOS 8 Apple has introduced so called Extensions. Extensions could be Share-Extensions or Today-Extensions.
Captures could be triggered either by an today-extension or by sharing content from another app. A selection of capture-templates should be presented to the user.
Capture templates already defined in Org should be accessible within MobileOrg as well.
| References: | |
|---|---|
| GitHub | #140, #106 |
| Architecture | capture |
Clocking should be available on MobileOrg too. The feature must be easily accessible by the user. If possible without the need to open the app and to search a matching task.
| References: | |
|---|---|
| GitHub | #25 |
| Architecture |
It should be possible to create new captures by triggering Siri. Captures could be:
- Tasks
- Notes
| References: | |
|---|---|
| GitHub | #148 |
| Architecture | Siri |
Some org files are encrypted on the user’s desktop machine. These files must be readable on the iOS device as well. As the phone is a protected single-user system, it ight not be necessary to encrypt the files in the local storage.
Encyption methods used on desktop:
- symetrical encryption (supported by
org-mobile.el) - GnuPG
For events triggered by SCHEDULED and DEADLINE a notification must be sent to the user. This should be configurable by the user.
- First alert (amount of time)
- Second alert (amount of time)
- Switch notificatons (on/off)
| References: | |
|---|---|
| GitHub | #64 |
| Architecture |
Sync functionality should be accessible at every time (in every scope) if possible.
| References: | |
|---|---|
| GitHub | #15 |
| Architecture |
The user must be able to take actions on notes. These actions mirror the behaviour of Org on the desktop.
Possible actions:
- set/unset TODO/DONE or individual keywords
- set/unset SCHEDULED
- set/unset DEADLINE
- set/unset tags
| References: | |
|---|---|
| GitHub | #51 |
| Requirements | widgets |
| Architecture |
Refiling like it is available in Org should be available in MobileOrg too. Supported by selection lists which show the refiling targets.
Level of available refiling targets should be configurable in Settings.
| References: | |
|---|---|
| GitHub | #109 |
| Requirements | widgets |
| Architecture |
Creating new notes are handled as Captures. All configured templates must be accessible if it makes sense in the current scope.
The location of captures should be stored with the note.
| References: | |
|---|---|
| GitHub | #104 |
| Architecture |
Whilst capturing (or editing) a Note there should be shortcuts which allows to enter SCHEDULED or DEADLINE times easily.
| References: | |
|---|---|
| GitHub | #33 |
| Architecture |
Sharing content with other applications. Sharing should share all content.
| References: | |
|---|---|
| GitHub | #108 |
| Architecture |
When the user edit an existing note a Logbook entry must be added to the note if configured.
| References: | |
|---|---|
| GitHub | |
| Requirements | capture |
| Architecture |
If Org mode is used as a writing-environment, it would be a nice addition if MobileOrg could provide support for writing whilst the user is on the go. Such support could be provided by:
- Shortcuts for markup or cross references
- Keyboard support for markup
- Allow editing of a whole item collection (document) in one screen
| References: | |
|---|---|
| GitHub | |
| Requirements | markup, links |
| Architecture |
There are many terms which are used already in Org mode. Many of them are used with different meanings in the context of MobileOrg. The introduction of a dictionary should help with this.
The terms in the following table could help in finding a terminology for MobileOrg.
| Org mode | MobileOrg |
| Agenda | Dashboard |
| Org File | Item Collection (Notebook) |
| Subtree | Item |
| Scheduled | Start Date |
| Deadline | Due Date |
|---|
There are plenty prossibilities to store information locally on the iOS device. Core Data seems as the best to start with as it allows to build easily the object model needed for storage. If at a later stage another storage-method is added, the Core Data object model could be easily reused.
The current approach to access Org files is by utilising org-mobile.el,
because it is the most reliable solution in regards to occurence of
conflicts.
Other methods could be plugged in at a later stage by making use of plugable backends.
The current version of MobileOrg supports only syncing over org-mobile.el.
This method is reliable and robust but needs some attention from the user.
It is necessary to org-mobile-push before leaving the computer and
triggering a org-mobile-pull to sync changes once the user is back at the
computer.
Demand is high for alternative approaches like working directly with org-files without any stage area and using git. Git is a popular choice because many users already use git to sync org files with desktop machines.
With org-mobile.el a staging area is needed. At the moment only WebDAV and Dropbox are supported. There is popular demand for alternative cloud services like iCloud. These services could be utilised for additional sync services as described above. Because of that, the staging area is referenced as cloud-storage within this document.
Regardless of the method chosen for syncing an internal storage is needed. The currently selected choice is Core Data. But as there are alternatives already present today an module-approach makes sense for internal-storage, too.
Possible Backends for MobileOrg could be:
- Sync - Backends
org-mobile.el- plain org-files
- git
- rsync over ssh
- bit torrent
- Cloud - Storage
- WebDAV
- iCloud
- Dropbox
- Box (which has conflict resolution built in?)
- GitHub
- Internal - Storage
- Core Data
- Native Storage
- Org Files
Plugging at compile time should be sufficient. There is no need to allow plugin of backend-modules at runtime.
Backend modules must be configured individually therefore it must be possible to register modules to settings
Settings consist of a static and dynamic part. In the static part it’s possible to configure app properties like behaviour of app badge. The dynamic part consists of settings individual for each module which has registered for configuration-settings. Possible entries for dynamic settings could be:
- Storage Backend
- Sync Backend
- Cloud Storage
- Internal Storage
- Encryption Provider
To support settings-registry protocols should be used.
If org-mobile.el is extended to transfer also Org configuration these setting could be incorporated into Settings as well. Settings which could be set on the desktop machine must occur in Settings in a seperate block.
Examples of settings which could be set on desktop:
- Logbook in Drawer (
(setq org-log-into-drawer 'LOGBOOK)) - Capture Templates
Org mode’s Agenda works as a container where the information cluttered in the many org files is collected and displayed to the user in an organised way.
The iOS’ UI works completely different to the UI Emacs serves. To provide a way where Org’s agendas could be reused within MobileOrg would complicate the software architecture. Configurable Agendas could be solution to fulfil the requirement in some way.
Siri could not be utilised by SiriKit as the necessary keywords as ‘remind me’ or ‘take note’ are reserved for the use with the internal Reminders and Notes applications.
One way to get Siri work with MobileOrg is to create a list in Reminders resp. a folder in Notes and set them as default. MobileOrg would then listen to this list or folder and if a new item is present it would move the item as a new capture to it’s internal store.