Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/marckrenn/framer-QueryInterface

Allows Framer prototypes to read variables from and write variables to the last part of their URL, the query.
https://github.com/marckrenn/framer-QueryInterface

Last synced: about 2 months ago
JSON representation

Allows Framer prototypes to read variables from and write variables to the last part of their URL, the query.

Awesome Lists containing this project

README

        

# framer-QueryInterface

This module allows Framer prototypes to **read variables from** and **write variables to** the last part of their URL, the *query*. This way, data can be injected into the prototype via the address bar. Plus, it handles data persistence via HTML5 localStorage and introduces some strict-ish / implicit type conversion for injected values.


## Demo Projects

| Supported Types | Beginner |
| :---: | :---: |
| ![png](http://i.imgur.com/tfGXpFl.png) | ![png](https://framer.cloud/ebcEA/framer/social-800x600.png) |
| Basic overview of all supported data types | Change the prototype's backgroundColor via the address bar |
| Live @ [QI dataTypes](https://framer.cloud/ppeGW/) | Live @ [QI bgColor](https://framer.cloud/ebcEA/) |

| Intermediate | Intermediate |
| :---: | :---: |
| ![png](https://framer.cloud/MriJR/framer/social-800x600.png) | ![png](https://framer.cloud/AbGDe/framer/social-800x600.png) |
| Loads a profile image from Twitter and saves / loads filter values | Combined use with *Flow Component*: Link to specific screen PLUS auto-refresh benefits in Framer IDE |
| Live @ [QI filter](https://framer.cloud/MriJR/) | Live @ [QI flow](https://framer.cloud/AbGDe/) |

**Additional Demo Projects**

| Link | Description |
| :---: | :--- |
| [QI device](https://framer.cloud/Txmyt/) | Allows a valid Framer.device to be set via the *query*. All valid device names are listed in the console. |


## Getting started

If you haven't already, I strongly recommend reading my [*QueryInterface article on Medium*](https://medium.com/@marc_krenn/queryinterface-a-query-based-api-for-framer-prototypes-cb99f595d984) first.

| Step | Instruction |
| :---: | :--- |
| **1** | Download the [QueryInterface module](https://github.com/marckrenn/framer-QueryInterface/archive/master.zip) and unzip the downloaded archive |
| **2** | Put `QueryInterface.coffee` into your prototype's `modules`-folder or *drag'n'drop* it onto the Framer window |
| **3** | Add or change the autogenerated `require`-line on the top of the code to `{QueryInterface} = require 'QueryInterface'` |
| **4** | Save (*CMD+S*) your project to get Framer to load the module |
| **5** | Initiate and use your first *QueryInterface* variable: |

```coffee
{QueryInterface} = require 'QueryInterface'

bgColor = new QueryInterface
key: "bgColor" # key used in address bar: ?bgColor=28affa
default: "28affa" # fallback / initial color = 'Framer blue' (hex color)

Canvas.backgroundColor = bgColor.value

window.addEventListener 'click', ->
bgColor.value = Canvas.backgroundColor = Utils.randomColor().toHex()
```

| Step | Instruction |
| :---: | :--- |
| **6** | In Framer, click *Mirror* → *Open in Browser* **OR** upload your project to Framer *Cloud* |
| **7** | You can now enter a new value for `?bgColor=` via the address bar (see gif on top of the page)                           | 
| **8** | Hit return to inject the newly set color into the prototype. |


### Important notes
| Note | |
| :---: | :--- |
| **1** | *QueryInterface* variables are by design more implicit than regular Javascript / coffeescript variables. This is required in order to prevent the prototype from crashing, for example when invalid or unwanted assignments were made to a QueryInterface variable (eg. your code expects a value of data type *number* but receives a *string* from the address bar instead). QueryInterface will always try to convert the new assignment to the expected data type, however, if that conversion fails, it will fall back to a predefined value assigned to [queryInterface.default](#-queryinterfacedefault).
| **2** | If your prototype stops due to `SecurityError (DOM Exception 18)`, try to limit updates to [queryInterface.value](#-queryinterfacevalue) and / or remove [QueryInterface.query()](#-queryinterfacequery) from your code. |


### Contact & Help
If you need further assistance or want to leave me some feedback, you can reach me via [Twitter](https://twitter.com/marc_krenn), [Facebook](https://www.facebook.com/groups/framerjs/permalink/1111435055650231/), [Slack](https://framer-slack-signup.herokuapp.com/), [Medium](https://medium.com/@marc_krenn/queryinterface-a-query-based-api-for-framer-prototypes-cb99f595d984) or here on Github.


---


## QueryInterface Class Reference

| Table of contents |
| :--- |
| [**1) Properties**](#1-properties) |
| --- [**A) Required Properties**](#a-required-properties) |
| ------- [queryInterface.key](#-queryinterfacekey) |
| ------- [queryInterface.default](#-queryinterfacedefault) |
| --- [**B) Optional Properties**](#b-optional-properties) |
| ------- [queryInterface.value](#-queryinterfacevalue) |
| ------- [queryInterface.publish](#-queryinterfacepublish) |
| ------- [queryInterface.fetchQuery](#-queryinterfacefetchquery) |
| ------- [queryInterface.default](#-queryinterfacedefault) |
| ------- [queryInterface.saveLocal](#-queryinterfacesavelocal) |
| ------- [queryInterface.loadLocal](#-queryinterfaceloadlocal) |
| --- [**C) Read-Only Properties**](#c-read-only-properties) |
| ------- [queryInterface.type](#-queryinterfacetype) |
| [**2) Methods**](#2-methods) |
| --- [A) Instance Methods](#a-instance-methods) |
| ------- [queryInterface.reset()](#-queryinterfacereset) |
| --- [**B) Class Methods**](#b-class-methods) |
| ------- [QueryInterface.resetAll()](#-queryinterfaceresetall) |
| ------- [QueryInterface.query()](#-queryinterfacequery) |




### 1) Properties

#### A) Required Properties

#### • **queryInterface.key**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**key** | undefined | string |

Defines the *query*-key of the variable (eg. `?bgColor=someColor` in the browser's address bar, *bgColor* being the *query*-key). Also, [queryInterface.value](#-queryinterfacevalue) will be saved locally using this key.


#### • **queryInterface.default**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**default** | undefined | boolean, number, string or object |

Defines two things:
- a fallback value which will be used if no valid value could be loaded, neither from the address bar NOR from localStorage and
- it automatically defines the to-expected data type (*boolean*, *number*, *string* or *object*) of future [queryInterface.value](#-queryinterfacevalue) assignments

**Example:** If `queryInterface.default` is set to a value of type *string*, for instance `"foo"`, QueryInterface will then try to convert any new assignment – either via the address bar or via [queryInterface.value](#-queryinterfacevalue) – to a *string*. In this scenario, if the number `100` was entered, it would be automatically converted to the string `"100"`. If the type conversion fails for whatever reason, the value of [queryInterface.default](#-queryinterfacedefault) will be assigned instead.


#### B) Optional Properties

#### • **queryInterface.value**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**key** | queryInterface.default | must be same type as queryInterface.default |

Carries the value of a *QueryInterface*-variable. It can be used to get the current, or to set a new value. Assigning a new value to this property will be reflected in the *query*.

| Note | |
| :---: | :--- |
| **1** | If `queryInterface.value` is set to `"/reset/"` or `"/default/"`, the value of [queryInterface.default](#-queryinterfacedefault) will be assigned instead, similar to [queryInterface.reset()](#-queryinterfacereset) |
| **2** | **Loading priority:** Values are, by default, loaded in the following priority:
`Query (from address bar) > Locally saved > queryInterface.default` This sequence can be modified by changing the following optional properties |


#### • **queryInterface.publish**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**publish** | true | boolean |

If set to `false`, [queryInterface.value](#-queryinterfacevalue) will NOT be published to the query in the address bar. However, data can still be injected by entering the right key manually. To prevent this, set [queryInterface.fetchQuery](#-queryInterfacefetchquery) to `false`.


#### • **queryInterface.fetchQuery**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**fetchQuery** | true | boolean |

If set to `false`, new assignments made via the address bar will NOT be injected into the prototype.


#### • **queryInterface.saveLocal**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**saveLocal** | true | boolean |

If set to false, [queryInterface.value](#-queryinterfacevalue) will NOT be saved locally.


#### • **queryInterface.loadLocal**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**loadLocal** | true | boolean |

If set to `false`, previously saved [queryInterface.value](#-queryinterfacevalue) will NOT be loaded from localStorage.

#### C) Read-Only Properties

#### • **queryInterface.type**
---
| Property | Default Value | Type |
| :--- | :--- | :--- |
| queryInterface.**type** | undefined | typeof queryInterface.default |

Returns the data type that was automatically set via [queryInterface.default](#-queryinterfacedefault). New assignments to a QueryInterface variable will be converted to this data type.


### 2) Methods

#### A) Instance Methods

#### • **queryInterface.reset()**
---
| Method | Arguments | Returns | Return type |
| :--- | :--- | :--- | :--- |
| queryInterface.**reset()** | none | [queryInterface.default](#-queryinterfacedefault) | typeof [queryInterface.default](#-queryinterfacedefault) |

Sets [queryInterface.value](#-queryunterfacevalue) to the value of [queryInterface.default](#-queryinterfacedefault). Only use temporarily.


#### B) Class Methods

#### • **QueryInterface.resetAll()**
---
| Method | Arguments | Returns | Return type |
| :--- | :--- | :--- | :--- |
| QueryInterface.**resetAll()** | none | nothing (reloads prototype) | none |

Resets all QueryInterface variables in the current prototype to their [queryInterface.default](#-queryinterfacedefault)-value. Reloads the prototype. Only use temporarily.


#### • **QueryInterface.query**
---
| Method | Arguments | Returns | Return type |
| :--- | :--- | :--- | :--- |
| QueryInterface.**query()** | none | preview of query | String |

Returns a preview / simulation of what the query will look like in the address bar. Only use temporarily for debugging purposes.