/framer-QueryInterface

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

Primary LanguageCoffeeScriptMIT LicenseMIT

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

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