mirror of
https://github.com/frappe/books.git
synced 2024-11-14 17:34:04 +00:00
112 lines
4.2 KiB
Markdown
112 lines
4.2 KiB
Markdown
# Fyo
|
|
|
|
This is the underlying framework that runs **Books**, at some point it may be
|
|
removed into a separate repo, but as of now it's in gestation.
|
|
|
|
The reason for maintaining a framework is to allow for varied backends.
|
|
Currently Books runs on the electron renderer process and all db stuff happens
|
|
on the electron main process which has access to nodelibs. As the development
|
|
of `Fyo` progresses it will allow for a browser frontend and a node server
|
|
backend.
|
|
|
|
This platform variablity will be handled by code in the `fyo/demux` subdirectory.
|
|
|
|
## Pre Req
|
|
|
|
**Singleton**: The `Fyo` class is used as a singleton throughout Books, this
|
|
allows for a single source of truth and a common interface to access different
|
|
modules such as `db`, `doc` an `auth`.
|
|
|
|
**Localization**: Since Books' functionality changes depending on region,
|
|
regional information (`countryCode`) is required in the initialization process.
|
|
|
|
**`Doc`**: This is `fyo`'s abstraction for an ORM, the associated files are
|
|
located in `model/doc.ts`, all classes exported from `books/models` extend this.
|
|
|
|
### Terminology
|
|
|
|
- **Schema**: object that defines shape of the data in the database.
|
|
- **Model**: the controller class that extends the `Doc` class, or the `Doc`
|
|
class itself (if a specific controller doesn't exist).
|
|
- **doc** (not `Doc`): instance of a Model, i.e. what has the data.
|
|
|
|
If you are confused, I understand.
|
|
|
|
## Initialization
|
|
|
|
There are a set of core models which are maintained in the `fyo/models`
|
|
subdirectory, from this the _SystemSettings_ field `countryCode` is used to
|
|
config regional information.
|
|
|
|
A few things have to be done on initialization:
|
|
|
|
#### 1. Connect To DB
|
|
|
|
If creating a new instance then `fyo.db.createNewDatabase` or if loading an
|
|
instance `fyo.db.connectToDatabase`.
|
|
|
|
Both of them take `countryCode` as an argument, `fyo.db.createNewDatabase`
|
|
should be passed the `countryCode` as the schemas are built on the basis of
|
|
this.
|
|
|
|
#### 2. Initialize and Register
|
|
|
|
Done using `fyo.initializeAndRegister` after a database is connected, this should be
|
|
passed the models and regional models.
|
|
|
|
This sets the schemas and associated models on the `fyo` object along with a few
|
|
other things.
|
|
|
|
### Sequence
|
|
|
|
**First Load**: i.e. registering or creating a new instance.
|
|
|
|
- Get `countryCode` from the setup wizard.
|
|
- Create a new DB using `fyo.db.createNewDatabase` with the `countryCode`.
|
|
- Get models and `regionalModels` using `countryCode` from `models/index.ts/getRegionalModels`.
|
|
- Call `fyo.initializeAndRegister` with the all models.
|
|
|
|
**Next Load**: i.e. logging in or opening an existing instance.
|
|
|
|
- Connect to DB using `fyo.db.connectToDatabase` and get `countryCode` from the return.
|
|
- Get models and `regionalModels` using `countryCode` from `models/index.ts/getRegionalModels`.
|
|
- Call `fyo.initializeAndRegister` with the all models.
|
|
|
|
_Note: since **SystemSettings** are initialized on `fyo.initializeAndRegister`
|
|
db needs to be set first else an error will be thrown_
|
|
|
|
## Testing
|
|
|
|
For testing the `fyo` class, `mocha` is used (`node` side). So for this the
|
|
demux classes are directly replaced by `node` side managers such as
|
|
`DatabaseManager`.
|
|
|
|
For this to work the class signatures of the demux class and the manager have to
|
|
be the same which is maintained by abstract demux classes.
|
|
|
|
`DatabaseManager` is used as the `DatabaseDemux` for testing without API or IPC
|
|
calls. For `AuthDemux` the `DummyAuthDemux` class is used.
|
|
|
|
## Translations
|
|
|
|
All translations take place during runtime, for translations to work, a
|
|
`LanguageMap` (for def check `utils/types.ts`) has to be set.
|
|
|
|
This can be done using `fyo/utils/translation.ts/setLanguageMapOnTranslationString`.
|
|
|
|
Since translations are runtime, if the code is evaluated before the language map
|
|
is loaded, translations won't work. To prevent this, don't maintain translation
|
|
strings globally since this will be evaluated before the map is loaded.
|
|
|
|
## Observers
|
|
|
|
The doc and db handlers have observers (instances of `Observable`) as
|
|
properties, these can be accessed using
|
|
- `fyo.db.observer`
|
|
- `fyo.doc.observer`
|
|
|
|
The purpose of the observer is to trigger registered callbacks when some `doc`
|
|
operation or `db` operation takes place.
|
|
|
|
These are schema level observers i.e. they are registered like so:
|
|
`method:schemaName`. The callbacks receive args passed to the functions. |