This document is a draft and needs improvement!

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

Setup HTML

First off, lets start with the minimal HTML template required to render the editor. There are some placeholders present within square brackets, e.g. [USER_ID], these must be replaced with actual values. More on that in later sections.

    <!DOCTYPE html>
    <html>
        <head>
          <meta content="initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport" />
          <link rel="stylesheet" media="screen" href="https://d30xpbkpa0ndno.cloudfront.net/editor-releases/2.3.27/style/style.css" />
          <script src="https://cdnjs.cloudflare.com/ajax/libs/script.js/2.5.8/script.min.js"></script>
        </head>
        <body>
            <div id="fp-editor-container"></div>
            <script src="https://d30xpbkpa0ndno.cloudfront.net/editor-releases/2.3.27/loader.js" crossorigin="anonymous"></script>
            <script>
                $script.ready('editor', function() {
                    // set up minimal settings object
                    var settings = {
                        user: {
                            id: "[USER_ID]",
                            permissions: ['save'],
                            auth_token: '[AUTH_TOKEN]',
                        }
                    };

                    // the entryPoint function returns a Promise, which is resolved with the 'editor API' object
                    entryPoint(document.querySelector('#fp-editor-container'), [PROJECT_ID], settings)
                    .then(function(api) {window.fpEditor = api});
                });
            </script>
        </body>
    </html>

Setup CSS

The editor nests itself inside a target HTML node. In the HTML example above, this is done using a <div> with id="fp-editor-container". The editor will take up 100% width and 100% height of the target div (#fp-editor-container). The following CSS will initialize the editor at 1024px wide by 880px high:

#fp-editor-container {
    width: 1024px;
    height: 880px;
}

The height must be set explicitly, using min-height is not sufficient since a height: 100% within such element is not respected. The dimensions used in above examples are the recommended minimum width and height attributes, you can go below this but in some cases, the editor needs at least this minimum amount of space.

Placeholders

Within the HTML, the placeholders [USER_ID], [AUTH_TOKEN] and [PROJECT_ID] must be replaced with real values. Below this section, you can find out how to retrieve each individual component.

Replacing auth_token and id

User ID and Authentication tokens can be retrieved by making an API request with your API key (scroll to bottom to see it). The following is an example cURL request. Do not forget to replace [YOUR_API_KEY] with your actual API key:

curl --user [YOUR_API_KEY]:x https://floorplanner.com/api/v2/users/token.json

This will return json in the following format:

{
   "token" : "eyJ0eXAiOiJKV1QiLQL1bGciOiJIUzI1NiJ9.eyJhY3Rpb24abaJsb2dpbiIsIm1vZGVsIjoiVXNlciIsImlkIjoxMDMsImlhdCI6MTUyMTczMTIwMH0.juutj2LGAVDUAV103Cz_viPvIfcPcs6weIPl3eFtsdM",
   "user_id" : 1337
}

Within the HTML template, replace [AUTH_TOKEN] with the value of the token key inside the result JSON. Also replace [USER_ID] with the value of user_id inside the result JSON.

Replacing project_id

See the following API call to fetch all the projects you can access, their ID will be part of the JSON output: Projects#index. Replace the [PROJECT_ID] in the HTML template with any of these ID’s.

Meta tags

To keep the editor from scaling on mobile devices the following meta tag can be used:

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

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,

    // A template offers a way to add consistent branding to floorplans and interior renders.
    // It's a collection of style and export settings which can be modified in the website.
    templateId: 160,

    // You can even change the colour theme of the editor, suppying your own colours
    // (using CSS syntax)
    colors: {light: 'rgb(62,136,158)', dark: '#444'},

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

        // 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: 'eyJ0eXAiOiJKV1QiLQL1bGciOiJIUzI1NiJ9.eyJhY3Rpb24abaJsb2dpbiIsIm1vZGVsIjoiVXNlciIsImlkIjoxMDMsImlhdCI6MTUyMTczMTIwMH0.juutj2LGAVDUAV103Cz_viPvIfcPcs6weIPl3eFtsdM'
    }
};

Unmounting the editor with React

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('fp-editor-container'));

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 a save action:

fpEditor.save();

Methods and properties available on the editor API object are:

Method/Property Description
save() Saves the current floor plan.
isDirty Returns true if there are unsaved changes.
state Returns the state of the Floorplan object (walls, items, areas..) displayed in the editor.
zoomIn() Zooms in.
zoomOut() Zooms out.
zoomAll() Zooms to fit the view.
view Write-only. Should be either ‘2D’ or ‘3D’. Switches to the corresponding view.
designId Write-only. Given an id of the design of current project, loads that design into the view.
project Read-only. Data about project, including floors and designs. Meant to be used to list project’s floors and designs and to switch betwen them (setting the /designId/ property).

You can also subscribe to following events:

Property Description
onSave The function assigned to this property will be called whenever the plan was saved.
onUpdated Will be called whenever internal state of the floorplan is updated. NB! The first update happens when the design is loaded
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
onExport Will be called whenever an export was requested. The assigned function will get a single input parameter, either “interior” or “floorplan”, indicating the type of the export

How to assign an event handler:

fpEditor.onUpdated = function(data) { console.log("floorplan updated", data); };