From 609391164e15a8012260171db6a180d0595a4707 Mon Sep 17 00:00:00 2001 From: rekjuh Date: Fri, 25 Oct 2024 13:01:05 +0300 Subject: [PATCH 1/7] Update How to create a bundle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add missing link and try to fix ´´ in the beginning --- 8 Developing instructions/00120-HowToCreateABundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/8 Developing instructions/00120-HowToCreateABundle.md b/8 Developing instructions/00120-HowToCreateABundle.md index 98894bc..267c5e9 100644 --- a/8 Developing instructions/00120-HowToCreateABundle.md +++ b/8 Developing instructions/00120-HowToCreateABundle.md @@ -1,8 +1,8 @@ ## How to create a bundle -If you haven't done it already, download sources [here](). Then extract the files from the downloaded archive. +If you haven't done it already, download sources [here](https://oskari.org/download). Then extract the files from the downloaded archive. -Now decide a `` which is unique and describes the functionality the bundle offers e.g. 'search' (already implemented so prefix it with something like mysearch). +Now decide a `` which is unique and describes the functionality the bundle offers e.g. `mysearch` (`search` is already implemented so use a prefix). Create a folder with the name of your `` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework//resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. It is encouraged to create your own namespace (and directories) for your own bundles. From 4d44ac83ad260286504e1e372b05ce708234e7e3 Mon Sep 17 00:00:00 2001 From: rekjuh Date: Fri, 25 Oct 2024 14:08:31 +0300 Subject: [PATCH 2/7] Update 00120-HowToCreateABundle.md --- 8 Developing instructions/00120-HowToCreateABundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/8 Developing instructions/00120-HowToCreateABundle.md b/8 Developing instructions/00120-HowToCreateABundle.md index 267c5e9..9acfc49 100644 --- a/8 Developing instructions/00120-HowToCreateABundle.md +++ b/8 Developing instructions/00120-HowToCreateABundle.md @@ -2,7 +2,7 @@ If you haven't done it already, download sources [here](https://oskari.org/download). Then extract the files from the downloaded archive. -Now decide a `` which is unique and describes the functionality the bundle offers e.g. `mysearch` (`search` is already implemented so use a prefix). +Now decide a `` which is unique and describes the functionality the bundle offers e.g. `my_search` (`search` is already implemented so use a prefix). Create a folder with the name of your `` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework//resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. It is encouraged to create your own namespace (and directories) for your own bundles. From 9432d1b91d8ab985d3eda140e729daab07f35fe0 Mon Sep 17 00:00:00 2001 From: rekjuh <87303508+rekjuh@users.noreply.github.com> Date: Tue, 26 Nov 2024 13:46:12 +0200 Subject: [PATCH 3/7] Update HowToUseABundle and HowToCreateABundle --- 7 Operating instructions/00080-HowToUseABundle.md | 14 +++++++------- .../00120-HowToCreateABundle.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/7 Operating instructions/00080-HowToUseABundle.md b/7 Operating instructions/00080-HowToUseABundle.md index 340b1de..9450304 100644 --- a/7 Operating instructions/00080-HowToUseABundle.md +++ b/7 Operating instructions/00080-HowToUseABundle.md @@ -1,18 +1,18 @@ ### How to use a bundle -A bundle is a component in an Oskari application. A bundle is a selection of [Oskari classes](00100-HowToUseClasses.md) which form a component that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. For a short introduction see [create your own bundle](/guides/quick-start/create-your-own-bundle). +A bundle is a component in an Oskari application. A bundle is a selection of [Oskari classes](00100-HowToUseClasses.md) which form a component that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality - for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. For a short introduction see [create your own bundle](../8%20Developing%20instructions/00120-HowToCreateABundle.md). #### Directory structure -See [here](../2 Application environment/00020-Frontend.md) for info about structure and conventions. +See [here](../2%20Application%20environment/00040-DirectoryStructure.md)) for info about directory structure and conventions. #### Implementation -Bundles implementation files should be located under the `/bundles` folder. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is played) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. The bundle doesn't need to have an instance and can be just used to import dependency files that can be instantiated elsewhere. Usually you want to implement a BundleInstance since you can think of it as a starting point for your functionality which is triggered by just adding your bundle in an applications startup sequence. +Bundle's implementation files should be located under the `/bundles` folder. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is played) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. -A Bundle instance is an Oskari class which implements `Oskari.bundle.BundleInstance` protocol. A Bundle instance is created as a result from a Bundle definitions (see above) create method. Bundle instance state and lifecycle is managed by Bundle Manager. +A Bundle instance is an Oskari class which implements `Oskari.bundle.BundleInstance` protocol. Usually you want to implement a BundleInstance since you can think of it as a starting point for your functionality which is triggered by just adding your bundle in an applications startup sequence. A Bundle instance is created as a result from a Bundle definitions (see above) create method. Bundle instance state and lifecycle is managed by Bundle Manager. However, the bundle doesn't need to have an instance and can be just used to import dependency files that can be instantiated elsewhere. -Bundle lifecycle methods +**Bundle lifecycle methods:** * `start` - called by application to start any functionality that this bundle instance might have * `update` - called by Bundle Manager when Bundle Manager state is changed (to inform any changes in current 'bundlage') @@ -27,9 +27,9 @@ instance.mediator = { #### Definition -The bundle definition (or package) should be located in `bundle.js` file under the `/packages` folder. The bundle package definition should not implement any actual functionality. It should only declare the JavaScript, CSS and localization resources (== files) and metadata if any. If the bundle package can be instantiated the package's `create` method should create the bundle's instance. The bundle doesn't need to have an instance and can be used to import dependency files that can be instantiated elsewhere. In that case the create method should return the bundle class itself (`return this;`). +The bundle definition (or package) should be located in `bundle.js` file under the `/packages` folder. The bundle package definition should not implement any actual functionality. It should only declare the JavaScript, CSS and localization resources (= files) and metadata (if any). If the bundle package can be instantiated the package's `create` method should create the bundle's instance. -[Sample bundle definition](/guides/quick-start/sample-bundle-definition) +If the bundle doesn't have an instance and is used to import dependency files that are instantiated elsewhere, the create method should return the bundle class itself (`return this;`). A sample bundle definition can be found as a file named `bundle.js` under `/packages///`. Bundle should install itself to Oskari framework by calling `installBundleClass` at the end of `bundle.js` diff --git a/8 Developing instructions/00120-HowToCreateABundle.md b/8 Developing instructions/00120-HowToCreateABundle.md index 98894bc..d1b60da 100644 --- a/8 Developing instructions/00120-HowToCreateABundle.md +++ b/8 Developing instructions/00120-HowToCreateABundle.md @@ -1,8 +1,8 @@ ## How to create a bundle -If you haven't done it already, download sources [here](). Then extract the files from the downloaded archive. +If you haven't done it already, download sources [here](https://oskari.org/download/). Then extract the files from the downloaded archive. -Now decide a `` which is unique and describes the functionality the bundle offers e.g. 'search' (already implemented so prefix it with something like mysearch). +Now decide a `` which is unique and describes the functionality the bundle offers e.g. `search` (already implemented so prefix it with something like mysearch). Create a folder with the name of your `` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework//resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. It is encouraged to create your own namespace (and directories) for your own bundles. From b92f641dd51245c06dbf4b93f3276b61dee07469 Mon Sep 17 00:00:00 2001 From: rekjuh <87303508+rekjuh@users.noreply.github.com> Date: Wed, 27 Nov 2024 15:20:13 +0200 Subject: [PATCH 4/7] Update SetupDevelopmentEnvironment.md Double-check the content to match what's requested in https://github.com/oskariorg/oskari-documentation/issues/30 --- .../00040-SetupDevelopmentEnvironment.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/3 Setup instructions/00040-SetupDevelopmentEnvironment.md b/3 Setup instructions/00040-SetupDevelopmentEnvironment.md index 3ba4dcb..f80f01d 100644 --- a/3 Setup instructions/00040-SetupDevelopmentEnvironment.md +++ b/3 Setup instructions/00040-SetupDevelopmentEnvironment.md @@ -1,7 +1,8 @@ ## Setup Oskari development environment -This document describes how to setup development environment for Oskari using source code. If you want to develop / maintain oskari yourself this is the correct section. -For setting up an instance using the ready jetty bundle check out [Setup Jetty](00030-SetupJetty.md) +This section describes how to setup development environment for Oskari using source code. If you want to develop or maintain Oskari yourself this is the correct section. + +For setting up an instance using the ready jetty bundle see [Setup Jetty](00030-SetupJetty.md) ### Requirements @@ -9,7 +10,7 @@ The following items are assumed installed. * JDK 8 * [Maven 3+](http://maven.apache.org/) (developed using 3.5.0) -* Git client (http://git-scm.com/) - Optionally download zip file from https://github.com/oskariorg/oskari-server +* [Git client](http://git-scm.com/) (git is mandatory for contributing any changes to Oskari) - Optionally download zip file from https://github.com/oskariorg/oskari-server * `{jetty.base}` refers to the oskari-server folder in an unzipped [Jetty bundle](/download) ### Setup Git configuration @@ -26,14 +27,14 @@ With commandline git: git clone https://github.com/oskariorg/oskari-server.git -Note! You can also download the codes in zip format from Github, but for contributing any changes to Oskari git is mandatory. -Additional Maven modules can be contributed outside git though if they are compatible with the current develop/master branch, but this is not adviced. +Note! You can also download the codes in zip format from Github, but for contributing any changes to Oskari git is mandatory. +Additional Maven modules can be contributed outside git though if they are compatible with the current develop/master branch, but this is not advised. Note! The frontend source code is already available under `{jetty.base}/oskari-frontend` in the [Jetty bundle](/download). To update it you can replace it with code found in https://github.com/oskariorg/oskari-frontend. ### Build Oskari server -This will build all modules that Oskari server is composed of. +This will build all modules that Oskari server is composed of: cd oskari-server mvn clean install From cb2993d7b317d090ad3b6bc40e9623ee85b14258 Mon Sep 17 00:00:00 2001 From: rekjuh <87303508+rekjuh@users.noreply.github.com> Date: Wed, 27 Nov 2024 15:37:33 +0200 Subject: [PATCH 5/7] Update version number examples to 1.0.0 Fixes this issue: https://github.com/oskariorg/oskari-documentation/issues/35 --- 3 Setup instructions/00050-UpdatingOskariVersion.md | 8 ++++---- .../00120-HowToModifyAppSetups.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/3 Setup instructions/00050-UpdatingOskariVersion.md b/3 Setup instructions/00050-UpdatingOskariVersion.md index 2ff4a4f..063b61f 100644 --- a/3 Setup instructions/00050-UpdatingOskariVersion.md +++ b/3 Setup instructions/00050-UpdatingOskariVersion.md @@ -25,7 +25,7 @@ Updating an Oskari-powered server that is based on the [sample-server-extension] ``` - 1.55.1 + 1.0.0 ... ``` @@ -34,7 +34,7 @@ To the new version: ``` - 1.56.0 + 1.0.1 ... ``` @@ -45,7 +45,7 @@ After this run `mvn clean install` to generate a new `oskari-map.war` under `[yo Updating an Oskari application that is based on the [sample-application](https://github.com/oskariorg/sample-application) template is fairly simple as well. For the frontend the oskari-frontend (and possible oskari-frontend-contrib) dependency is updated by changing the version number in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L9) file from the current version in the app: ``` "dependencies": { - "oskari-frontend": "https://git@github.com/oskariorg/oskari-frontend.git#1.55.2" + "oskari-frontend": "https://git@github.com/oskariorg/oskari-frontend.git#1.0.0" }, ``` @@ -53,7 +53,7 @@ To the new version: ``` "dependencies": { - "oskari-frontend": "https://git@github.com/oskariorg/oskari-frontend.git#1.56.0" + "oskari-frontend": "https://git@github.com/oskariorg/oskari-frontend.git#1.0.1" }, ``` diff --git a/9 Configuration instructions/00120-HowToModifyAppSetups.md b/9 Configuration instructions/00120-HowToModifyAppSetups.md index 20f8f8f..a8826cb 100644 --- a/9 Configuration instructions/00120-HowToModifyAppSetups.md +++ b/9 Configuration instructions/00120-HowToModifyAppSetups.md @@ -42,7 +42,7 @@ The application specific migrations can of course be done however you want but t ### Modifying applications after the initial database population -Here's an example Flyway-migration that you can add on your server-extension code. Note that the order in which migrations are run is determined by the version number on the filename (the below would be 3.0.3). When you want to add a new migration after one has been run, you need to bump the version to a higher number like 3.0.4, 3.1.0, 4.0.0. So take a note a consider a versioning strategy for your Oskari instance. For best practices the version on the frontend codes package.json, the version on the server Maven modules pom.xml and the version on the Flyway migration should be tied to each other someway. Also note that the package reads `[your apps module]`. This is `example` on our sample-server-extension but can and should be changed to something that describes your app. (Not sure why we didn't call it "app" instead of "example" as that would have been more generic to use without renaming/might change this later). Note that you can also have multiple Flyway-modules on your app. The modules that are used when the server runs is set on `oskari-ext.properties` as `db.additional.modules`. +Here's an example Flyway-migration that you can add on your server-extension code. Note that the order in which migrations are run is determined by the version number on the filename (the below would be 1.0.0). When you want to add a new migration after one has been run, you need to bump the version to a higher number like 1.0.1, 1.1.0, 2.0.0. So take a note a consider a versioning strategy for your Oskari instance. For best practices the version on the frontend codes package.json, the version on the server Maven modules pom.xml and the version on the Flyway migration should be tied to each other someway. Also note that the package reads `[your apps module]`. This is `example` on our sample-server-extension but can and should be changed to something that describes your app. (Not sure why we didn't call it "app" instead of "example" as that would have been more generic to use without renaming/might change this later). Note that you can also have multiple Flyway-modules on your app. The modules that are used when the server runs is set on `oskari-ext.properties` as `db.additional.modules`. The migration name is after two underscores after the version. This can be anything you like on your application but it's easier to maintain if naming makes sense with the migration that is being run. From 11da8784b49058e347a13c728cc3c6dbf1e9d2fc Mon Sep 17 00:00:00 2001 From: rekjuh <87303508+rekjuh@users.noreply.github.com> Date: Tue, 3 Dec 2024 09:25:20 +0200 Subject: [PATCH 6/7] Update 7 Operating instructions/00080-HowToUseABundle.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sami Mäkinen --- 7 Operating instructions/00080-HowToUseABundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/7 Operating instructions/00080-HowToUseABundle.md b/7 Operating instructions/00080-HowToUseABundle.md index 9450304..44087a7 100644 --- a/7 Operating instructions/00080-HowToUseABundle.md +++ b/7 Operating instructions/00080-HowToUseABundle.md @@ -8,7 +8,7 @@ See [here](../2%20Application%20environment/00040-DirectoryStructure.md)) for in #### Implementation -Bundle's implementation files should be located under the `/bundles` folder. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is played) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. +In oskari-frontend the implementations for bundles are be located under the `/bundles` folder. It's followed by a namespacing folder and a folder (usually) matching the bundle id. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is "played"/started) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. A Bundle instance is an Oskari class which implements `Oskari.bundle.BundleInstance` protocol. Usually you want to implement a BundleInstance since you can think of it as a starting point for your functionality which is triggered by just adding your bundle in an applications startup sequence. A Bundle instance is created as a result from a Bundle definitions (see above) create method. Bundle instance state and lifecycle is managed by Bundle Manager. However, the bundle doesn't need to have an instance and can be just used to import dependency files that can be instantiated elsewhere. From 1cf0f731c2e52a97c30e2572c4a31c7fb0eab296 Mon Sep 17 00:00:00 2001 From: rekjuh <87303508+rekjuh@users.noreply.github.com> Date: Tue, 3 Dec 2024 15:36:49 +0200 Subject: [PATCH 7/7] Revisions to the documentation Taking into account Sami's comments and further revisions. WIP still. --- .../00040-SetupDevelopmentEnvironment.md | 22 ++++++----- .../00050-UpdatingOskariVersion.md | 32 +++++++++++----- .../00080-HowToUseABundle.md | 16 ++++++-- .../00120-HowToCreateABundle.md | 8 ++-- .../00120-HowToModifyAppSetups.md | 38 ++++--------------- 5 files changed, 60 insertions(+), 56 deletions(-) diff --git a/3 Setup instructions/00040-SetupDevelopmentEnvironment.md b/3 Setup instructions/00040-SetupDevelopmentEnvironment.md index f80f01d..676d8ad 100644 --- a/3 Setup instructions/00040-SetupDevelopmentEnvironment.md +++ b/3 Setup instructions/00040-SetupDevelopmentEnvironment.md @@ -1,16 +1,16 @@ ## Setup Oskari development environment -This section describes how to setup development environment for Oskari using source code. If you want to develop or maintain Oskari yourself this is the correct section. +This section describes how to setup development environment for Oskari using source code. If you want to customize Oskari, this is the correct section. -For setting up an instance using the ready jetty bundle see [Setup Jetty](00030-SetupJetty.md) +For setting up an instance using the ready Jetty bundle see [Setup Jetty](00030-SetupJetty.md) ### Requirements -The following items are assumed installed. +The following items are required for the development process: * JDK 8 * [Maven 3+](http://maven.apache.org/) (developed using 3.5.0) -* [Git client](http://git-scm.com/) (git is mandatory for contributing any changes to Oskari) - Optionally download zip file from https://github.com/oskariorg/oskari-server +* [Git client](http://git-scm.com/) (git is mandatory for contributing any changes to Oskari) - Optionally download zip file from [oskari-server GitHub repo](https://github.com/oskariorg/oskari-server) * `{jetty.base}` refers to the oskari-server folder in an unzipped [Jetty bundle](/download) ### Setup Git configuration @@ -23,27 +23,31 @@ Ignore file permissions: ### Fetch Oskari-server source code -With commandline git: +With command line git: git clone https://github.com/oskariorg/oskari-server.git -Note! You can also download the codes in zip format from Github, but for contributing any changes to Oskari git is mandatory. +Or download the codes in zip format from [GitHub](https://github.com/oskariorg/oskari-server). + Additional Maven modules can be contributed outside git though if they are compatible with the current develop/master branch, but this is not advised. -Note! The frontend source code is already available under `{jetty.base}/oskari-frontend` in the [Jetty bundle](/download). To update it you can replace it with code found in https://github.com/oskariorg/oskari-frontend. +Note! The frontend source code is already available under `{jetty.base}/oskari-frontend` in the [Jetty bundle](/download). To update it, you can replace it with code found in [the oskari-frontend GitHub repo](https://github.com/oskariorg/oskari-frontend). ### Build Oskari server -This will build all modules that Oskari server is composed of: +Build all modules that Oskari server is composed of with the following command: cd oskari-server mvn clean install ### Fetch sample-server-extension source code and compile it -To test your changes on a running web app you can use sample-server-extension to create a webapp using your modified version of oskari-server. +To test your changes on a running web app you can use [sample-server-extension](https://github.com/oskariorg/sample-server-extension/) to create a web app using your modified version of oskari-server. + Check that the oskari.version in pom.xml matches the project version of oskari-server you built. +Download and install the sample-server-extension with the following commands: + git clone https://github.com/oskariorg/sample-server-extension.git cd sample-server-extension mvn clean install diff --git a/3 Setup instructions/00050-UpdatingOskariVersion.md b/3 Setup instructions/00050-UpdatingOskariVersion.md index 063b61f..562b7df 100644 --- a/3 Setup instructions/00050-UpdatingOskariVersion.md +++ b/3 Setup instructions/00050-UpdatingOskariVersion.md @@ -1,17 +1,27 @@ ## Updating Oskari version -Note! We are updating the frontend and server versions at the same time and for best compatibility it's best to use same version in both. Hotfix/patch versions might not always match but with version `major.minor.patch` the major and minor versions should match. +This section guides you through updating your Oskari instance. -### Migration and release notes - -Simply updating the version of Oskari dependency for the frontend and server and building new versions of your app/server is enough in most cases. But sometimes there are additional things that need to be done when updating. For example your application code might not compile after updating if we have changed some class in oskari-server that you are using directly in your app or there might be some things that should be done while updating that are not as obvious. These things are documented on the `Migration Guide` in oskari-server repository. You should also at least skim through the `Release notes` for both server and frontend to see if there are something that might affect your app. There might be a new implementation of a functionality/bundle that you want to use instead of the old one or things like this. +We are updating the frontend and server versions **at the same time** and for the best compatibility **it's best to use same version in both**. Hotfix/patch versions might not always match but with version `major.minor.patch` the major and minor versions should match. -So take a look at these before updating: +Before updating, the following links are recommended to at least skim through: - [Migration Guide](https://github.com/oskariorg/oskari-server/blob/master/MigrationGuide.md) - [Server release notes](https://github.com/oskariorg/oskari-server/blob/master/ReleaseNotes.md) - [Frontend release notes](https://github.com/oskariorg/oskari-frontend/blob/master/ReleaseNotes.md) +### Migration and release notes + +In most cases updating Oskari version means: +1. updating the version of Oskari dependency for the frontend and server and +2. building new versions of your app/server + +Sometimes there are additional things that need to be done when updating. These are documented on [The Migration Guide in oskari-server repository](https://github.com/oskariorg/oskari-server/blob/master/MigrationGuide.md). + +There can be also application spesific things that need to be taken into account when updating. For example, your application code might not compile after updating if you have changed some class in oskari-server that you are using directly in your app. + +You should also at least skim through [the Release notes](https://oskari.org/documentation/docs/latest/12-Changelog) for both the server and the frontend to see if there is something that might affect your app. There might be, for example, a new implementation of a bundle/functionality that you want to use instead of the old one. + It's also a good idea to see any PRs/changes for the sample application to see if there are things that you can streamline/change in your application for the newer version: - https://github.com/oskariorg/sample-application @@ -19,7 +29,7 @@ It's also a good idea to see any PRs/changes for the sample application to see i Note! The idea is not that you use the sample-application/server directly but use it as a template to create your own app/server. For example the database migrations in server-template assume they are run on an empty database and might not work properly if copied directly to your server code. We change the sample migrations between versions to make the most sense as simple examples for the latest version while actual apps (copies of sample-server) should work to migrate the existing database of the app. -### Server +### Updating the server Updating an Oskari-powered server that is based on the [sample-server-extension](https://github.com/oskariorg/sample-server-extension) template is done by updating the value of `oskari.version` property in [pom.xml](https://github.com/oskariorg/sample-server-extension/blob/1.2.1/pom.xml#L13) file: @@ -38,11 +48,13 @@ To the new version: ... ``` + After this run `mvn clean install` to generate a new `oskari-map.war` under `[your-server-repository-root]/webapp-map/target`. Replace the `oskari-map.war` under the `oskari-server/webapps` folder (in a setup similar to the Oskari/Jetty download package) with the new one. -### Frontend +### Updating the frontend Updating an Oskari application that is based on the [sample-application](https://github.com/oskariorg/sample-application) template is fairly simple as well. For the frontend the oskari-frontend (and possible oskari-frontend-contrib) dependency is updated by changing the version number in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L9) file from the current version in the app: + ``` "dependencies": { "oskari-frontend": "https://git@github.com/oskariorg/oskari-frontend.git#1.0.0" @@ -58,18 +70,18 @@ To the new version: ``` -When updating Oskari version you might also want to change the application version in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L3) on your application to signal that the application has been updated. +When updating Oskari version, change also the application version in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L3) on your application to signal that the application has been updated. After this you need to run `npm install` to install any new/changed libraries and `npm run build` to generate a new build under `[your-application-repository-root]/dist/[version on package.json]`. After the build the application repository can be served as static resources from Jetty/nginx or similar server. -Note! To use the newly built frontend you will need to update `oskari-ext.properties` under `oskari-server/resources` to link the new frontend version: +Finally, to use the newly built frontend you will need to update `oskari-ext.properties` under `oskari-server/resources` to link the new frontend version: oskari.client.version=dist/[version from your package.json] #### Building the frontend for production -Modern web applications are developed using JavaScript syntax that is not fully supported by older browsers and the code needs to be processed before it can be used by end-user browsers. This step also includes bundling and minifying the code so it's more compact for consumption than the human-friendly version that is used for development. This will reduce the startup time for the end-user dramatically. +Modern web applications are developed using JavaScript syntax that is not fully supported by older browsers and the code needs to be processed before it can be used by the end-user browsers. This step also includes bundling and minifying the code so it's more compact for consumption than the human-friendly version that is used for development. This will reduce the startup time for the end-user dramatically. With the default sample application (a pre-built version is included in the zip download) you can run `npm run build` to generate the minified Javascript files. This will result in folders and files generated under `[your frontend repository root]/dist/`. diff --git a/7 Operating instructions/00080-HowToUseABundle.md b/7 Operating instructions/00080-HowToUseABundle.md index 9450304..31a42e0 100644 --- a/7 Operating instructions/00080-HowToUseABundle.md +++ b/7 Operating instructions/00080-HowToUseABundle.md @@ -1,14 +1,14 @@ ### How to use a bundle -A bundle is a component in an Oskari application. A bundle is a selection of [Oskari classes](00100-HowToUseClasses.md) which form a component that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality - for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. For a short introduction see [create your own bundle](../8%20Developing%20instructions/00120-HowToCreateABundle.md). +A bundle is a pluggable module in an Oskari application. A bundle is a selection of implementing JavaScript files that can include for example [Oskari classes](00100-HowToUseClasses.md) that as a whole form a module that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality - for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. For a short introduction see [create your own bundle](../8%20Developing%20instructions/00120-HowToCreateABundle.md). #### Directory structure -See [here](../2%20Application%20environment/00040-DirectoryStructure.md)) for info about directory structure and conventions. +See [here](../2%20Application%20environment/00040-DirectoryStructure.md) for information about directory structure and conventions. #### Implementation -Bundle's implementation files should be located under the `/bundles` folder. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is played) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. +In oskari-frontend directory the implementations for bundles are be located under the `/bundles` folder. It's followed by a namespacing folder and a folder (usually) matching the bundle id. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is "played"/started) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. A Bundle instance is an Oskari class which implements `Oskari.bundle.BundleInstance` protocol. Usually you want to implement a BundleInstance since you can think of it as a starting point for your functionality which is triggered by just adding your bundle in an applications startup sequence. A Bundle instance is created as a result from a Bundle definitions (see above) create method. Bundle instance state and lifecycle is managed by Bundle Manager. However, the bundle doesn't need to have an instance and can be just used to import dependency files that can be instantiated elsewhere. @@ -27,7 +27,15 @@ instance.mediator = { #### Definition -The bundle definition (or package) should be located in `bundle.js` file under the `/packages` folder. The bundle package definition should not implement any actual functionality. It should only declare the JavaScript, CSS and localization resources (= files) and metadata (if any). If the bundle package can be instantiated the package's `create` method should create the bundle's instance. +The bundle package definition should not implement any actual functionality. It should only declare the JavaScript, CSS and localization resources (= files) and metadata (if any). If the bundle package can be instantiated, the package's `create` method should create the bundle's instance. + +Usually the bundle definition (or package) is located in `bundle.js` file under the `/packages` folder. + +As of 2024, the `bundle.js` file is used for +1. picking what files need to be imported when a bundle with certain id is being used in the app +2. define the way to include and split localization files when the application is built + +In this case, any CSS and most of Javascript can be imported on, from example, `instance.js`. If the bundle doesn't have an instance and is used to import dependency files that are instantiated elsewhere, the create method should return the bundle class itself (`return this;`). A sample bundle definition can be found as a file named `bundle.js` under `/packages///`. diff --git a/8 Developing instructions/00120-HowToCreateABundle.md b/8 Developing instructions/00120-HowToCreateABundle.md index d1b60da..4dcd22b 100644 --- a/8 Developing instructions/00120-HowToCreateABundle.md +++ b/8 Developing instructions/00120-HowToCreateABundle.md @@ -1,12 +1,14 @@ ## How to create a bundle -If you haven't done it already, download sources [here](https://oskari.org/download/). Then extract the files from the downloaded archive. +If you haven't done it already, copy the oskari-frontend repo [here](https://github.com/oskariorg/oskari-frontend/). Now decide a `` which is unique and describes the functionality the bundle offers e.g. `search` (already implemented so prefix it with something like mysearch). -Create a folder with the name of your `` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework//resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. It is encouraged to create your own namespace (and directories) for your own bundles. +Create a folder with the name of your `` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework//resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. -Create a `bundle.js` file under `/packages/framework//`. You can use the following sample as a template. +You can create your own namespace (and folders) for your own bundles. If you plan to contribute the bundle to oskari-frontend, place the bundle either to framework, mapping or admin depending on what the functionality is/does. + +Create a `bundle.js` file under `/packages/framework//`. You can use the sample file as a template (explained below). ### The Sample bundle diff --git a/9 Configuration instructions/00120-HowToModifyAppSetups.md b/9 Configuration instructions/00120-HowToModifyAppSetups.md index a8826cb..8343b93 100644 --- a/9 Configuration instructions/00120-HowToModifyAppSetups.md +++ b/9 Configuration instructions/00120-HowToModifyAppSetups.md @@ -42,39 +42,17 @@ The application specific migrations can of course be done however you want but t ### Modifying applications after the initial database population -Here's an example Flyway-migration that you can add on your server-extension code. Note that the order in which migrations are run is determined by the version number on the filename (the below would be 1.0.0). When you want to add a new migration after one has been run, you need to bump the version to a higher number like 1.0.1, 1.1.0, 2.0.0. So take a note a consider a versioning strategy for your Oskari instance. For best practices the version on the frontend codes package.json, the version on the server Maven modules pom.xml and the version on the Flyway migration should be tied to each other someway. Also note that the package reads `[your apps module]`. This is `example` on our sample-server-extension but can and should be changed to something that describes your app. (Not sure why we didn't call it "app" instead of "example" as that would have been more generic to use without renaming/might change this later). Note that you can also have multiple Flyway-modules on your app. The modules that are used when the server runs is set on `oskari-ext.properties` as `db.additional.modules`. +Here's an example Flyway migration that you can add on your server-extension code. -The migration name is after two underscores after the version. This can be anything you like on your application but it's easier to maintain if naming makes sense with the migration that is being run. - -``` -package flyway.[your apps module]; - -import org.flywaydb.core.api.migration.BaseJavaMigration; -import org.flywaydb.core.api.migration.Context; -import org.oskari.helpers.AppSetupHelper; -import org.oskari.helpers.BundleHelper; +Note that the order in which migrations are run is determined by the version number on the filename (the below would be 1.0.0). When you want to add a new migration after one has been run, you need to bump the version to a higher number like 1.0.1, 1.1.0, 2.0.0. So take a note a consider a versioning strategy for your Oskari instance. For best practices: the version on the frontend codes `package.json`, the version on the server Maven modules `pom.xml` and the version on the Flyway migration should be tied to each other some way. -import java.sql.Connection; +Open the folder `sample-server-extension/app-resources/src/main/java/flyway/app`. Inside, you will find various files that can be used as templates for your flyway migration. -/** - * Adds a bundle to all default/user appsetups - */ -public class V3_0_3__add_mybundle_to_apps extends BaseJavaMigration { +The code in each file begins with + package flyway.app; - public void migrate(Context context) throws Exception { - Connection connection = context.getConnection(); +The `app` on our sample-server-extension can and should be changed to something that describes your app (`custom_flyway_module`). Note that you can also have multiple Flyway-modules on your app. The modules that are used when the server runs are set on `oskari-ext.properties` in oskari-server as `db.additional.modules`. - // id for the bundle to be added - String bundleID = "mybundle"; - - // register a new bundle (for example application specific bundle to the database "oskari_bundle" table) - // this can be skipped when adding a "built-in" functionality to apps - BundleHelper.registerBundle(connection, bundleID); - - // add the bundle to - AppSetupHelper.addBundleToApps(connection, bundleID); - } -} -``` +The migration name is after two underscores after the version. This can be anything you like on your application but it's easier to maintain if naming makes sense with the migration that is being run. -For removing bundles after they have been added you can see the other methods available on the AppSetupHelper class. You also don't need to use these helpers and can modify the tables with for example SQL. These are just common operations so we have helpers for them to make it as easy as it can be. +For removing bundles after they have been added, you can see the other methods available on the AppSetupHelper class. You also don't need to use these helpers and can modify the tables with for example SQL. These are just common operations so we have helpers for them to make it as easy as it can be.