Repository navigation
User Guide
Note
The user guide is supposed to give you the basic knowledge to understand and use the core functions of the program.
It is meant to be read from top to bottom, as it may require things explained earlier.
If you want to, you can skip the [Advanced] topics as they are not required again later in the guide.
Nevertheless, you will learn the full functionality by using the program.
Double click on OrganizationDataMangement.exe or execute python main.py, depending on your type of installation, to start the application the first time.
It will automatically open a new file so you can hop right in.
It should look something like this:
This example will run you through the steps to create a new person, address, and organization and how to connect them in the end.
Furthermore, it will show you the different search features and how to use them.
The programs layout is very simple:
- Menubar: Lets you, for example, open an existing file, create a new file, or change settings.
- Tabbar: Switch between the different tabs
- Content: Changes depending on the tab you're currently looking at
- Statusbar: Shows status messages and file metadata
ODM is designed to be used as a floating, vertical window.
Anyhow, you can maximize the window, if you want to.
Switch to the Person tab and click on Add at the bottom.
This will open a new window:
Tip
Scroll down to see all the fields.
Here you can enter details for the person.
The Entry Name, Note, and Derivatives fields exist for the Person, Address, and Organization entries.
You will recognize them later.
Everything between the Name and Note field is specific to the Person.
The only required input (same applies to Address and Organization) is the Entry Name (just called Name in Address and Organization).
Multiple entries can have the same name, but this isn't recommended.
If you really need to, you can add a Note to differentiate between the entries, in this case.
The switch to the right of the fields allows you to enable or disable the specific field.
If it is enabled, you can add a text into the field.
Clicking into a disabled field will automatically enable it.
Disabling the switch will delete all the contents from the field.
This switch is specifically interesting for the Derivatives feature, explained later.
After entering the information, you need to click on Save at the bottom, which will close the window.
Tip
The * at the start of the window title indicates that there are unsaved changes.
Caution
If you click on Abort or close the window, your changes will be gone!
You should now see your newly created person in the table:
The green, downward facing arrow next to name indicates that the table is sorted by name in alphabetical order.
Clicking on name will reverse the order.
Moreover, you can click on any other category to change the sorting.
The null entry indicates that the field is empty.
Clicking on an entry once will select the entry.
Furthermore, only one entry can be selected at a time.
While an entry is selected, the button Edit, Duplicate, and Delete on the bottom will become active.
Clicking on Edit will open the same window as before with the stored values.
Duplicate and Delete should be pretty self-explanatory.
Double clicking on an entry will open it like the Edit button does.
Now, switch to the Address tab and click on the Add button at the bottom, to add a new Address.
This will open a new window which should already look very familiar.
The biggest difference here is the Other field:
Clicking on Add will add a new other field, so you can add additional details to an address.
Disabling a field using the switch will delete the field altogether.
Important
Currently, it isn't possible to search for a value stored in a Other field.
Let's create our first Address:
Click on save to add the new address.
Switch to the Organization tab.
To create a new organization, click on the Add button on the bottom.
Again, a new window opens:
Most of the fields should look familiar.
The only big difference is the Connections field.
This one is later used to create the links between a organization, person, and address.
At the moment, you cannot create a new connection, because the organization has not yet been created.
Important
Connections can only be added to an already existing organization.
To do that, first save the organization and then open it again, to be able to add a new connection.
Same applies to the Derivatives, which cannot be added on a not yet saved organization, person, or address, too.
Knowing this, we will first enter all the other details:
Now, click on Save and then open the newly created organization again by double clicking the entry.
This time, we can click on Add in the Connections field to create a new connection.
A new window opens looking like this:
It is prefilled with the first option.
Nevertheless, you can use the drop-down menu to select a different combination.
Though, in this case we only have one address and one person and therefore no other choice.
Click on Save to add the new connection.
Important
Every connection must be unique.
Therefore, the program will not let you create an already existing combination again.
In this case, the information field will turn red and show an error.
Important
Connections are independent from the Save or Abort actions of the entry!
This means, that adding, modifying, or deleting a Connection will be applied, no matter if you save the Organization or not!
[Same applies to derivatives]
So far, you have created a connection between a organization, a person, and an address.
One important thing we need to do next, is saving the file.
You can either use the File button found in the menubar on top or simply press CTRL+S.
This will open a dialog window asking you for a place and name to store the file, if you haven't saved it yet.
Otherwise it will overwrite the file with the new data.
Tip
If you're closing a file that has been stored before, it is possible to enable the Autosave on Close feature (enabled by default).
When you're trying to close a file or open another one, you can activate the feature, which will automatically save your file before opening a new one or closing the application.
Additionally, the activation state of the feature is permanently saved and will therefore stay activated or deactivated.
Important
Autosave on Close is not available on newly created files. You need to save them manually first!
Warning
The program will not automatically save the changes you did to the file on the disk.
It only works on a copy stored in the temporary memory.
Therefore, every change gets deleted after closing the program or when opening another file and not having Autosave on Close enabled!
It is therefore crucial, that you always manually save the file or use Autosave on Close before closing the program or opening another file!
Tip
If you have a file opened, that has been stored on the disk before, you can see the date and time when it has been saved the last time in the statusbar under Saved.
Right next to it, under Created, you can find the first time the file was saved.
Switch to the Search tab to perform any kind of search.
The top part of the screen lets you set search parameters and settings, while the lower part shows the results:
Tip
The divider can be adjusted by dragging with the mouse.
Tip
Double clicking the divider will set it back to the default position.
The upper half of the tab lets you set different search parameters.
First, you can enter a text which should be searched for.
Important
The text entered is case sensitive.
Tip
You don't need to press the Enter key or something else.
The results update automatically while you type or make any other changes.
The Search in Organization properties, Search in Person properties, and Search in Address properties fields let you specify in which columns the text should be looked for.
The Select All, Unselect All, and Invert Selection buttons can help you narrow your search down quicker.
For example if you want to look for organization with 'My' in the name, but 'My' in other columns should be ignored, you do the following:
- Enter
Myin the search field on the top. - In the
Search in Organization propertiesfield click on thenametoggle to disable it (for now). - Click on
Invert Selectionso thatnamein the organization field is the only active field.
You should now only see theMyShopresult (that's the only one existing right now, but you get the point).
Apart from that, there are three more fields called Search in Organization, Search in Person, and Search in Address.
These options allow you to filter for connection requirements.
These can be applied standalone or on top of the text search explained before.
Additionally, you can use all of the filters at once (though that wouldn't make much sense).
For example if you want to search for all organizations that use your Empire State Building address, select Empire State Building in the Search in Address field.
You should now see your MyShop organization, as this one is connected with the Empire State Building address.
Furthermore, you can also see the persons that are connected to the 'Empire State Building' address.
To see those results, we need to talk a bit more about the lower part of the screen in the next section.
Tip
The two buttons Reload Results and Reset Search at the bottom of the search parameters let you either reload the results according to your search parameters or reset all of the search parameters.
The reload button might help if you're missing a specific result in the list or a result wasn't updated correctly.
Please create an issue in this case, so the bug can be investigated.
On the lower part of the screen are the search results.
Without any search parameters, all of the entries will be shown.
Note
The results show all entries, even Derivatives.
This way, you can directly find and open a specific derivative without going through all the parents.
The Organization, Person, and Address buttons will let you switch between the different tables.
Important
The results are not all shown in one table.
They're separated into the Organization, Person, and Address tables respectively.
At the bottom of every Organization, Person, and Address edit dialog is a Derivatives field.
Here, you can create a new derivative of an already existing entry, by clicking on Add.
This will open a new window with the exact same features as the original entry.
Tip
You can create as much derivatives of the same parent or in a chain as you want.
There is no limit.
Important
Derivatives are not shown in the main window's tables.
You can only find them either in the settings or the derivatives field of the parent's entry.
The feature helps you organize similar entries in an efficient way without entering redundant data.
Additionally, changes in the parent automatically affect all derivatives.
But the best way to learn the possibilities is by going through an example:
Switch to the Address tab and open the Empire State Building entry.
Scroll to the bottom and take a look at the Other entry we did earlier: Room: 8002
Imagine we now have two different rooms at the same address, that we want to connect with organizations and persons.
One option would be to duplicate the existing entry and just modify the Other entry.
But as we want to reduce redundant data, we're using derivatives instead.
First, remove the Other entry with the room number from the current entry by disabling the switch.
The Other list is empty now.
After that, you save the entry and open it again.
Important
Derivatives always use the last saved state of their parent as a base.
Therefore, changes that have not yet been saved will not be reflected in the derivatives window, before you save them!
Now you click on Add in the Derivatives field.
This opens a new Address window prefilled with the parent's values:
As always, you need to provide a name for the entry.
We call it Empire State Building and write Room 8002 into the Notes section to make it easier to differentiate and find in future selections.
The switch next to each field now has an additional meaning.
Disabling it will not delete the value, but derive it from the parent (and the parent's parent and so on, if that's the case).
If the parent's value isn't set, the derivatives value will be empty as well.
On the other hand, enabling the switch will allow you to overwrite the parent's value.
It is prefilled with the derived value, but it can bet set to any value (including left empty).
Note
As long as the switch is disabled, the value will always be derived.
If the parent's value changes, the update is automatically reflected in every child.
Tip
Derivatives work in a tree structure.
The best way to use them is by refining your entries further with every step (e.g. by adding a room number in a derivative instead of removing one).
To finish this derivative, we add the room number to the Other field:
Now click on Save to save the changes and close the window.
Important
Every derivative is handled on it's own.
This means, that saving a derivative and clicking on Abort in the associated parent right after will still apply the derivative's changes!
[Same applies to connections in the Organization dialog]
You're now back in the parent entry.
Now, we duplicate the derivative value, that we just created, by selecting it and clicking on Duplicate.
Double click the copied entry (has a - Copy suffix) to open it.
Change both the Note and Other 1 field to Room 8001.
Click on save to apply the changes.
To sum it up, we created two new derivatives that derive from the Empire State Building entry.
Each derivative reflects a different room number, so you can have multiple room numbers at the same address without inputting the same address over and over again.
Additionally, changes in the parent are automatically reflected in the child entries (as long as they are not overwritten by the child).
Of course, This feature enables many things, but don't overdo it.
Note
Derivatives can be used for connections just like normal entries.
Derivatives show up in the search like normal entries.
This way you, can get to your derivative faster without stepping through all the parents.
Important
Derived fields are shown as null in the search results for derivatives.
This is to improve the performance when using a lot of entries.
Nevertheless, it has the benefit of only seeing the root of each value in your search.
For example, if you search for the postalcode 10001, only the parent entry will appear, as this is the only entry where you can change the value if you want to, as the derivatives are updated automatically.
Most of the day to day activities can be controlled by only using the keyboard.
The following keys can be used (not a complete list of all actions):
-
ESC- close the current window (often needs to be pressed twice to confirm) -
RETURN- presses the currently focused button; in case of a text field theSavebutton will be highlighted; opens a table entry -
TABorRIGHT Arrow- Move focus to the next element -
BACKTAB(==SHIFT+TAB) orLEFT Arrow- Move focus to the element before -
UP Arrow- Move focus to the element to the top -
DOWN Arrow- Move focus to the element to the bottom
Tip
Additional global key combinations (platform dependent) can be found under Help -> About in the program's menu.
Note
When a disabled element is selected, it will automatically pass the focus on to the next element in the same direction.
-
CTRL+A- Add new entry -
CTRL+D- Duplicate selected entry -
BACKSPACE- Delete selected entry -
HOME- Go to the top -
END- Go to the end -
ESC- Move focus out of table -
LEFT Arrow- move focus to the element above the table -
RIGHT Arrow- move focus to the element underneath the table
Only the element that has the focus will accept the key events (apart from global key combinations, they will always work unless conflicting with local key combinations).
By using the mouse and clicking on an element, it will get the focus automatically.
Tip
When the focus gets lost, just click on an element to manually set the focus to it.
When an element has focus, it will have a special color fade to it at the upper and lower edge:
The Edit button is focused in this example, while the Duplicate button is not.
Note
Only one element can have the focus at a time.
Tip
The windows already preselect the focus on the most likely option the user will do.
(e.g. focusing Proceed instead of Abort on an action)
Select Settings in the Menubar and click on Change Language.
By default, the language will be set to your operating system's language (Follow System).
If the system's language is not available for the program, the default English Development (Fallback) language is used.
It is named that way, because especially the error messages are more technically detailed and therefore harder to read for a regular user.
The menu let's you change the language to a specific, available language.
Important
The program has to be manually restarted for any language change to take effect.
To prepare the uninstall process of the program, select Prepare Program Uninstall from the Menubar.
This will remove any changes made to the operating system, like the shortcut and registry entries in Windows.
After executing the uninstall function, the program will close itself.
You can now safely delete all the files related to the program.
Tip
If you want to revert the decision, just open the program again.
This will bring the modifications back, if not disabled by the user previously.
Use GitHub's Issues feature to create a bug report: ODM::Issues
Include as many details as you can, so that the problem can be reproduced.
Important
Never share your personal details like the database used or screenshots of your data!