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 = {
  // Set the domain used for requests from the editor.
  // You can remove this setting when using the production environment.
  apiDomain: 'sandbox.floorplanner.com',

  // Toggles between metric and imperial measurement systems [true, false]
  useMetric: true,

  // Generate and show automatic dimension lines [true, false]
  engineAutoDims: true,

  // Enable or disable pan and zoom by setting [true, false]
  panZoom: true,

  // Show or hide the welcome splash + quite tour (only first item) [true, false]
  showTour: true,
  
  // Show or hide the quit button
  showQuit: true,
  
  // Show or hide the blue feedback corner
  showFeedback: true,

  // Show or hide Symbols & Icons section in Organize tab [true, false]
  useSymbols: true,
  
  // Which floor to show after project is loaded (NB! It's zero-based index and not a floor id)
  floorIndex: 0,
  
  // Whether to swap legacy FP assets from the old editor with their HQ counterparts
  mapLegacy: true,

  // User info
  user: {
    // The Floorplanner user id
    id: 18128921,

    // User email, necessary when exporting 2D or 3D images
    email: 'support@floorplanner.com',

    // A collection of permissions
    //    'hd' sets the exports to HD resolution
    //    'pdf' allows for PDF export
    //    'change_email' allows user to change email address
    //    'save' and 'export' are for corresponding buttons in the top bar
    permissions: ['hd', 'pdf', 'change_email', 'save', 'export'],

    // Authentication token to log in as a certain user
    auth_token: '3f55328b06762f88787765a3cc556837'
  },

  // The project_template setting allows you to define the list of collections,
  // to show or hide the 'featured' section or to define a list of custom room
  // type sets.
  project_template: {
    // The collections are shown in the 'Decorate > All furniture' tab. Supply a
    // list of collection ids to change the content of the tab or set an empty
    // array to use the default list.
    collections: [],

    // The 'featured' section is located at the 'Decorate > Browse unique collections'
    // tab. Setting collection_set to null removes the 'featured' section.
    collection_set: 'floorplanner',

    // Room type sets are located in the 'Build > Set room type' tab. Supply a
    // list of room type set ids to change the content of the tab.
    room_type_sets: [],

    wallTopColor3D: 'F7F7F7', // a hex string (without leading '#'!) for wall top color in 3D
    wallTopColor2D: '000000' // same for wall top color in 2D
  }
};

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
isDirty Returns true if there are unsaved changes
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 %
onQuit Will be called whenever the editor is going to quit. NB! This handler replaces the default one, which sets window.location to ‘/dashboard’. So if your goal is to navigate the user to some other page, you have to do it in the body of the handler

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