diff --git a/3 Setup instructions/00040-SetupDevelopmentEnvironment.md b/3 Setup instructions/00040-SetupDevelopmentEnvironment.md index 61e6984..7a9bd4f 100644 --- a/3 Setup instructions/00040-SetupDevelopmentEnvironment.md +++ b/3 Setup instructions/00040-SetupDevelopmentEnvironment.md @@ -1,15 +1,16 @@ ## 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 customize Oskari, this is the correct section. + +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/) - 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 @@ -22,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. -Additional Maven modules can be contributed outside git though if they are compatible with the current develop/master branch, but this is not adviced. +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 sample application, including its source code and build, is available in `{jetty.base}/sample-application` within the [Jetty bundle](/download). The Jetty bundle uses the pre-built code located in the `dist` folder. To update the sample application you can replace the contents of the `sample-application` folder with a clone from https://github.com/oskariorg/sample-application, and build the application following the instructions in its README.md file. ### 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 2ff4a4f..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,13 +29,13 @@ 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: ``` - 1.55.1 + 1.0.0 ... ``` @@ -34,18 +44,20 @@ To the new version: ``` - 1.56.0 + 1.0.1 ... ``` + 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.55.2" + "oskari-frontend": "https://git@github.com/oskariorg/oskari-frontend.git#1.0.0" }, ``` @@ -53,23 +65,23 @@ 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" }, ``` -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 340b1de..2b685f0 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 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 Application environment/00020-Frontend.md) for info about structure and conventions. +See [here](../2%20Application%20environment/00040-DirectoryStructure.md) for information 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. +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. 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,17 @@ 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 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) +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///`. 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..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](). 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). +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 20f8f8f..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 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. -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.