{"id":21430128,"url":"https://github.com/cuba-platform/currency-addon","last_synced_at":"2025-03-16T21:44:51.458Z","repository":{"id":150932104,"uuid":"139792091","full_name":"cuba-platform/currency-addon","owner":"cuba-platform","description":"Currency CUBA addon provides currencies and currency rates for CUBA application. Component is under development.","archived":false,"fork":false,"pushed_at":"2019-04-22T08:28:14.000Z","size":244,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-23T08:19:38.027Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuba-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-05T03:49:12.000Z","updated_at":"2019-10-02T18:08:20.000Z","dependencies_parsed_at":"2023-04-12T19:27:10.008Z","dependency_job_id":null,"html_url":"https://github.com/cuba-platform/currency-addon","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fcurrency-addon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fcurrency-addon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fcurrency-addon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fcurrency-addon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuba-platform","download_url":"https://codeload.github.com/cuba-platform/currency-addon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243940063,"owners_count":20372044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T22:20:57.275Z","updated_at":"2025-03-16T21:44:51.436Z","avatar_url":"https://github.com/cuba-platform.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)\n# currency-addon\n\n## Overview\nCurrency CUBA addon provides currencies and currency rates for CUBA application. Component is under development.\n\n## Content\n* [Installation](#installation)\n* [Usage](#usage)\n    * [1. Create currencies](#1-create-currencies)\n    * [2. Configure rate source](#2-configure-rate-source)\n    * [3. Create own entity](#3-create-own-entity)\n* [Demo Project](#demo-project)\n* [Configuration](#configuration)\n* [Implementation Details](#implementation-details)\n    * [Global Application Part](#global-application-part)\n        * [Entities](#entities)\n        * [Services](#services)\n    * [Core Part](#core-part)\n    * [Web Part](#web-part)\n        * [Predefined Screens](#predefined-screens)\n        * [Field Usage](#field-usage)\n            * [Auto Replace](#auto-replace)\n            * [XML Descriptor](#xml-descriptor)\n            * [Programmatic](#programmatic)\n    * [Currency Rates](#currency-rates)\n        * [Scheduled Task](#scheduled-task)\n        * [Providers](#providers)\n        * [Fixer.io](#fixer-io)\n    \n\n\n    \n    \n    \n## Installation\nTo add the component to your project, the following steps should be taken:\n\n1. Open your application in CUBA Studio. \n\n2. Edit Project properties.\n\n3. Click the plus button in the *App components* section of the *Main* tab.\n\n4. Specify the coordinates of the component in the corresponding field as follows: group:name:version.\n   Click *OK* to confirm the operation.\n    \n    * Artifact group: *\u003ccomponent group\u003e*\n    * Artifact name: *\u003ccomponent artifact name\u003e*\n    * Version: *add-on version*\n    \n        When specifying the component version, you should select the one, which is compatible with the platform version used\n    in your project.\n    \n    | Platform Version | Component Version |\n    |------------------|-------------------|\n    | 6.9.X            | 1.X.X             |\n    | 6.10.X            | 1.X.X             |\n\n\n## Usage\nSimple steps for work with currency addon:\n1. Create currencies (by default exist only USD currency)\n2. Configure rate source\n\n\n\n### 1. Create currencies\nBy default exists only USD currency. Need to create other currencies required in your project.\n\n\n\n### 2. Configure rate source\nBy default application doesn't have active providers. Need to implements self own provider or configure and activate existed.\n\n\n\nFor configure existed provider need to:\n1. Register at [fixer.io](http://fixer.io)\n2. Fetch `access key` at [fixer.io](http://fixer.io) profile.\n3. Set `access key` in addon configuration.\n4. Turn on scheduled task for auto update rated or call [`CurrencyRateWorkerMBean`](modules/core/src/com/haulmont/addon/currency/core/CurrencyRateWorkerMBean.java) method.\n\n\n\n### 3. Create own entity\nNow we can create entity with [`CurrencyRateAware`](modules/global/src/com/haulmont/addon/currency/entity/CurrencyRateAware.java) ([`Currency`](modules/global/src/com/haulmont/addon/currency/entity/Currency.java)) field type.\n\n## Demo Project\nAddon has [Demo Project](https://github.com/cuba-platform/currency-addon-demo) for showing use cases.\n\n\n## Configuration\nAddon has some configuration interfaces:\n* [`CurrencyApplicationProperties`](modules/core/src/com/haulmont/addon/currency/core/config/CurrencyApplicationProperties.java)\n* [`CurrencyConfig`](modules/global/src/com/haulmont/addon/currency/config/CurrencyConfig.java)\n\n\n##Implementation Details\n    \n### Global Application Part\n[`CurrencyRateAware`](modules/global/src/com/haulmont/addon/currency/entity/CurrencyRateAware.java) - is __interface__, amount of specific currency at specific date. \n\n\n\n#### Entities\n* [`CurrencyDescriptor`](modules/global/src/com/haulmont/addon/currency/entity/CurrencyDescriptor.java) - persist currency from real world like USD, EUR, BTC, ...\n* [`Currency`](modules/global/src/com/haulmont/addon/currency/entity/Currency.java) - implements [`CurrencyRateAware`](modules/global/src/com/haulmont/addon/currency/entity/CurrencyRateAware.java).\n* [`CurrencyRate`](modules/global/src/com/haulmont/addon/currency/entity/Currency.java) - rate for exchange from Currency1 to Currency2 at specific date.\n\n\n\n#### Services\n* [`CurrencyBigDecimalFormat`](modules/global/src/com/haulmont/addon/currency/format/CurrencyBigDecimalFormat.java) - can format and parse amount value depends on user `locale` and currency `precision`.\n* [`CurrencyService`](modules/global/src/com/haulmont/addon/currency/service/CurrencyService.java) - util service on global layer.\n\n\n\n### Core Part\n[`Currencies`](modules/core/src/com/haulmont/addon/currency/core/Currencies.java) - service helps to work with addon entities.\n\n\n\n### Web Part\n\n\n\n#### Predefined Screens\n* __Currencies__ - provide ability to manage currencies in system.\n* __Rates__ - show existed exchange rates between currencies.\n\n\n\n#### Field Usage\n\n\n\n##### Auto Replace\nUI field for entity field which implements interface [`CurrencyRateAware`](modules/global/src/com/haulmont/addon/currency/entity/CurrencyRateAware.java) will be automatically replaced by [`CurrencyAddonField`](modules/web/src/com/haulmont/addon/currency/web/gui/components/currency_field/CurrencyAddonField.java).\n\nF.e. we have entity `MyEntity` with field __sellAmount__ with type [`Currency`](modules/global/src/com/haulmont/addon/currency/entity/Currency.java) so in UI simple `com.haulmont.cuba.gui.components.TextField` will be replaced by [`CurrencyAddonField`](modules/web/src/com/haulmont/addon/currency/web/gui/components/currency_field/CurrencyAddonField.java).   \n```xml\n\u003cfieldGroup datasource=\"myEntityDs\"\u003e\n    \u003ccolumn width=\"250px\"\u003e\n        \u003cfield property=\"name\"/\u003e\n        \u003cfield property=\"sellAmount\"/\u003e\n    \u003c/column\u003e\n\u003c/fieldGroup\u003e\n```\n\n\n\n##### XML Descriptor\nAlso we can define [`CurrencyAddonField`](modules/web/src/com/haulmont/addon/currency/web/gui/components/currency_field/CurrencyAddonField.java) in screen XML descriptor:\n```xml\n\u003ccurrencyAddonField/\u003e\n```\n\n\n\n##### Programmatic\n```java\nimport com.haulmont.addon.currency.web.gui.components.currency_field.CurrencyAddonField;\nimport com.haulmont.cuba.gui.xml.layout.ComponentsFactory;\n...\nComponentsFactory componentsFactory = ...;\nCurrencyAddonField currencyField = componentsFactory.createComponent(CurrencyAddonField.class);\n```\n\n\n\n## Currency Rates\n[`CurrencyRateWorkerMBean`](modules/core/src/com/haulmont/addon/currency/core/CurrencyRateWorkerMBean.java) - provides ability to update exchange rates immediately and some other actions.\n\n\n\n#### Scheduled Task\nAddon has preconfigured scheduled task for update exchange rates.\nIt __Turned Of__ by default and has period __4 hours__. \n\n\n\n### Providers\n[`CurrencyRateProvider`](modules/core/src/com/haulmont/addon/currency/core/CurrencyRateProvider.java) - is interface, it should provide exchange rates for specific currencies and date.\n\n\n\n##### Fixer.io\nCurrency addon has own implementation of [`CurrencyRateProvider`](modules/core/src/com/haulmont/addon/currency/core/CurrencyRateProvider.java) - [`FixerIOCurrencyRateProviderBean`](modules/core/src/com/haulmont/addon/currency/core/impl/FixerIOCurrencyRateProviderBean.java).\n\nIt uses REST API of [fixer.io](http://fixer.io) exchange rates provider.\nThis provider requires registration and providing API KEY to addon configuration.\nIt uses configuration interface [`FixerIOConfig`](modules/core/src/com/haulmont/addon/currency/core/impl/FixerIOConfig.java).\n\nRequired parameter: `addon.currency.fixerIO.apiKey`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fcurrency-addon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuba-platform%2Fcurrency-addon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fcurrency-addon/lists"}