Awesome
<p align="center"><img src="http://i.imgur.com/cPe31yo.png"></p>
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.
<br />
<p align="center"><img src="https://fat.gfycat.com/QuickAntiqueGoldfish.gif"></p>
<br />
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 | Live @ QI bgColor |
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 | Live @ QI flow |
Additional Demo Projects
Link | Description |
---|
QI device | Allows a valid Framer.device to be set via the query. All valid device names are listed in the console. |
<br />
Getting started
If you haven't already, I strongly recommend reading my QueryInterface article on Medium first.
Step | Instruction |
---|
1 | Download the QueryInterface module 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: |
{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. |
<br />
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). </br> </br> 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. |
2 | If your prototype stops due to SecurityError (DOM Exception 18) , try to limit updates to queryInterface.value and / or remove QueryInterface.query() from your code. |
<br />
Contact & Help
If you need further assistance or want to leave me some feedback, you can reach me via Twitter, Facebook, Slack, Medium or here on Github.
<br />
<br />
QueryInterface Class Reference
<br />
<br />
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 will be saved locally using this key.
<br />
• 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 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 – 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 will be assigned instead.
<br />
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 will be assigned instead, similar to queryInterface.reset() |
2 | Loading priority: Values are, by default, loaded in the following priority: <br /> Query (from address bar) > Locally saved > queryInterface.default This sequence can be modified by changing the following optional properties |
<br />
• queryInterface.publish
Property | Default Value | Type |
---|
queryInterface.publish | true | boolean |
If set to false
, queryInterface.value 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 to false
.
<br />
• 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.
<br />
• queryInterface.saveLocal
Property | Default Value | Type |
---|
queryInterface.saveLocal | true | boolean |
If set to false, queryInterface.value will NOT be saved locally.
<br />
• queryInterface.loadLocal
Property | Default Value | Type |
---|
queryInterface.loadLocal | true | boolean |
If set to false
, previously saved queryInterface.value will NOT be loaded from localStorage.
<br />
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. New assignments to a QueryInterface variable will be converted to this data type.
<br />
2) Methods
A) Instance Methods
• queryInterface.reset()
Sets queryInterface.value to the value of queryInterface.default. Only use temporarily.
<br />
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-value. Reloads the prototype. Only use temporarily.
<br />
• 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.
<br />