Keira3 Internals

This is a collection of notes aiming to explain the internals of Keira3 for development purposes.

If you just want to use Keira3, you don't need any of the following. If you want to modify Keira3, for example to improve it or to add new features, you may find this page useful.

Main technologies

Keira3 is built upon the following open source web technologies:

• TypeScript is the main language of Keira3. It is a superset of JavaScript. If you know JavaScript and have some basic knowledge of OOP languages like Java and C#, you will feel pretty familiar with TypeScript already. Otherwise, you might find this course helpful. If you don't know JavaScript at all, it would be better to get some basic knowledge first.

• Angular. This is the main framework behind Keira3. We absolutely recommend getting familiar with it before getting your hands inside Keira3's code. If you are looking for a complete Angular course, we can recommend this one.

• We use SCSS to style our UI. It's an extension of CSS. Knowing the CSS fundamentals is required in order to be able to change the Keira3's interface. SCSS should be quite intuitive for anyone who can understand CSS.

• Bootstrap is the CSS framework used as a base for Keira3's style. You don't have to be a Bootstrap expert, however we recommend being at least familiar with its Grid system and Utilities like spacing.

• Electron is the software framework that allows building Desktop apps using web technologies. We don't use many native Electron features so usually you don't have to worry about it when developing Keira3.

• NX is the build system to manage the project and keep it modular by diving it into several libraries. It was originally born as an extension of the Angular CLI, today NX is a generic to manage all kinds of monorepo projects (also for projects not based on Angular). Among several features, we leverage the affected powerful command of NX to run checks (e.g. lint, test, ...) only to the parts of the application that have been modified and to those which depend on them.

Testing

We use test automation in Keira3 in our development cycle. For every PR/commit, our CI automatically runs a lot of automated tests.

More specifically, we have:

• Unit tests. It's all *.spec.ts file, they run with npm run test. We keep 100% coverage and in this is article it is explained why this is important. This means that if you try to submit untested code, the CI build of your PR will fail. We use the Angular testing framework for it.

• Integration tests. It's all the *.integration.spec.ts file, they also run with npm run test, together with the unit tests. You can see the integration tests of Keira3 almost like a set of e2e tests, the main difference is that all the DB interactions are mocked. The difference between unit tests and integration test is: in unit tests we test units by mocking all their dependencies, while in integration tests we test "big pieces" of Keira3 together (mocking only the DB). Mostly used to test the editors.

• For both our unit and integration tests, we test components by doing Component DOM Testing. Check this article for more information about it.

• E2E tests. We have a tiny set of e2e tests based on Playwright. For example, to check the sqlite integration. The command npm run e2e will automatically serve the app and run the e2e tests.

Why test automation?

Because every time you modify your app, you never know if you are breaking any existing functionality unless you manually test everything again and again.

When you have automated tests in place, you are still not 100% sure about not breaking existing stuff, but at least they can give you some assurance.

Files structure

The project is entirely based on NX divinding the code into apps and libraries.

Apps:

• apps/keira-e2e: all e2e test cases, isolated from everything else;
• apps/keira: the main Angular app that imports code from libs/*

Libraries:

• libs/features: source code of the main Keira3 features (each one isolated from the others in different libs). RULE: a feature can NOT import anything from another feature. If something is meant to be shared across features, then it must be placed under libs/shared;

• libs/main: libraries of components that don't belong to a specific feature, yet they are isolated. For example, the main wrapper component MainWindowComponent, the Sidebar, the Login window, etc...

• libs/shared: all kinds of utilities, modules, components, services, abstract classes, testing utilities, etc...

Architecture design and fundamentals

Keira3 code is structured using OOP with techniques like inheritance and generic types to maximise code reuse.

Inside the directory libs/shared/base-abstract-classes there is a collection of abstract classes that are meant to be extended by the concrete Angular Components and Services which will implement the Keira3 features.

If you are not familiar with the terminology used so far, please check the above hyperlinks before proceeding.

Keira3 is modular, you can see it as a collection of features and shared utilities that are organised into NX apps and libraries.

Keira3 terminology and conventions

Typically, Keira3 features are characterised by the following elements.

Table types

All the definitions of the AzerothCore DB tables are defined in Keira3 inside libs/shared/acore-world-model.

If you want to create a new editor, you have to first create its definition there.

The Main Entity

For example Creature is a main entity. Whether you want to modify a vendor (npc_vendor) or a loot of a creature (creature_loot_template), you still have to select (or create) a Creature.

There is always a table (and so also an Editor) for the Main Entity. For creatures it's creature_template.

You can't have a vendor, loot, etc... without having a creature first. In other words, you can't have an npc_vendor row without linking it to an existing entry of creature_template.

Another example could be: you can't have a row in quest_template_addon without linking it to an existing row of quest_template. Because quest_template is the Main Entity of the Quest editors.

Editor

An Editor is typically linked to a table. For example, the Creature -> Trainer editor allows you to edit the npc_trainer table.

There are 2 main types of Editors in Keira3:

Single-row editors

They are the editors of tables containing ONE row for each entity.

For example, the table creature_template_addon can have only ONE row for each creature. You can never have 2 rows pointing to the same creature in this table.

Every row is uniquely identified by a primary key, that is the ID of the selected entity. Typically in the DB they are called id, ID, entry, Entry, etc... yes, they are completely inconsistent, but that's what we inherited from MaNGOS/TrinityCore. In Keira3 we call it just entityIdField.

Multi-row editors

They are the editors containing MULTIPLE rows for each entity.

For example, the table npc_vendor can have multiple rows that belongs to the same Creature. Every row of npc_vendor represents a specific Item that is sold by a specific Creature. And a Creature can sell 0, 1 or many items. Then every Creature can have 0, 1 or many rows in the npc_vendor table. Makes sense right?

Every row has 2 primary keys, typically (but not always) called id and guid. In Keira3 we always call them entityIdField and entitySecondIdField. The entityIdField is the ID of the selected entity.

Back to the example of npc_vendor:

• entityIdField would be the ID of the Creature
• entitySecondIdField would be the ID of the Item

Editor's Component and Service

Every Editor in Keira3 has its own Component and Service counterparts, where:

• you can see an Editor Component as the "UI part" of the Editor. It reflects the status of the table being edited and contains a form that allows the user to change its properties. Components are typically "dumb" (without much logic code) and are mostly about the HTML code. Of course it's linked to the Editor Service;

• the Editor Service contains all the logic that powers an Editor, as well as the status for the current table being edited. It's responsible for calling the QueryService whenever the user edits any property in order to re-generate the SQL queries.

In order to maximise code reuse, the following abstract classes have been created:

• EditorService: base of all Editor Services;

• SingleRowEditorService: extends EditorService, base of all Single-row Editor Services (e.g. CreatureTemplateService extends this class);

• MultiRowEditorService: extends EditorService, base of all Multi-row Editor Services (e.g. CreatureLootTemplateService extends this class);

• EditorComponent: base of all Editor Components

• SingleRowEditorComponent: extends EditorComponent, base of all Single-row Editor Components (e.g. CreatureTemplateComponent extends this class);

• MultiRowEditorComponent: extends EditorComponent, base of all Multi-row Editor Components (e.g. CreatureLootTemplateComponent extends this class);

Handler

Handlers are services responsible for holding statuses such as:

• which entity has been selected (for example, when you select a Creature, the ID of the creature is kept inside the CreatureHandlerService)
• which editors are left with unsaved changes

Group of editors that refer to the same main entity should share one Handler. For example, all Creature Editors refer to the CreatureHandlerService, all Quest Editors refer to the QuestHandlerService, and so on...

All Handlers classes extend the HandlerService abstract class.

Selectors

There are several kinds of selectors which allow the user to easily select a value for a given field.

Selectors are typically available to the user by clicking on the button with three dots:

There are three main types of selectors, listed below.

SingleValueSelectorBtnComponent

The SingleValueSelectorBtnComponent is a reusable component which can be used to allow the user to select a single value from a list of values, for a given field.

Let's check for example the exp field of creature_template, allowing to specify ONE value:

0 - Classic
1 - TBC
2 - WOTLK

All you have to do to implement such selector is first definying the list values by creating an array of Option:

All the options are located in libs/shared/acore-world-model/src/options so you just need to create a new file like the above.

You then need to import the array of options, in this case EXPANSIONS, in the .ts file of your component and declare it as PUBLIC READONLY in order to make it available for the component's template:

Now you can use it in the .html template of the component by adding the keira-single-value-selector-btn html element and passing the following properties:

• [control] the form control, example editorService.form.controls.exp (note: exp is the name of the field)
• [config] an object specifying the options and name property
• [modalClass] the class of the modal, so you can change the modal size, e.g. modal-md or modal-lg (optional)

This is the result:

FlagsSelectorBtnComponent

The FlagsSelectorBtnComponent is another very useful reusable component which allows the user to compose a value from a set of flags (bitmask), for a given field. If terms like bits, bitmask, flags, etc.. sounds weird to you, we recommend to read this page to fully understand how flag values work.

Let's see, for example, how the field dynamicflags of creature_template is implemented.

First you need to define the list of (bit) values by creating an array of Flag:

All the flag values are located in libs/shared/acore-world-model/src/flags so you can create a new file there, for example dynamic-flags.ts in our case.

Basically you need to define what's the meaning of every single bit. Don't forge that bits typically start from zero.

Then you need to import the DYNAMIC_FLAGS array in the component's .ts file and make it available for its .html template by declaring it PUBLIC READONLY:

Now you just need to use it in the html by adding the keira-flags-selector-btn component there:

The attributes for this component are:

• [control] the form control, example editorService.form.controls.dynamicflags (note: dynamicflags is the name of the field)
• [config] an object specifying the options and name property
• [modalClass] the class of the modal, so you can change the modal size, e.g. modal-md or modal-lg (optional)

This is the result:

Other selectors

There are other selectors that allow the user to select values by doing a search either in the DB or in the DBC contained in the sqlite integrated in Keira3.

You can find their implementations in libs/shared/selectors as well as examples of usage around the app.

Example: the item-selector.

You can use it whenever an Item ID is needed: