This is an actual org file - feel free to play around with it! (Don’t worry about messing it up - your changes won’t be saved, so just refresh the page to reset it)
This header has some description text and a couple subheaders. Look through the next few top level headers to learn more about organice.
When you select a header, the “header action drawer” appears. The first two icons in this drawer edit the header and description respectively. Try editing this header.
Title and Description fields are not edited as raw text by default. Instead, a semantic editor comes up when editing them. To edit raw values, click the ‘edit’ icon, again.
If you want the “header action drawer” to disappear or to deselect the current header, tap onto the title (or empty space) in the application’s headerbar.
- Pen: Edit header title
- Pen in square: Edit header description
- Tags: Modify tags
- Properties: Modify properties
- Expand: Narrow to subtree (Narrowing means focusing on this header, making the rest temporarily inaccessible.)
- Plus: Create new header below
- Mail: Share this header via email
- Calendar 1: Set deadline datetime
- Calendar 2: Set scheduled datetime
- Hourglass: Clock in and out (Start and stop the clock)
- File Export: Refile this header to another header
- Add a note: Add a time-stamped note to the current header (
org-add-note).
This header has a few TODO items as subheaders.
This interactive tutorial helps you get to know organice really quickly.
To advance the todo state of a header, swipe right on it until the background turns green.
Try advancing the todo state of this header a few times!
There’s also a setting once you’re signed in to enable tapping on the TODO label itself to advance the todo state. Its off by default because I thought the behavior would be confusing unless explained, but I recommend turning it on!
organice also supports custom todo states (if declared at the top of the file). Swipe right on this header a few times.
Note that when the cycle restarts, it defaults to the first set of todo states. Manually edit the header to get back to a different todo state cycle (more on editing headers below!)
Custom org-todo-keywords keyword sequences can have finish states. They are colored appropriately. You can see that TODO and START headlines are colored red whereas DONE and FINISHED headlines are colored green.
organice has solid documentation, including frequently asked questions: https://organice.200ok.ch/documentation.html
#organice on IRC Libera.Chat, or #organice:matrix.org on Matrix.
The next button in the header action drawer will bring up the tag editor.
This editor lets you add, modify, and reorder tags, as well as giving you easy access to all tags in the file.
Try it out on these headers:
The next button in the header action drawer “narrows” to a header, hiding all others and promoting it to the top level. Press the button again to “widen”.
Narrowing can make it easier to concentrate on a single heading or topic by eliminating clutter. It can also be used to limit the range of operation of a search command.
This is purely visual - your Org file isn’t affected under the hood.
Example: You can narrow on the “Groceries” list when you go to the grocery store. Give it a shot on this grocery list:
- [ ] Mangoes
- [ ] Dark chocolate
- [ ] Carrots
To add a new header, press the + button in the header action drawer
To remove a header, swipe left on the header until the background turns red.
To move a header, click on the four-way arrows button at the bottom of the screen with a header selected. 6 buttons will appear for moving headers.
The center 4 move the header up, down, left, and right. The 2 outermost buttons move the header and its entire nested subtree.
Give them a try on these nested headers to get a feel for how they operate:
The “cloud” button in the lower left hand corner syncs changes to your chosen sync service (Dropbox, GitLab, or WebDAV).
If there’s a newer version on the server and no local changes, it’ll pull.
If there’s no newer version on the server and there are local changes, it’ll push.
Otherwise, it’ll ask what you want to do.
This button isn’t enabled in this demo :)
If you’d like to automatically push changes as you make them, you can enable “Live sync” in settings.
When you’re signed in, you’ll have undo and redo buttons in the
headerbar.
organice has native support for viewing and editing tables.
Try playing around with this one by first clicking on the table:
| Dog name | Age | Weight (in lbs) | Parent | Score (1-10) |
|---|---|---|---|---|
| Eloise | 3 | 5.1 | Erin | 15 |
| Starla | 15 | 40 | Sarah S | 15 |
| Rex | 15 | 45 | Sarah S | 15 |
| Maz | 1 | 55 | Brittany | 15 |
| Clooney | 0.1 | 4.8 | Sarah R | 15 |
| Murphy | 0.5 | 25 | Jordan | 15 |
When a table is selected, the table editor is opened.
Below the table a table-specific action drawer appears.
For the icons to trigger any actions, you first need to select a table cell.
The leftmost icon allows you to edit a cell.
In the Middle, the top two icons let you add and remove rows. The bottom two icons let you add and remove columns.
On the right side, the four-way arrow buttons allow you to manipulate tables by moving rows and columns.
Press up and down to move rows, and left and right to move columns.
organice has native support for displaying plain lists and checkboxes.
Plain:
- Plain list item 1
- Plain list item 2
- Sub item 1
- Plain list item 3
Ordered:
- Ordered Item 1
- Ordered Item 2
- Sub item
- Ordered Item 2
Checkboxes:
- [-] 1 [1/2]
- [ ] 1.1 [0%]
- [ ] 1.1.1
- [X] 1. 2
- [ ] 1.1 [0%]
- [X] 2
First, create the first list item by editing the description of a header. When you close the “edit description” modal, you can manipulate the list item with native list manipulation functions. The UX is analogous to manipulating a header. Here’s what you can do:
- Add new list item
- Remove list item
- Move list item up
- Move list item down
- Move list item left
- Move list item right
- Move list subtree left
- Move list subtree right
- Edit list item title
- Edit list item contents
- Pen: Edit list item title
- Pen in square: Edit list item contents
- Plus: Create new list item below
- Cross: Delete list item
organice has native support for displaying and editing timestamps.
Try tapping on the timestamps below to get a feel for the editor:
<2018-09-17 Sun>
[2018-09-17 Sun]
[2018-09-17 Sun +1d]
[2018-09-17 Sun 10:00-11:30]
<2018-09-17 Sun>–<2018-09-25 Tue>
Org has the ability to track the consistency of a special category of TODO, called “habits.” From the upstream doc: A timestamp may have minimum and maximum ranges specified by using the syntax .+2d/3d, which says that you want to do the task at least every three days, but at most every two days.
Example timestamp: <2009-10-17 Sat .+2d/4d>
organice supports parsing and preserving the minimum/maximum range timestamps. Alas, only the minimum range is handled as a repeated task. There’s no UI for the maximum range, it can be edited as raw text. Also, there is no UI to show how well a habit has been exercised.
organice recognizes various types of hyperlinks automatically which Emacs Org mode would not necessarily do. That makes sense, because mobile devices, or browsers, enable a different feature set.
For example, when you read this in organice, then the text https://organice.200ok.ch will implicitly be rendered as a clickable link (as it would be in Emacs Org mode). The same also works for other web links like www.200ok.ch, email addresses like [email protected], and different kinds of phone numbers. For these, Emacs Org mode doesn’t create an explicit link, but organice can and does.
International/US phone numbers:
- 123-456-7890
- (123) 456-7890
- 123 456 7890
- 123.456.7890
- +91 (123) 456-7890
Swiss phone numbers:
- 0783268674
- 078 326 86 74
- 041783268675
- 0041783268674
- +41783268676
- +41783268677
organice has native support for viewing and editing property lists. To bring up an editor, expand the PROPERTIES drawer below and tap on any of the properties.
organice has native support for adding and editing DEADLINE and SCHEDULED items. It also supports repeaters and delays. Check out these examples:
DEADLINE means that the task - most likely a TODO item, though not necessarily—is supposed to be finished on that date.
SCHEDULED means that you are planning to start working on that task on the given date.
Scheduling an item should not be understood in the same way that we understand scheduling a meeting. Setting a date for a meeting is just a simple appointment, you can mark this entry with a simple plain timestamp, to get this item shown on the date where it applies.
Deadlines and scheduled items produce entries in the agenda when they are over-due, so it is important to be able to mark such an entry as done once you have done so. When you mark a ‘DEADLINE’ or a ‘SCHEDULED’ with the TODO keyword ‘DONE’, it no longer produces entries in the agenda.
For simple appointments, it is enough to mark the entry with a simple plain timestamp. This will still show up in the agenda.
- State “DONE” from “TODO” [2019-01-03 Thu 15:35]
The +1w is a repeater; the intended interpretation is that the task has a deadline on ‘2019-01-10’ and repeats itself every (one) week starting from that time. You can use yearly, monthly, weekly, daily and hourly repeat cookies by using the ‘y’, ‘w’, ‘m’, ‘d’ and ‘h’ letters.
With the +1w cookie, the date shift is always exactly one week. So if you completed the TODO for three months, marking this entry DONE still keeps it as an overdue deadline. Depending on the task, this may not be the best way to handle it. For example, if you forgot to call your father for 3 weeks, it does not make sense to call him 3 times in a single day to make up for it. Finally, there are tasks, like changing batteries, which should always repeat a certain time after the last time you did it. For these tasks, Org mode has special repeaters ++ and .+. For example:
On the deadline date, the task is listed in the agenda. In addition, the agenda for today carries a warning about the approaching or missed deadline, starting a defined time period before the due date (see settings “Default DEADLINE warning period”), and continuing until the entry is marked as done.
You can specify a different lead time for warnings for a specific deadlines using the following syntax. Here is an example with a warning period of 5 days ‘DEADLINE: <2004-02-29 Sun -5d>’.
In case the task contains a repeater, the delay is considered to affect all occurrences; if you want the delay to only affect the first scheduled occurrence of the task, use ‘–5d’ instead.
In the settings, there is an option to display deadline values on each headline.
organice supports something like Org capture in the form of customizable, quickly accessible buttons for creating new headers.
Click the button in the bottom right corner of the screen to see some examples. The first button, the lemon, will create a new entry in the “Groceries” list below this. The second button adds an entry to a more deeply nested header.
Once signed in, you can set up capture templates that specify header paths (and various other configurations). If the list is empty, the content will be inserted at the end of the file, or the beginning if the prepend option is selected. These capture templates will sync between your devices if you enable settings sync.
Below, there is a button to open up a generic search and a task list. The modal opens “Search” by default, but remembers what was opened last. If there are open clocks, a third tab “Clock List” is added
Tap a header in the view to jump to it.
Using the filter input, you can search for headlines. Specifically, you can search for headline text, TODO keywords, tags, and orgmode properties. It also supports alternatives, and you can exclude headlines by negating a filter.
When a header is narrowed, and the user uses the ‘search’ or ‘task list’ feature, then the searched header list is automatically narrowed to only subheaders of the originally narrowed header.
After entering a search string, you can bookmark it using the ⭐ button.
Bookmarked search strings populate the suggestions if no search string is entered into the input field.
Bookmarks are saved by context, so there are separate bookmarks for search, task-list, and refile.
There are at most ten bookmarks for a context. Newly saved bookmarks are inserted at the top of the list. If the list gets too long, the last search strings are dropped. Duplicate bookmarks are dropped too. The list of bookmarks is ordered by last used.
Bookmarks are unaware of file context. Therefore, you always have the same bookmarks.
- In the task list, you can tap on the date to switch to a more readable relative date format.
- The task list shows only tasks - i.e. headlines with a TODO keyword are displayed.
- The tasks will be sorted by state and then date.
You can simply search for
TODO check out organice|orgmode
to filter for tasks containing these words. The pipe symbol (|) is a logical OR. The filter is a smart-case search:
- Lower-case words mean that the filter ignores the case.
- If a word contains upper-case letters, the filter is case-sensitive.
The following example searches for headlines containing START or FINISHED keywords and the string “states are”. You can also use single-quotes.
START|FINISHED "states are"
The next example excludes DONE headlines but requires the tag fun.
-DONE :fun
You can exclude text strings, tags, and properties as well by prepending the minus sign (-).
You can search for headlines with defined properties:
TODO :blocked_by: :assignee:nobody|none
This filters headlines having a property blocked_by (with any value) and a property assignee with a value containing nobody or none.
You can also negate filters by prefixing them with -. For example, if you want to search for all headers that are not DONE:
-DONE
You can also search time ranges on headers with planning items (SCHEDULED and DEADLINE), plain active timestamps or clocked work time.
The time related filters are:
scheduled(shorthandsched)deadline(shorthanddead)clockdate
date is a shorthand to search for planning items (SCHEDULED and DEADLINE) and plain active timestamps at the same time.
These time related filters work on time ranges indicated by START..END where START and END support the following units:
h: Hoursd: Daysw: Weeksm: Monthsy: Years
START and END can both be omitted to search for an infinite timespan into the past or future. Both can be used with digits to quantify the amount (i.e. 2w for two weeks). For both, the digit can be omitted to refer to the calendar unit instead of a time duration (i.e. w is the current week using the Western Traditional system [from Sunday to Saturday]).
There are two special units that need no quantification:
today: Current datenow: Current time
Next to units, START and END can also be expressed in dates like. Dates can be expressed by:
YYYY(i.e. 2020)YYYY-MM(i.e. 2020-11)YYYY/MM(i.e. 2020/11)YYYY.MM(i.e. 2020.11)YYYYMM(i.e. 202011)YYYY-MM-DD(i.e. 2020-11-17)YYYY/MM/DD(i.e. 2020/11/17)YYYY.MM.DD(i.e. 2020.11.17)YYYYMMDD(i.e. 20201117)
Some examples on how to use time ranges:
clock:..searches for all items with time clocked. This includes headers that have time logged on their children.clock:nowsearches for currently clocked in headers.
sched:wsearches for all scheduled items in the current week (same for other units).dead:..wsearches for all deadlines between now and the end of the week.date:todaysearches for all planning items (scheduled and deadline items) as well as items with active timestamps.date:1w(equivalent todate:..1w) searches from now to one week in the future.sched:2m..wif both ends of the range are relative, they refer back to the current moment. So this searches for all scheduled items between two months before now to the end of the current week.
Note that negating time ranges is not implemented.
To search for the description of your headlines, use desc or description:
desc:"search term"
If you want to search for multiple terms, you can combine them like so:
desc:term_1 desc:term_2
You probably noticed that organice provides suggestions for your filter. After space, -, :, and | you can tap on the completion – no need to type the tag, property, etc.
organice has a basic agenda view that you can access by tapping the calendar button at the bottom of the page.
Tap a header in this view to jump to it, and tap on the date to switch to a more readable relative date format.
Due and overdue items with deadlines and a schedule show up on today’s entry. Entries with just an active timestamp are shown only on exactly the day of the timestamp. Hence, a ‘meeting’ or an ‘appointment’ should get an active timestamp whereas a TODO often will be scheduled or even has a deadline.
More information on that in the org manual.
Examples:
<2020-02-17 Mon>
organice pulls down your org files from Dropbox, GitLab, or WebDAV. Click the “Sign in” button in the upper right hand corner to sign in with either of them and authenticate organice.
The first time you push changes from organice back up to your chosen sync service, organice will make a backup of the original file first. It’ll be named {your-file-name}.organice-bak. Dropbox keeps a full version history of your files for you, but this is an additional precaution in case something goes wrong pushing the file back up.
Generally, when working with distributed Org files, we’re recommending to put them under version control and to check for bugs and racing conditions between clients.
organice supports using multiple files.
Default behaviour:
- When you first open a file it is loaded from the backend. At this point the file is persisted to local storage. It will be loaded from there on future application starts. To ensure consistency whenever a file is opened it will be synced with the backend.
- Agenda, Refile, Search and Task List by default show results from the currently viewed file.
You can adjust these defaults on a file per file basis by creating file settings in the settings menu.
You don’t log in to organice directly because organice doesn’t have a back end - it operates completely client side using Dropbox, GitLab, or WebDAV as back-ends for storage.
organice supports a flexible mechanism for capturing using URL parameters. This mechanism integrates very nicely with the new Siri Shortcuts feature in iOS 12, allowing you to use Siri to execute capture templates.
You can use this sample Shortcut to get started with this right away in iOS 12. Open the link on your iOS device and click “Get Shortcut”. Then open up the Shortcuts app and edit the template by following the directions in the comments. Then record a Siri trigger and you’re good to go!
Alternatively, you can take advantage of the URL parameters yourself to build your own custom capture mechanism. You can find more details about this in the README file.
If you’ve finished this interactive tutorial, but have further questions, we have you covered! There is additional documentation which contains more comprehensive and formal documentation, including installation instructions, deployment guides, contribution guidelines, and technical details about the project’s architecture and development process. This file is aimed at both users seeking in-depth information and developers interested in contributing to the project.