It's a framework to automatically bootstrap Framer.js prototypes.
Framer.js is an awesome tool for making high fidelity prototypes, but it can be overwhelming. Since everything in Framer.js must be coded, it becomes really painful to implement a lot of small and repetitive interactions: you spend a lot of time writing and getting lost in hundreds of lines of code.
That's why I wrote ProtoSparker, a Framer.js module that takes care of generating these common interactions automatically, so that you only have to code what REALLY needs coding.
You just have to name your layers following some conventions (see references below) and instantiate ProtoSparker. It will handle everything else for you.
Open your layout inside Figma or Sketch and rename the layers you want to interact with using the References as a guideline. Try adding a scrollable layer by renaming a group layer to "scroll".
- Import this project inside Framer.js
- Download
dist/ProtoSparker.jsand place it into your project/modules folder. - Import protoSparker module inside your project's file and instantiate it:
figma = Framer.Importer.load("imported/Your project@1x")
require 'ProtoSparker'
protoSparker = new ProtoSparker
# pass a layer as the first page
firstPage: figma.pageLayerThat's it! Now go back to your design software, start changing layers names following the naming usage and reimport them back to Framer.js.
You can also import SVG files to work with Framer. This means you can use it outside a Mac, with the Framer open source engine. Bear in mind that this Importer is highly experimental, so don't expect perfect imports.
Grab our dist/ProtoSparker.js and place it inside your project's modules folder. Then type:
require 'ProtoSparker'
importer = new SvgImporter
files: ['img/page1.svg', 'img/page2.svg']
protoSparker = new ProtoSparker
firstPage: f('page1') # the name of the artboard or svg filenameFirst you'll have to download Framer.js library (visit this page and download the latest framer.js, use the link on the left called 'framer.js'). Then, you'll have to include this script alongside ProtoSparker (download it at dist/ProtoSparker.js) in an HTML file and serve it via a web server.
<!DOCTYPE html>
<html>
<head><meta charset="utf-8"></head>
<body>
<script src="js/framer.js"></script>
<script src="js/ProtoSparker.js"></script>
<script type="text/javascript">
var importer = new SvgImporter({
editableSvg: true,
files: [ 'img/page1.svg', 'img/page2.svg' ]
});
var protoSparker = new ProtoSparker({
firstPage: f('page1') // name of the artboard or svg filename
});
</script>
</body>
</html>You have to serve this page with an HTTP server so that our script can request your svg files. If you are on Mac or Linux, open your terminal, navigate to the project folder and type python -m SimpleHTTPServer 8000 or python -m http.server 8000 - hit enter and visit http://localhost:8000 in your browser. If you are on Windows, you can download MiniWeb, drop you html files and images inside htdocs folder, run miniweb.exe and visit http://localhost:8000.
Try renaming some complex layer groups to "flatten;". See Flatten Feature
Not running on Firefox: Firefox has a bug dealing with .getBBox().
Drop shadows: This is much harder than it seems.
importer = new SvgImporter
editableSvg: true,
files: [ "img/page1.svg", "img/page2.svg" ]If you enable this, the SVG slices will be imported using Framer built in SVG API. This enables you to modify the SVG paths directly. By now it's toggled off for testing purposes, soon this will be enabled by default.
Here you pass the files you want to import into Framer. If this SVG doesn't contain a root group with an "id" or "data-name" (like an artboard), SVGImporter will set its Framer root layer name as the SVG filename.
Turn it on if you want to see how much time is taking to load each file.
Startup usage
firstPage
textField
selectField
goto
goback
flatten
scroll
text-field
select-field
overlay
element
setElement
protoSparker = new ProtoSparker
# this is the object
firstPage: layer # this is the optionThis is the layer that shows up when the prototype boots. You can navigate between layers using the goto action. This is required
This option allows you to customize the HTML input created by text-field.
protoSparker = new ProtoSparker
textField:
defaultClass: "ps-text-field" # this is set by default
placeholderText: "" # text when input is empty
styles:
default:
field:
# add any css property and value as strings
"color": "#121212"
placeholder:
# add any css property and value as strings
"color": "#CBCACA"This option allows you to customize the HTML selects created by select-field.
protoSparker = new ProtoSparker
selectField:
defaultClass: "ps-select-field" # this is set by default
placeholderText: "" # text when input is empty
styles:
default:
field:
# add any css property and value as strings
"color": "#121212"
placeholder:
# add any css property and value as strings
"color": "#CBCACA"If set to true, shows outline hints to help user know where she can interact with.
ProtoSparker is based on layer names to automatically set up the expected behavior.
That means if you want a layer to scroll, you name it "scroll;". If you want it to be a select field, you name it "select-field;".
Every feature we have is based on the same layer naming convention:
"action:target[option:value,option:value];"
Actions define the wanted feature, target defines where it should be applied and options define additional settings we might want to apply. Some features require targets, some features don't. Some features allow options, other features don't.
You can also chain features after the semicolon:
"action;action:target;action:target[option:value];"
Just remember the convention to make sure the layer name is well formatted.
When a layer with this name is clicked, the prototype will transition the current page to targetLayer. E.g.: when a layer named "goto:page1;" is clicked, the prototype will set "page1" as the new page and transition into it.
You can pass a transition option and control the animation when transition happens. The values for the transition can be fade, slideUp, slideDown, slideLeft, slideRight.
This layer name will make the prototype return to the last page it visited. It's really useful for back buttons.
When using SvgImporter, this will flatten a group into a single layer, improving dramatically the loading and render times. It's specially useful for illustration groups, because they usually have a lot of layer that slows down creation of framer layers.
This makes the layer / group automatically scrollable. By default it's set to scroll vertically
You can pass the options horizontal or vertical to control the scroll behavior.
This will turn the layer into a <input[type="text"]> field. If you want to override the default css or apply a style for the placeholder, check select-field styling .
This will turn the layer into a <select> field. If you want to override the default css or apply a style for the placeholder, check select-field styling.
The options will be rendered as <option> tags inside the <select>.
Eg.: a layer named "select-field[Apple,Microsoft,Amazon:cool];" will be rendered as:
<select>
<option>Apple</option>
<option>Microsoft</option>
<option value="cool">Amazon</option>
</select>When a layer with this name is clicked, it will overlay "targetLayer" at the center of the prototype.
You can explicitly pass a position for the overlay. The options can be "top", "right", "bottom", "left" or "center". If you don't pass any option, it defaults to "center".
This allow us to create one element with multiple states, making it easy to alternate between them.
You should always have a default state defined: "element:elName[state:default];" or "element:elName;"
When the prototype loads, protoSparker puts all states behind the default state with visible=false, so you start off seeing just the default one. E.g.: you could have a tabs component with two states, just name the layers accordingly:
default layer, name it "element:tabs;"
active state layer, name it "element:tabs[state:active];"
You can add a "toggle" property to toggle between two states. It's really useful for controls with on/off states. Both states must have this "toggle" option for it to work:
default state, name it "element:switch[toggle]"
on state, name it "element:switch[state:on,toggle]"
This allows you to switch an element's state. Using the last example, you could trigger a state change by creating a button layer:
set the button layer's name to "setElement:tabs[state:active];"