Update HowToCreateABundle.md #52

rekjuh · 2024-10-25T11:09:50Z

Add URL, fix ´´

Add missing link and try to fix ´´ in the beginning

into develop

Double-check the content to match what's requested in oskariorg#30

ZakarFin · 2024-11-27T13:27:15Z

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 develop or maintain Oskari yourself this is the correct section.


Should this be Oskari-based application or develop/maintain Oskari or both? Since telling people to first start with customizing the application before diving head first into developing Oskari itself might be a better starting point.

Fixes this issue: oskariorg#35

ZakarFin · 2024-11-27T14:59:52Z

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).


Should we use module instead of component here? Added some other changes to the text as well

Suggested change

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).

ZakarFin · 2024-11-27T15:04:29Z

7 Operating instructions/00080-HowToUseABundle.md


 #### 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. 


Suggested change

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.

ZakarFin · 2024-11-27T15:04:54Z

7 Operating instructions/00080-HowToUseABundle.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.


We now use folder and directory as terms. Maybe we should pick one and stick to it.

ZakarFin · 2024-11-27T15:08:05Z

7 Operating instructions/00080-HowToUseABundle.md

@@ -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. 


"The bundle definition (or package) should be located in bundle.js file under the /packages folder". This is not always true anymore and this might change in a very near future. However, for now I think this might be accurate enough.

Also, any CSS and most of Javascript can be imported now on for example the instance.js. The bundle.js file is currently mostly used for picking what the files that need to be imported when a bundle with certain id is being used in the app AND the way to include and split localization files when the application is built.

ZakarFin · 2024-11-27T15:12:07Z

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.


The sources are not really in the zip-file at least anymore. They can be found on GitHub. Or what does the sources here mean?

ZakarFin · 2024-11-27T15:14:36Z

8 Developing instructions/00120-HowToCreateABundle.md


-Now decide a `<bundle-identifier>` 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 `<bundle-identifier>` 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 `<bundle-identifier>` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework/<bundle-identifier>/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.


"It is encouraged to create your own namespace (and directories) for your own bundles." We don't really care what people do with application specific bundles. If it's a contribution to oskari-frontend, then we care and it probably should be either framework, mapping or admin currently depending on what the functionality is or does.

ZakarFin · 2024-11-27T15:15:51Z

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`.



Should we just link something from sample-server-extension instead of having code here?

Should we rename this now?

"(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)"

rekjuh and others added 5 commits October 25, 2024 13:01

Update How to create a bundle

6093911

Add missing link and try to fix ´´ in the beginning

Update 00120-HowToCreateABundle.md

4d44ac8

Update HowToUseABundle and HowToCreateABundle

9432d1b

Merge branch 'develop' of https://github.com/rekjuh/oskari-documentation

662678d

into develop

Update SetupDevelopmentEnvironment.md

b92f641

Double-check the content to match what's requested in oskariorg#30

ZakarFin reviewed Nov 27, 2024

View reviewed changes

Update version number examples to 1.0.0

cb2993d

Fixes this issue: oskariorg#35

ZakarFin reviewed Nov 27, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update HowToCreateABundle.md #52

Update HowToCreateABundle.md #52

rekjuh commented Oct 25, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024 •

edited

Loading

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024

ZakarFin Nov 27, 2024 •

edited

Loading

Update HowToCreateABundle.md #52

Are you sure you want to change the base?

Update HowToCreateABundle.md #52

Conversation

rekjuh commented Oct 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZakarFin Nov 27, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZakarFin Nov 27, 2024 • edited Loading

Choose a reason for hiding this comment

ZakarFin Nov 27, 2024 •

edited

Loading

ZakarFin Nov 27, 2024 •

edited

Loading