Introduction

The editor is the app where people can create their floor plans. The scope of the editor is limited to one floor plan project. Think of a project as a house for a family with the possibility of multiple floor levels, bigger than a room and smaller than an apartment building. You can see a demo of the on the Floorplanner website.

On this page I’ll do my best to explain how you can embed the editor into your own HTML page.

Table of contents

Floorplanner Partner account

Before you start, make sure you have a Floorplanner Partner account and an API key. You need an API key to be able to log in as a certain user so you can load and save his/her floor plan projects (using a token, but more on that later).

Setup HTML

To embed the editor into an HTML page, you first have to load a few other scripts which the editor uses ReactJS and PixiJS.

External JS libs

<script crossorigin="anonymous" src="//cdnjs.cloudflare.com/ajax/libs/react/0.14.7/react.min.js" type="text/javascript"></script>
<script crossorigin="anonymous" src="//cdnjs.cloudflare.com/ajax/libs/react/0.14.7/react-dom.min.js" type="text/javascript"></script>
<script crossorigin="anonymous" src="//cdnjs.cloudflare.com/ajax/libs/pixi.js/3.0.11/pixi.min.js" type="text/javascript"></script>

Editor JS

Then add the editor JS file to the page…

Btw. don’t mind the alpha in the URL. The editor is definitely not in alpha mode anymore, but it is still under active development. We deploy updates multiple times a day, so it currently makes sense to use one directory, and this is the one we chose in the beginning… Once the updates will slow down we will start releasing separate versions.

<script crossorigin="anonymous" src="//fpcdn.s3.amazonaws.com/apps/fp.editor/alpha/fp.editor.min.js" type="text/javascript"></script>

Editor CSS

… and the necessary CSS files.

<link href="//fpcdn.s3.amazonaws.com/apps/fp.editor/alpha/style/page.css" media="screen" rel="stylesheet" type="text/css" />
<link href="//fpcdn.s3.amazonaws.com/apps/fp.editor/alpha/style/style.css" media="screen" rel="stylesheet" type="text/css" />

Meta tags

To keep the editor from scaling on mobile devices you can set the viewport using a meta tag.

<meta content='initial-scale=1.0, maximum-scale=1.0, user-scalable=0' name='viewport' />

Initialize the editor

Finally, we can initialize the editor. It operates inside an HTML element, so make sure you have something like this in your page:

<div id='editor'></div>

To initialize the editor call the entryPoint(element, projectId, theme) function. The function returns the editor API object that you might need later on. Make sure the page has loaded before you init the editor. The element is an HTML element like described above, the projectId is the id of a Floorplanner project and we’ll the discuss the settings in more detail below.

<script type="text/javascript">
  var api;
  window.onload = function() {
    api = entryPoint(document.getElementById('editor'), projectId, settings);
  }
</script>

Settings

The settings object can be used to customize certain parts of the editor, see the sample below:

var settings = {
  useMetric: true, // toggles between metric and imperial measurement systems
  engineAutoDims: true, // generate and show automatic dimensions
  layout: "regular", // chose between "regular", "embed" or "canvas"
  panZoom: true // (default) you can disable pan and zoom by setting it to false
  user: {
    id: 18128921, // the Floorplanner user id
    email: 'support@floorplanner.com', // user email, necessary when exporting 2D or 3D images
    permissions: ['hd', 'pdf', 'change_email'], // 'hd' sets exports to HD resolution, 'change_email' allows user to change email
    auth_token: '3f55328b06762f88787765a3cc556837' // authentication token to log in as a certain user
  }
};

We have implemented three different kind of layouts: regular, embed and canvas. The regular one is - as you might expect - the default layout, the one you see on Floorplanner. In the embed layout the save, export and quit buttons and the feedback UI is hidden. If you want to use the editor without any UI at all, then use the canvas layout. This layout allows you to build you own UI on top of the canvas layer of the editor.

Auth token

An auth token has to be supplied to the settings var when initializing the editor. To get a token, use your API key to send a request to the Floorplanner API /users/:user-id/token.

Unmounting the editor

If you are embedding the editor in a single-page webapp, you need to make sure you unmount the editor before you initialize it again.

ReactDOM.unmountComponentAtNode(document.getElementById('editor'));

This will ensure that references to the editor are released and there will be just one instance after you intialize it again.

API methods

It possible to trigger certain actions inside the editor by calling methods on the editor API object. For example, this will trigger an undo action:

api.undo();

The basic methods that are available on the editor API object are:

Method Description
save() Saves the current floor plan.
export() Shows the export dialog with all the export options.

Advanced API methods

More advanced methods are:

Method Description
zoomIn(amount=0.1) Zooms in on the plan, +0.1 of initial zoom by default
zoomOut(amount=0.1) Zooms out on the plan, -0.1 of initial zoom by default
zoomAll() Zooms the plan to fit the screen
undo() Undo the previous action
redo() Redo the last action after undo
canUndo() Returns true if undo is available
canRedo() Returns true if redo is available
addWalls([walls]) Adds walls to the plan. Walls have to be defined in an array of 4-element array like [[x1, y1, x2, y2], ...] using screen coordinates.
collectionItems(collectionId) Returns the furniture items, materials and colours of a certain collection specified by the collectionId. These items are draggables which means that they can be dragged and dropped onto the plan.
doors() Returns a set of draggable doors.
windows() Returns a set of draggable windows.
icons() Returns a set of draggable icons.
signs() Returns a set of draggable signs.
startDrag(e, draggable) Starts dragging a draggable; a furniture item, door, window, material or a colour. e is the original mouse or touch event.
drop({x,y,obj:draggable}) Drops a draggable at a screen position {x,y}.
reset() Resets the plan to a blank slate.
dispose() Removes the selected item (see below).
updateSelected(data) Updates currently selected item (see the section below).
toGlobal({x,y}) Converts in-plan coordinates to global (DOM) coordinates. NB! These are not exactly screen coordinates. The origin is the left-top corner of the editor DOM element.
exportGltf(callback) Exports the 3D scene in GLTF. When the export is done, the callback is called with a single parameter - an ArrayBuffer with export data.

You can also subscribe to following events:

Property Description
onSave The function assigned to this property will be called whenever the plan was saved.
onSelected Will be called whenever something gets selected or deselected. The first and the only parameter contains information about what is selected or null if it was a de-select.
onUpdated Will be called whenever internal state of the floorplan is updated. The first update happens when the design is loaded, so this handler can also be used as ‘editor ready’ handler.
onZoomUpdated Will be called whenever zoom value changes. The only parameter of the callback is the new zoom level in %

How to assign an event handler:

api.onSelected = function(data) { console.log("selected", data); };

Note: all methods returning draggables are Promises, so you can do something like this:

api.doors().then(doors => /* do something with doors */ );

Adding a camera

Cameras are also droppables, so you can drop them to the plan, too. How to add a camera to a plan:

api.drop({x: 1000, y: 510, obj: {kind: 'camera', data:
   {z: 100, dx: 1, dy: 0, dz: 0, fov: 78, name: 'hall'}}});

Description of camera properties:

Property Description
x, y Screen position of the camera.
z Real height of the camera, in centimetres.
dx, dy, dz Values in range (-1,1) describing the direction of the camera
fov Field of view of the camera, in degrees.
name User-assigned name.

Internal state

We also expose the internal state of the floorplan. It’s available via the state property. Feel free to examine what this object contains in various situations. For instance, the following code will output the number of walls currently in the plan:

console.log(api.state.walls.length);

Update selected

Once an item is selected, you can update its attributes to change its size, rotation and so on. The list of attributes you can update depends on what is selected. To update, you call updateSelected like this:

api.updateSelected({width: 100, z_height: 250})

Here is an (incomplete) list of properties for openings, such as doors and windows. You can examine other properties of objects using onSelected callback (the obj property of the only callback parameter).

Property Description
width The width of the object, in cm
z_height The hight of the object, in cm. Note the prefix!
z The elevation of the object above the floor, also in cm