XRX plus plus Inheritance

TODO:

• check if valid for every xrx++-object type. Currently we have only examples of inheritance in apps, services and widgets. modules etc. aren't inherited?

Basics

xrx++ objects can inherit "properties". The xrx:inherits element contains the atom:id of the base object.

xrx:inherits is evaluated during the compilation (build/compiler.xql) in the function xrx:inherit() and xrx:inherited-objects().

The complier copies all elements at the second level (i.e. /root/*) into the inheriting object. Every element defined in the inheriting object overwrites properties with the same name in the base object. (i.e. it currently doesn't exist a type extension!).

Every XRX++-object only inherits from a single super-object. (TODO: only?)

Where is xrx:inherits used?

This is a comprehensive list of all occurrences of <xrx:inherits> in the source code at the time of writing:

All occurences are within the directory mom.XRX/my/XRX/src/mom/app/. For brevity the path is shortened, and the <xrx:inherits>tag:www.monasterium.net,2011:[XY]</xrx:inherits> are left out of the following list:

• portal/portal.app.xml: /core/app/portal
• editor/editor.app.xml: /core/app/editor
• metadata/metadata.app.xml: /core/app/metadata
• archive/widget/remove-archive.widget.xml: /mom/widget/remove-metadata
• charter/widget/imported-charter.widget.xml: /mom/widget/charter
• charter/widget/charter-to-publish.widget.xml: /mom/widget/charter
• charter/widget/saved-charter.widget.xml: /mom/widget/charter
• charter/widget/my-charter.widget.xml: /mom/widget/charter
• bookmark/widget/charter-preview-bookmarks.widget.xml: /mom/widget/charter-preview
• auth/auth.app.xml: /core/app/auth
• auth/widget/apply-role.widget.xml: /core/widget/apply-role
• auth/widget/manage-roles.widget.xml: /core/widget/manage-roles
• auth/service/apply-role.service.xml: /core/service/apply-role
• collection/widget/charter-preview-collection.widget.xml: /mom/widget/charter-preview
• collection/widget/charter-preview-importedcollection.widget.xml: /mom/widget/charter-preview-importedfond
• collection/widget/collection.widget.xml: /mom/widget/charters
• collection/widget/charter-preview-my-collection.widget.xml: /mom/widget/charter-preview
• collection/widget/my-collection.widget.xml: /mom/widget/charters
• collection/widget/remove-collection.widget.xml: /mom/widget/remove-metadata
• collection/widget/imported-collection.widget.xml: /mom/widget/charters
• xrx/xrx.app.xml: /core/app/xrx
• user/user.app.xml: /core/app/user
• user/widget/moderator-info.widget.xml: /core/widget/moderator-info
• user/widget/change-password.widget.xml: /core/widget/change-password
• user/widget/login2.widget.xml: /core/widget/login2
• user/widget/remove-account.widget.xml: /core/widget/remove-account
• user/widget/registration.widget.xml: /core/widget/registration
• user/widget/my-account.widget.xml: /core/widget/my-account
• user/widget/reset-password.widget.xml: /core/widget/reset-password
• user/widget/registration-successful.widget.xml: /core/widget/registration-successful
• user/widget/request-password.widget.xml: /core/widget/request-password
• user/service/update-account.service.xml: /core/service/update-account
• user/service/change-password.service.xml: /core/service/change-password
• user/service/confirm-account.service.xml: /core/service/confirm-account
• user/service/create-account.service.xml: /core/service/create-account
• user/service/request-password.service.xml: /core/service/request-password
• user/service/login2.service.xml: /core/service/login2
• user/service/reset-password.service.xml: /core/service/reset-password
• user/service/remove-account.service.xml: /core/service/remove-account
• user/service/logout2.service.xml: /core/service/logout2
• oaiinterface/oaiinterface.app.xml: /core/app/oaiinterface
• fond/widget/charter-preview-importedfond.widget.xml: /mom/widget/charter-preview
• fond/widget/fond.widget.xml: /mom/widget/charters
• fond/widget/remove-fond.widget.xml: /mom/widget/remove-metadata
• fond/widget/imported-fond.widget.xml: /mom/widget/charters
• search/widget/search-result.widget.xml: /mom/widget/charter
• search/widget/result.widget.xml: /mom/widget/charter-preview
• htdoc/htdoc.app.xml: /core/app/htdoc
• htdoc/widget/edit-htdoc.widget.xml: /core/widget/edit-htdoc
• data/data.app.xml: /core/app/data
• demo-annotation/widget/demo-annotation-editor.widget.xml: /mom/widget/my-collection-charter-edit
• charters/widget/import-info-excel.widget.xml: /mom/widget/import-charters
• charters/widget/import-info-sql.widget.xml: /mom/widget/import-charters
• charters/widget/sql-import.widget.xml: /mom/widget/charter-import
• charters/widget/import-info-ead.widget.xml: /mom/widget/import-charters
• charters/widget/xml-import.widget.xml: /mom/widget/charter-import
• charters/widget/import-info-cei.widget.xml: /mom/widget/import-charters
• charters/widget/excel-import.widget.xml: /mom/widget/charter-import
• charters/widget/oai-import.widget.xml: /mom/widget/charter-import
• charters/widget/cei-import.widget.xml: /mom/widget/charter-import
• charters/widget/import-info-xml.widget.xml: /mom/widget/import-charters
• charters/widget/import-info-oai.widget.xml: /mom/widget/import-charters
• charters/widget/ead-import.widget.xml: /mom/widget/charter-import
• i18n/i18n.app.xml: /core/app/i18n
• i18n/widget/translate.widget.xml: /core/widget/translate
• i18n/widget/translation-progress.widget.xml: /core/widget/translation-progress
• i18n/service/get-translations.service.xml: /core/service/get-translations
• i18n/service/catalog-add-language.service.xml: /core/service/catalog-add-language
• i18n/service/migrate-i18n.service.xml: /core/service/migrate-i18n
• i18n/service/update-i18n-catalog.service.xml: /core/service/update-i18n-catalog
• i18n/service/save-i18n-entry.service.xml: /core/service/save-i18n-entry

Admittedly this list seems a little overwhelming at first. The following information can be extracted from the above list:

• Inheritance within /mom/apps/... occurs in two main flavors:
• from inside the mom.XRX/my/XRX/src/mom/ folder and
• from inside the core-folder in mom.XRX/my/XRX/src/core, i.e. the external infrastructural folder where all the fundamental XRX functionality is situated (to achieve conceptual clarity).
• The only thing inherited from inside the mom.XRX/my/XRX/src/mom/ folder are widgets though. Specifically from mom.XRX/my/XRX/src/mom/widget. And the widgets that are inherited from are often reused in different, albeit fitting contexts. For example the mom/widget/charter-import is inherited from in multiple import scenarios. So inheritance inside of the mom-folder is only used in a context of widget specialization. That these super-widgets are not in the core folder makes sense. The core folder is for un-Monasterium-specific source-code and the super widgets we are talking about here are already within the conceptual space of the more specific Monasterium application.

The inheritance from the mom.XRX/my/XRX/src/core remains...:

We are left with a pretty reduced set of occurrences:

• portal/portal.app.xml: /core/app/portal
• editor/editor.app.xml: /core/app/editor
• metadata/metadata.app.xml: /core/app/metadata
• auth/auth.app.xml: /core/app/auth
• auth/widget/apply-role.widget.xml: /core/widget/apply-role
• auth/widget/manage-roles.widget.xml: /core/widget/manage-roles
• auth/service/apply-role.service.xml: /core/service/apply-role
• xrx/xrx.app.xml: /core/app/xrx
• user/user.app.xml: /core/app/user
• user/widget/moderator-info.widget.xml: /core/widget/moderator-info
• user/widget/change-password.widget.xml: /core/widget/change-password
• user/widget/login2.widget.xml: /core/widget/login2
• user/widget/remove-account.widget.xml: /core/widget/remove-account
• user/widget/registration.widget.xml: /core/widget/registration
• user/widget/my-account.widget.xml: /core/widget/my-account
• user/widget/reset-password.widget.xml: /core/widget/reset-password
• user/widget/registration-successful.widget.xml: /core/widget/registration-successful
• user/widget/request-password.widget.xml: /core/widget/request-password
• user/service/update-account.service.xml: /core/service/update-account
• user/service/change-password.service.xml: /core/service/change-password
• user/service/confirm-account.service.xml: /core/service/confirm-account
• user/service/create-account.service.xml: /core/service/create-account
• user/service/request-password.service.xml: /core/service/request-password
• user/service/login2.service.xml: /core/service/login2
• user/service/reset-password.service.xml: /core/service/reset-password
• user/service/remove-account.service.xml: /core/service/remove-account
• user/service/logout2.service.xml: /core/service/logout2
• oaiinterface/oaiinterface.app.xml: /core/app/oaiinterface
• htdoc/htdoc.app.xml: /core/app/htdoc
• htdoc/widget/edit-htdoc.widget.xml: /core/widget/edit-htdoc
• data/data.app.xml: /core/app/data
• i18n/i18n.app.xml: /core/app/i18n
• i18n/widget/translate.widget.xml: /core/widget/translate
• i18n/widget/translation-progress.widget.xml: /core/widget/translation-progress
• i18n/service/get-translations.service.xml: /core/service/get-translations
• i18n/service/catalog-add-language.service.xml: /core/service/catalog-add-language
• i18n/service/migrate-i18n.service.xml: /core/service/migrate-i18n
• i18n/service/update-i18n-catalog.service.xml: /core/service/update-i18n-catalog
• i18n/service/save-i18n-entry.service.xml: /core/service/save-i18n-entry

Now it becomes apparent that there are only three things that are ever inherited from. It is apps, widget, service. For now, for an example and brief explanation of app inheritance see Project Structure , my/XRX/src/core & mom

Why do we use inheritance in widgets and services?

So, what about the widget and service, now? Let's dive right into it...:

We remember the difference between a widget and a service: A widget the user interacts with, a service does stuff behind the scenes, often in reaction to previous widget user interaction.

How does the inheritance of widget and service work in detail now, and why do we do it?

Example: user context

Let's focus on the user context. It is by far showing the biggest amount of inheritance-occurrence. Once the user context is explained, the rest is far easier to come to grasps with. Advantage here is that everyone is familiar with a stereotypical user and has a decent understanding of what use-cases arise. For example a user wants to register, change his password or remove his account.

If we look at the list of occurrences of xrx:inherits again at the rows starting with user/

Note: It makes sense to open the two registration.widget.xml files of the two folders my/XRX/src/core/app/user and my/XRX/src/mom/app/user side by side to compare them:

What does core's registration.widget.xml offer you? It has an XForm inside of it, so the user can give personal information like wished username, the town he/she is living in, password etc. In addition there is a title of "Registration" present. That is nice, mom does not need to provide one then.

What is mom's registration.widget.xml doing now? First of all, it inherits from core's one. And then, it provides an <xrx:portal> (which specifies the way the widget would like to be presented, some possible values are "default" as here and "desktop" or "fullscreen"). And mom's registration.widget.xml adds some CSS-properties that inform about how the widget would like to be presented. Now it is really making sense that inheritance is used here, right? How to present this specific widget is clearly a very specific thing and should not be placed withing the core folder. It is mom's responsibility, clearly!

Now, I mentioned the difference between widget and service earlier, and how a service often reacts to user interaction. In this case, with a user registration the "behind the scenes" part of the use-case is "getting that user into the database". Look at the above list, is there a fitting service?

create-account.service.xml looks good to me! Go ahead and open the two versions of create-account.service.xml (as before core's one and mom's one) side by side. What is core's service doing now? It gets the $data (information typed into xform and sent to server) from the user, checks if the email already exists and so on and if not creates a user with the $data. That is totally core! What does mom's create-account.service.xml do in addition to that? It sends a confirmation email with a personalilzed message. The email's subject says "MOM-CA - Account Service". No need to read further here, this is in the responsibilty of mom and not at all a thing for core to do. Customized. Inheritance makes perfect sense.

If you like, take a look around and have a look at the other app, service and widget things. If inheritance is present, remember to open the respective files side by side to understand why mom is extending core's implementation. Most of the time, it will add a little something which is clearly in its responsibility.