Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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.
- Host: GitHub
- URL: https://github.com/marckrenn/framer-QueryInterface
- Owner: marckrenn
- License: mit
- Created: 2017-03-23T14:09:29.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-04-23T14:48:36.000Z (over 6 years ago)
- Last Synced: 2024-08-04T00:10:24.898Z (5 months ago)
- Language: CoffeeScript
- Size: 16.6 KB
- Stars: 27
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-framer - framer-QueryInterface - Module that allows Framer prototypes to read variables from and write variables to the last part of their URL (the query). (Modules)
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.