diff --git a/docs/dataflow/index.rst b/docs/dataflow/index.rst index 0d0983646b..d19ad0c423 100644 --- a/docs/dataflow/index.rst +++ b/docs/dataflow/index.rst @@ -58,7 +58,7 @@ In order to access a particular REST API endpoint, a Javascript Resource has to :caption: channel.js :emphasize-lines: 5 - import { Resource } from 'kolibri.lib.apiResource'; + import { Resource } from 'kolibri/apiResource'; export default new Resource({ name: 'channel', diff --git a/docs/frontend_architecture/core.rst b/docs/frontend_architecture/core.rst index 8975785038..e10b8e2690 100644 --- a/docs/frontend_architecture/core.rst +++ b/docs/frontend_architecture/core.rst @@ -2,48 +2,30 @@ Shared core functionality ========================= -Kolibri provides a set of shared "core" functionality – including components, styles, and helper logic, and libraries – which can be re-used across apps and plugins. +Kolibri provides a set of shared "core" functionality – including components, styles, and helper logic, and libraries – which can be re-used across apps and plugins. This forms a public API that others may depend on, so we keep it limited to ensure we can continue to support it. + +For code that needs to be reused across two plugins, it is recommended to put it in the `kolibri-common` package instead. This will allow easy reuse, but without expanding our API and increasing the number of things we potentially have to support for external users. JS libraries and Vue components ------------------------------- -The following libraries and components are available globally, in all module code: +The following libraries and components are available for import, in all module code, without need for bundling, e.g.: - ``vue`` - the Vue.js object - ``vuex`` - the Vuex object -- ``logging`` - our wrapper around the `loglevel logging module `__ -- ``CoreBase`` - a shared base Vue.js component (*CoreBase.vue*) +- ``kolibri-logging`` - our wrapper around the `loglevel logging module `__ +- ``AppBarPage`` - a shared Vue.js page component (*AppBarPage.vue*) -And **many** others. The complete specification for commonly shared modules can be found in ``kolibri/core/assets/src/core-app/apiSpec.js``. This object defines which modules are imported into the core object. These can then be imported throughout the codebase - e.g.: +The complete specification for commonly shared modules can be found in ``packages/kolibri/package.json``. The "exports" field defines the things inside the package that can be imported, and the "exposes" field defines additional modules that are bundled into the core package. .. code-block:: javascript - import Vue from 'kolibri.lib.vue'; - import CoreBase from 'kolibri.coreVue.components.CoreBase'; + import Vue from 'vue'; + import AppBarPage from 'kolibri/components/AppBarPage'; Adding additional globally-available objects is relatively straightforward due to the :doc:`plugin and webpack build system `. -To expose something in the core app, add the module to the object in ``apiSpec.js``, scoping it to the appropriate property for better organization - e.g.: - -.. code-block:: javascript - - components: { - CoreTable, - }, - utils: { - navComponents, - }, - -These modules would now be available for import anywhere with the following statements: - -.. code-block:: javascript - - import CoreTable from 'kolibri.coreVue.components.CoreTable'; - import navComponents from 'kolibri.utils.navComponents'; - -.. note:: - - In order to avoid bloating the core api, only add modules that need to be used in multiple plugins. +In general, code should not be added to the kolibri package unless it has been specified as required in planned work. This is to avoid cluttering the core package with unnecessary code. Styling ------- @@ -53,7 +35,7 @@ To help enforce style guide specs, we provide global variables that can be used Dynamic core theme ------------------ -Vuex state is used to drive overall theming of the application, in order to allow for more flexible theming (either for accessibility or cosmetic purposes). All core colour styles are defined in Javascript variables kept in Vuex state, which are then applied inline to elements using Vue.js style bindings from Vuex getters. +Reactive state is used to drive overall theming of the application, in order to allow for more flexible theming (either for accessibility or cosmetic purposes). All core colour styles are defined in Javascript variables kept in state, which are then applied inline to elements using Vue.js style bindings. There are two cases where dynamic styles cannot be directly applied to DOM elements: - inline styles cannot apply `pseudo-classes `__ (e.g. ':hover', ':focus', '::before') @@ -65,10 +47,7 @@ In order to apply a style using a computed class, define a style object as a com .. code-block:: javascript - import themeMixin from 'kolibri.coreVue.mixins.themeMixin'; - export default { - mixins: [themeMixin], computed: { pseudoStyle() { return { diff --git a/docs/frontend_architecture/single_page_apps.rst b/docs/frontend_architecture/single_page_apps.rst index 5adc4a17bc..fb2f44ad65 100644 --- a/docs/frontend_architecture/single_page_apps.rst +++ b/docs/frontend_architecture/single_page_apps.rst @@ -38,46 +38,47 @@ If you want to expose your new single page app as a top level navigation item in For more information on using `bundle_id` and connecting it to the relevant Javascript entry point read the documentation on the :ref:`Frontend build pipeline`. The entry point for the nav item should minimally do the following: -.. code-block:: html +.. code-block:: js - - - - This will create a navigation component which will be registered to appear in the navigation side bar. diff --git a/docs/frontend_architecture/testing_layout.rst b/docs/frontend_architecture/testing_layout.rst index 00f12139a4..caf687301f 100644 --- a/docs/frontend_architecture/testing_layout.rst +++ b/docs/frontend_architecture/testing_layout.rst @@ -112,10 +112,10 @@ It any composable does not have an associated mock file, please do create one be .. code:: javascript - import useUser, { useUserMock } from 'kolibri.coreVue.composables.useUser'; + import useUser, { useUserMock } from 'kolibri/composables/useUser'; import YourSampleComponent from '../YourSampleComponent.vue'; - jest.mock('kolibri.coreVue.composables.useUser'); + jest.mock('kolibri/composables/useUser'); ... diff --git a/docs/i18n.rst b/docs/i18n.rst index 269eb859d6..8bc3c3248e 100644 --- a/docs/i18n.rst +++ b/docs/i18n.rst @@ -71,7 +71,7 @@ In order to translate strings in Javascript source files, the namespace and mess .. code-block:: javascript - import { createTranslator } from 'kolibri.utils.i18n'; + import { createTranslator } from 'kolibri/utils/i18n'; const name = 'someModule'; const messages = { helloWorld: 'Hello world', @@ -225,7 +225,7 @@ Content rendererers User interfaces that are tightly coupled to embedded content, such as the 'next page' and 'previous page' buttons in a book, need to be flipped to match the language direction of that content. UIs that are not tightly integrated with the content should match the overall application language, not the content. -Information about content language direction is available in the computed props ``contentDirection`` and ``contentIsRtl`` from ``kolibri.coreVue.mixins.contentRendererMixin``. These can be used to change styling and directionality dynamically, similar to the application-wide ``isRtl`` value. +Information about content language direction is available in the computed props ``contentDirection`` and ``contentIsRtl``. These can be used to change styling and directionality dynamically, similar to the application-wide ``isRtl`` value. In situations where we are using third-party libraries it might be necessary to flip the entire content renderer UI automatically using the RTLCSS framework rather than make targeted changes to the DOM. To handle these cases, it's possible to dynamically load the correct CSS webpack bundle using a promise: