Frontend Editing

Frontend Editing is a huge focus of the Gentics CMS JavaScript API. We tried to make it as easy as possible to have your editors editing contents from the frontend – so this is you guide to get you started.

1 Prerequisites & setting up your page

Some things need to be in place before you may start hacking away:

  • You need a Gentics CMS backend up and running with some data ready for editing
  • There should be a user who can access the pages you want to edit
  • You need to be able to connect to Gentics CMS from your page.

1.1 Proxy

If the page that includes the Gentics CMS JavaScript API is on a different host than the Gentics CMS backend, you need a proxy script to avoid problems with cross origin AJAX requests.

The proxy script must be located on the same host as the page that includes the Gentics CMS JavaScript API. In the examples below, “[Proxy]” is a placeholder for the the path to the proxy script and must be replaced for the examples to work.

An example implementation is provided.

A proxy servlet implementation is provided with Gentics Portal.Node. Please see the documentation for the GCNProxyServlet for further information.

2 Basic page

We will start out with a very basic page, which has no funky layout yet, but already includes Aloha Editor, some plugins and stylesheets along with the Gentics CMS JavaScript API.

There is no script element that includes the Gentics CMS JS API as it will be loaded automatically by the Aloha Editor gcn-plugin. Don’t include the Gentics CMS JS API on a page where the gcn-plugin is loaded, since that would load the Gentics CMS JS API twice and may result in errors.


<head>
	<meta http-equiv="content-type"
          content="text/html; charset=UTF-8">
	<title>
      Frontend Editing with Gentics CMS JavaScript API & Aloha Editor
    </title>

	<!-- Loads the Aloha Editor styles --> 
	<link rel="stylesheet"
      href="/[Proxy]/CNPortletapp/latest/alohaeditor/css/aloha.css"
      id="aloha-style-include"
      type="text/css">
    
    <!-- Configures the gcn-plugin-->
    <script>
    var alohaEditorContextPath = '/[Proxy]';
    var Aloha = {};

	Aloha.settings = {
		"plugins": {
			"gcn": {
				"webappPrefix": alohaEditorContextPath + "/CNPortletapp/",
				"buildRootTimestamp": "latest",
				"stag_prefix": alohaEditorContextPath + "/.Node/"
			}
		}
	};
    </script>

	<!-- Loads Aloha Editor itself including some plugins -->
	<script type="text/javascript"
      src="/[Proxy]/CNPortletapp/latest/alohaeditor/lib/aloha.js"
      data-aloha-plugins="common/ui,
						  common/block,
						  extra/ribbon,
						  common/format,
						  common/highlighteditables,
						  common/list,
						  common/link,
						  common/table,
						  common/paste,
						  common/contenthandler,
						  common/commands,
						  gcn/gcn-linkbrowser,
						  gcn/gcn"></script>

	<script type="text/javascript">
	Aloha.ready(function () {
        // Replace [Proxy] with the location of the proxy script
        GCN.settings.BACKEND_PATH = alohaEditorContextPath + "/CNPortletapp";

		// use Aloha Editor's internal jQuery & expose it 
		window.$ = window.jQuery = window.Aloha.jQuery;

        // and this is where your code goes
	});
	</script>
</head>
<body>
	<h1 id="title">Basic Page</h1>
	<div id="content">Basic Page Content :)</div>
</body>

3 Implementing frontend editing

3.1 Authenticate with the backend

The first thing we want to do is to authenticate with the backend:


// authenticate with the backend
GCN.login('[username]', '[password]', function (success, data) {
	if (success) {
		// authentication successful
		alert('Hello, ' + data.user.firstName);
	} else {
		// error :(
		alert('Error during login.');
		return;
	}
});

Give this code a spin to see if authentication works for you.

In a production version of this code you want to use SSO or directly set a session id for the library, but to keep things simple we are using basic authentication with username and password for this example.

3.2 Fetch a page & start editing!

The next step is about fetching the page from the server and starting to edit contents.


// authenticate with the backend
GCN.login('[username]', '[password]', function (success, data) {
	if (success) {
		// load page with id 1 which is part of the demo package
		GCN.page(1, function (page) {
			// inside the page there is a tag namend "content"
			// which will contain all contents
			// using the .edit() method we will put those
			// contents into our <div id="content"> and
			// start editing with aloha right away! 
			page.tag('content').edit('#content');
		});
	} else {
		// error :(
		alert('Error during login.');
		return;
	}
});

Paste this code into your page and witness the glory of frontend editing!

3.3 Saving your changes

Frontend editing is fine but you also need to be able to save your changes. For this purpose we need to add a save button.


// authenticate with the backend
GCN.login('[username]', '[password]', function (success, data) {
	if (success) {
		// load page with id 1 which is part of the demo package
		GCN.page(1, function (page) {
			// inside the page there is a tag namend "content"
			// which will contain all contents
			// using the .edit() method we will put those
			// contents into our <div id="content"> and
			// start editing with aloha right away! 
			page.tag('content').edit('#content');

			// add a save button
			$('body')
				.append('<button id="save">save</button>')
				.find('#save')
				.click(function () {
					// save the page
					page.save();
				});
		});
	} else {
		// error :(
		alert('Error during login.');
		return;
	}
});

4 Complete example

Here’s the full example in case things got tedious on the way :)

Remember this is just a basic implementation of frontend editing to get you started on the topic. For your production environment you want to add error handling and SSO.


<head>
	<meta http-equiv="content-type"
          content="text/html; charset=UTF-8">
	<title>
      Frontend Editing with Gentics CMS JavaScript API & Aloha Editor
    </title>

	<!-- Loads the Aloha Editor styles --> 
	<link rel="stylesheet"
      href="/[Proxy]/CNPortletapp/latest/alohaeditor/css/aloha.css"
      id="aloha-style-include"
      type="text/css">
    
    <!-- Configures the gcn-plugin-->
    <script>
    var alohaEditorContextPath = '/proxy-php';
    var Aloha = {};

	Aloha.settings = {
		"plugins": {
			"gcn": {
				"links": "backend",
				"webappPrefix": alohaEditorContextPath + "/CNPortletapp/",
				"buildRootTimestamp": "latest",
				"stag_prefix": alohaEditorContextPath + "/.Node/"
			}
		}
	};
    </script>

	<!-- Loads Aloha Editor itself including some plugins -->
	<script type="text/javascript"
      src="/[Proxy]/CNPortletapp/latest/alohaeditor/lib/aloha.js"
      data-aloha-plugins="common/ui,
						  common/block,
						  extra/ribbon,
						  common/format,
						  common/highlighteditables,
						  common/list,
						  common/link,
						  common/table,
						  common/paste,
						  common/contenthandler,
						  common/commands,
						  gcn/gcn-linkbrowser,
						  gcn/gcn"></script>

	<script type="text/javascript">
	Aloha.ready(function () {
        // Replace [Proxy] with the location of the proxy script
        GCN.settings.BACKEND_PATH = alohaEditorContextPath + "/CNPortletapp";

		// use Aloha Editor's internal jQuery & expose it 
		window.$ = window.jQuery = window.Aloha.jQuery;

		// authenticate with the backend
		GCN.login('[username]', '[password]', function (success, data) {
			if (success) {
				// load page with id 1 which is part of the demo package
				GCN.page(1, function (page) {
					// inside the page there is a tag namend "content"
					// which will contain all contents
					// using the .edit() method we will put those
					// contents into our <div id="content"> and
					// start editing with aloha right away! 
					page.tag('content').edit('#content');
					
					// add a save button
					$('body')
						.append('<button id="save">save</button>')
						.find('#save')
						.click(function () {
							// save the page
							page.save();
						});
				});
			} else {
				// error :(
				alert('Error during login.');
				return;
			}
		});
	});
	</script>
</head>
<body>
	<h1 id="title">Basic Page</h1>
	<div id="content">Basic Page Content :)</div>
</body>