aico-image-editor/readme.md

Combine multiple image into and create single combined image

# Installation
`npm install aico-image-editor`

`npm run dev`


## Dependencies
**aico-image-editor** requires you to add these two libraries before adding script from the package
Add these two lines before adding link to the package.

1. [fabric.js](http://fabricjs.com/) which is for doing canvas based operations very efficiently
2. [fabriceraser.js](http://fabricjs.com/erasing) which is taken as an addon to the fabric for having the eraser functionality.

```
<script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.0/fabric.min.js"></script>

<script src="{{ url('js/fabriceraser.js') }}" ></script>
```

3. In addition to above, package requires you to have these libraries to be present at window(global) level as they were used as a peerDependencies in the package. These libraries are
[bootstrap](https://getbootstrap.com/docs/5.3/getting-started/introduction/), [alpinejs](https://alpinejs.dev/) and [@alpinejs/persist](https://alpinejs.dev/plugins/persist). So check whether these are present and if not please add them manually.


## Usage
After running above commands in [installation](#installation) step, it will basically publish folder named `aico-image-editor/output` in the public directory.

You can get the umd version of the package from there. 
Please note that you need to add `data-app-url` and `data-openai-api-key` attributes along with the script to inform the library about your application url with workspace if any so that it can create public path (link to images and other assets like fonts etc...) starting from that url. and api key for open ai platform for ai related operations.

For example, this is how it is used in laravel

`script src="{{ url('aico-image-editor/output/js/index.js') }}" data-app-url="{{ config('app.url') }}"
        data-openai-api-key="{{ env('OPENAI_KEY') }}"></script>`


### Within the html.

Once all of the above scripts have been added, you can initialize on the element like this. imageModalToggle is the name of alpine data which you will be using to pass apiConfig object to configure the canvas configurator.

```
    div x-data="imageModalToggle({
        apiUrl: '{{ config('app.url') }}',
        apiToken: '{{ $apiToken }}',
        configuratorId: '{{ $configuratorId }}',
        productId: '{{ $productId }}',
        locale: '{{$currentLanguage}}',
        productMainImage: '{{$productMainImage}}',
        eventId: '{{$eventId}}'
    })" @click="updateConfigurator()">
</div>

```

Let's understand each and every parameter step by step which needs to be passed as the `apiConfig` object.

- **apiUrl**: this should be your workspace url same as `data-app-url` attribute in the script.
- **apiToken**: this is the token which is used for authentication im the header along with the request.
- **configuratorId**: this is the id for which you would want to reload configuration that you saved earlier.
- **productId**: this is the id for which new configuration will be created. if configuratorId is not there and productId is present, new configurator will be auto created for that productId when you save.
- **locale**: currently active locale for translation. Only two values are allowed for now which `en_US` and `de_CH`.
- **productMainImage**: this should be the path to the main image (which will appear in the first pictured tab) which you need to update every time you open the configurator.
- **eventId**: this should be unique id associated with the component so that event with this name can be triggered after save.

Once you initialized the configurator on any element this way, you can get the bundle image from it when you hit save button by using 
event which is named using this convention: `@bundle-image-processed-<eventId>.window`. It will create `bundleFile` which can be obtained using event.detail.bundleFile.


e.g. in laravel livewire, this is how it can be used to upload the file to component using `$wire.upload` syntax in alpine js.
```
@bundle-image-processed-{{$eventId}}.window="($event) => {
    if($event.detail.bundleFile) {
        $wire.upload('uploadedImage', $event.detail.bundleFile)
    }
}"
```


### In the script which consumes library.

```
const {prepareEditorHTML, productPicturesData, updateEditorConfig} = window.aicoEditor
```

`window.aicoEditor` provides us theese three information which is needed. So we are destructring and storing them in individual variables.

- **prepareEditorHTML** - It is one button html which package will add inside your given/passed element.
- **productPicturesData** - It is the plain object version of the mainPictures alpine data. You need to pass this to `Alpine.reactive` method to be able to modify it.
- **updateEditorConfig** - It is the function which updates the configuration of editor everytime just before the configurator modal opens. It expects `$store` and `apiConfig` as parameters. so that it can loads the configuration with updated values after configuratorId changes


```
document.addEventListener('alpine:init', function() {
    Alpine.data('imageModalToggle', (apiConfig = {}) => ({
        init() {
            prepareEditorHTML(this.$el);
        },
        
        updateConfigurator() {
            updateEditorConfig(this.$store, apiConfig)

            const productPictures = Alpine.reactive(productPicturesData);
            productPictures.mainPictures = [];

            if(apiConfig?.productMainImage) {
                let url = apiConfig?.productMainImage;

                productPictures.mainPictures.push({
                    id: `main-image-${apiConfig.productId}`,
                    url: url,
                    label: url.substring(url.lastIndexOf("/") + 1, url.lastIndexOf("."))
                })

            }
        },
        
    }))
})
```

This way, when element is initialized, library will append button element inside element. and then you can create function like `updateConfigurator` above to update configuration each time someone clicks the button to open the modal using `updateEditorConfig` function obtained from the package. This sends $store and apiConfig information necessary for function to work.

You can also empty older mainPictures by resetting array to empty and then again populating new values for `productPictures.mainPictures` which is what this code is for. If you want to add subPictures you need to push to `productPictures.subPictures`.

```
const productPictures = Alpine.reactive(productPicturesData);
productPictures.mainPictures = [];

if(apiConfig?.productMainImage) {
    let url = apiConfig?.productMainImage;

    productPictures.mainPictures.push({
        id: `main-image-${apiConfig.productId}`,
        url: url,
        label: url.substring(url.lastIndexOf("/") + 1, url.lastIndexOf("."))
    })
}
```

id, url and label are needed for the `mainPicture` object to push to the existing array of `mainPictures`. 

> Note that we have generated label by extracting the file's name information from `productMainImage` itself but you can use any other label string which suits you. label is necessary for searching through that label in searchbox.



> [!TIP]: 
> We have already created component which can be directly used by using the above way in livewire. If productId and configuratorId both are null then this editor can just be used to get image output as a bundleFile via the event.

```
<div>
    <livewire:pim::pages.bundles.image-combiner-modal
            :configuratorId="<configuratorId>"
            :productId="<productId>"
            :eventId="<eventId>"
            :productMainImage="<productMainImagePath>"
            :modalEl="'<modalElementId>'"
            wire:key="<Unique_livewire_key>"
    />
</div>
```

and then we can get the final file using event we illustrated earlier.