Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dan-shields/nodecg-vue-composable

Vue composables to interact more predictably with NodeCG replicants
https://github.com/dan-shields/nodecg-vue-composable

composition-api nodecg vue vue3 vuejs vuejs2

Last synced: about 2 months ago
JSON representation

Vue composables to interact more predictably with NodeCG replicants

Awesome Lists containing this project

README 

        
# nodecg-vue-composable

### A set of Vue composables for interacting more predictably with NodeCG replicants.

#### Works with Vue 2 & Vue 3 thanks to [vue-demi](https://github.com/vueuse/vue-demi).



`useReplicant` is a happy medium between manually syncing a vue reactive value with a nodecg replicant on every change and not using reactivity at all. It forces you to be explicit about when a replicant should be updated while still providing reactivity for easy `v-model` binding.



## Usage

**Note**: use of composables requires the [Vue Composition API](https://v3.vuejs.org/guide/composition-api-introduction.html), either importing it directly from Vue 3 or using the `@vue/composition-api` package with Vue 2. You are also required to create components using `defineComponent`.



### `useReplicant(name, namespace, opts)`



A (sort-of) two-way binding that keeps a separate copy of the latest replicant value locally which you're free to modify. Doesn't update the replicant itself until you explicitly tell it to.



Returns an object with the following properties:

- `data`: a `ref` that stores the current local value

- `changed`: a `ref` bool indicating if the local value is different to the replicant value

- `upToDate`: a `ref` bool indicating if the replicant has been updated since the local copy was first changed (i.e. if true, saving will overwrite a change from elsewhere)

- `save()`: a function to commit the locally current value to the replicant

- `revert()`: a function to set `data` to the replicant value (clearing local changes)

- `loadDefault()`: a function to reset the local value to the default value of the replicant

- `oldData`: a readonly `ref` of the latest replicant value



Update the value (`data`) programatically or in a template binding and commit it with `save()`.



If the local value is out of sync when a new value comes in from the replicant, it won't update (indicated by `upToDate`). If it's unchanged however, `data` will be updated and propagate to your bindings.



#### Example



```html



    


        

        

            SAVE

        

        

            REVERT CHANGES

        

        

            CLEAR

        

    



import { defineComponent } from 'vue' // or '@vue/composition-api' with vue 2

import { useReplicant } from 'nodecg-vue-composable'



export default defineComponent({

    setup() {

        const lowerThird = useReplicant('lowerThird', { defaultValue: '' })



        return {

            lowerThird

        }

    }

})



```



### `useAssetReplicant(name)`

A read-only binding to an asset replicant with the name `assets:`.



#### Example

```html



    


        

            Select a logo...

            

                {{ logoAsset.name }}

            

        

        

            SAVE

        

        

            REVERT CHANGES

        

        

            CLEAR

        

    



import { defineComponent } from 'vue' // or '@vue/composition-api' with vue 2

import { useReplicant, useAssetReplicant } from 'nodecg-vue-composable'



export default defineComponent({

    setup() {

        const logo = useReplicant('logo', { defaultValue: null })

        const logos = useAssetReplicant('logos')



        return {

            logo,

            logos

        }

    }

})



```

### `useDynamicReplicant(name, namespace, opts)`

If you want to use a name that is itself reactive use a `useDynamicReplicant` (name suggestions welcome).



Only usage difference with `useReplicant` is that it returns a `ref` that wraps the reactive, so if you want to use it inside the setup function or another composable you need to access the `value` before `data`. Usage inside the template is unaffected as the unwrapping will be done for you.



I.e. instead of:



```javascript

const rep = useReplicant('repName')

rep.data = '....'

```

You need to do:

```javascript

const repName = toRef(props, 'repName')  // example reactive name



const rep = useDynamicReplicant(repName)

rep.value.data = '....'

```



## Installation



### Vue 3

`npm install -D nodecg-vue-composable`

### Vue 2

`npm install -D @vue/composition-api nodecg-vue-composable`



Setup `@vue/composition-api` by adding the following to your entry file:

```javascript

import VueCompositionApi from '@vue/composition-api'



Vue.use(VueCompositionApi)

```

## Todo

- ~~Add TypeScript typings~~

- Write some tests

- ~~Come up with a better name for DynamicReactiveReplicant~~