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
Basic overview of all supported data types	Change the prototype's backgroundColor via the address bar
Live @ QI dataTypes	Live @ QI bgColor

Intermediate	Intermediate
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.

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.

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.
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.

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.

---

QueryInterface Class Reference

Table of contents
1) Properties
--- A) Required Properties
------- queryInterface.key
------- queryInterface.default
--- B) Optional Properties
------- queryInterface.value
------- queryInterface.publish
------- queryInterface.fetchQuery
------- queryInterface.default
------- queryInterface.saveLocal
------- queryInterface.loadLocal
--- C) Read-Only Properties
------- queryInterface.type
2) Methods
--- A) Instance Methods
------- queryInterface.reset()
--- B) Class Methods
------- QueryInterface.resetAll()
------- QueryInterface.query()

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.

• 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.

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: 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 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.

• 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 will NOT be saved locally.

• queryInterface.loadLocal

---

Property	Default Value	Type
queryInterface.loadLocal	true	boolean

If set to false, previously saved queryInterface.value 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. 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	typeof queryInterface.default

Sets queryInterface.value to the value of queryInterface.default. 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-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.