[CONF] Apache Sling Website: Discover Sling in 15 minutes (page edited)

confluence Fri, 28 Nov 2008 04:50:05 -0800

Page Edited : SLINGxSITE : Discover Sling in 15 minutes

Discover Sling in 15 minutes has been edited by Bertrand Delacretaz (Nov 28, 2008).

Change summary:

point to more samples

(View changes)

Content:

The Sling Launchpad

Page Status

Reviewed 2008-04-11, this page's information is in sync with the current Sling codebase.

The Sling Launchpad is a ready-to-run Sling configuration, providing an embedded JCR content repository and web server, a selection of Sling components, and documentation and examples. The Launchpad makes it easy to get started with Sling and to develop script-based applications.

This page will help you in getting started with the Launchpad. Fifteen minutes should be enough to get an overview of what Sling does.

While simple to run and understand, the Launchpad is a full-featured instance of Sling, an example configuration that we have created with the most common modules and configurations. The full functionality of Sling is available by loading additional Sling (or custom) OSGi modules as needed, using the Launchpad's web-based OSGi management console.

Launchpad Status

The Launchpad is not released as I write this (January 29th, 2008), so you'll have to get the code from our Subversion code repository, and build it yourself with Maven.

Also, the Launchpad does not yet include any built-in examples, so some assembly is required...things will get better - stay tuned!

Prerequisites

A Subversion client to get the Sling code.
A Java 5 JDK.
Maven is used to build Sling, we currently recommend V 2.0.7 (and see our MavenTipsAndTricks).
cURL to create content in the JCR repository.

A WebDAV client makes editing server-side scripts much more convenient, but to make our examples easy to reproduce, we're using cURL below to create and update files in the JCR repository, via the Sling WebDAV server.

Get the Launchpad

Checkout the code from our Subversion repository:

svn co http://svn.apache.org/repos/asf/incubator/sling/trunk sling

This creates a directory named sling under the current directory, with the completed Sling source code.

Client-less SVN

In a pinch, the code can also be copied using HTTP from the above URL, without installing a Subversion client.

Build the Launchpad

In the top-level sling directory that was created by the svn command, run:

mvn clean install

This builds and tests all the Sling modules that are required to run the Launchpad.

Maven should say BUILD SUCCESSFUL once the build is complete. Note that extensive automated tests of the Launchpad run during this build, so if this works Sling should run without problems on your system.

Maven tips and tricks

See MavenTipsAndTricks if you're having trouble building Sling.

Okay, this might send our 15 minutes deadline right out of the window...things will get better once we have a ready-to-run release.

Start the Launchpad

Change to the launchpad/webapp directory under the top-level sling directory, and run

mvn jetty:run

To start the launchpad.

By default, Jetty is configured to run on port 8888. If for some reason your setup is different you'll need to adjust the port number in the examples below.

Once started, look at http://localhost:8888/system/console with your browser. Use admin with password admin if Sling asks you for a login. Sling then displays the Sling Management Console page.

We don't need the Sling management console right now, but it tells us that Sling is started.

If you look at the http://localhost:8888/system/console/list page, all bundles should be marked Active. They're OSGi bundles powered by Apache Felix, but that doesn't really matter to us right now.

Log files

If things go wrong, have a look at the target/sling/logs/error.log log file under launchpad/webapp - that's where Sling writes any error messages.

Create some content

Until we have ready-to-test forms, you can create content with cURL, or you can create an HTML form that posts to the specified URL.

To create a content node (nodes are a JCR concept, a unit of storage) with cURL, use:

curl -F"sling:resourceType=foo/bar" -F"title=some title" http://admin:[EMAIL PROTECTED]:8888/content/mynode

The resulting node can be seen at http://localhost:8888/content/mynode, with default renderings in various formats at http://localhost:8888/content/mynode.html and http://localhost:8888/content/mynode.json.

Render your content using server-side _javascript_ (ESP)

Sling uses scripts or servlets to render and process content.

Several scripting languages are available as additional Sling modules (packaged as OSGi bundles that can be installed via the Sling management console), but the launchpad currently only includes the ESP (server-side ECMAscript) and JSP (Java Server Pages) languages modules by default.

To select a script, Sling uses the node's sling:resourceType property, if it is set.

That's the case in our example, so the following script will be used by Sling to render the node in HTML, if the script is found at /apps/foo/bar/html.esp in the repository.

html.esp

<html>
  <body>
    <h1><%= currentNode.title %></h1>
  </body>
</html>

To select the script, Sling looks under /apps, appends the sling:resourceType value of our node, which is foo/bar, and appends html.esp as the extension if our URL is html and the language of our script is esp.

Store this script under apps/foo/bar/html.esp, either using a WebDAV client (connected to http://admin:[EMAIL PROTECTED]:8888/), or using cURL as shown here, after creating the html.esp script in the current directory on your system:

curl -X MKCOL http://admin:[EMAIL PROTECTED]:8888/apps
curl -X MKCOL http://admin:[EMAIL PROTECTED]:8888/apps/foo
curl -X MKCOL http://admin:[EMAIL PROTECTED]:8888/apps/foo/bar
curl -X PUT -d @html.esp http://admin:[EMAIL PROTECTED]:8888/apps/foo/bar/html.esp

The HTML rendering of your node, at http://localhost:8888/content/mynode.html, is now created by this ESP script. You should see the node's title alone as an <h1> element in that page.

A script named POST.esp instead of html.esp would be called for a POST request, DELETE.esp for DELETE, xml.esp for a GET request with a .xml extension, etc.

Servlets can also be easily "wired" to handle specific resource types, extensions, etc., by simply loading a servlet with some additional metadata about the servlet, as an OSGi bundle.

What next?

These simple examples show how Sling uses scripts to work with JCR data, based on sling:resourceType or node types.

There's much more to Sling of course - you'll find some additional simple examples below.

We are working on debugging features to help trace the way Sling processes requests. This is not finished yet, but you can have a look at SLING-3 to see what's possible already.

TODO: add references to the next docs to study.

Additional examples

Let Sling generate the path of a newly created node.

To create a node with a unique path at a given location, end the URL of the POST request with /*.

In this case, the Sling response redirects to the URL of the created node.

Start by creating a new /blog folder:

curl -X POST "http://admin:[EMAIL PROTECTED]:8888/content/blog"

And create a node with a Sling-generated name under it:

curl -D - -F"title=Adventures with Sling" "http://admin:[EMAIL PROTECTED]:8888/content/blog/*"

Using cURL's -D option shows the full HTTP response, which includes a Location header to indicate where the new node was created:

Location: http://localhost:8888/content/blog/adventures_with_slin_0

The actual node name might not be adventures_with_slin_0 - depending on existing content in your repository, Sling will find a unique name for this new node, based on several well-know property values like title, description, etc. which are used for this if provided.

So, in our case, our new node can be displayed in HTML via the http://localhost:8888/content/blog/adventures_with_slin_0.html URL.

Note that we didn't set a sling:resourceType property on our node, so if you want to render that node with a script, you'll have to store the script under /apps/nt/unstructured/html.esp.

Add a page header with sling.include

The sling.include function can be called from scripts to include the rendered result of another node.

In this example, we create a node at /content/header, rendered with a logo using an html.esp script, and use that header at the top of the html.esp script that we previously created for the foo/bar resource type.

Start by checking that http://localhost:8888/content/mynode.html is rendered using the html.esp script created above.

Create this script and name it header.esp:

header.esp

<div>
  <p style="color:blue;">
    <img src="" class="code-quote">"/images/sling.jpg" align="right"/>
    <%= currentNode.headline %>
  </p>
</div>

Upload it so that it is used to render resources having sling:resourceType=foo/header:

curl -X MKCOL  http://admin:[EMAIL PROTECTED]:8888/apps/foo/header/
curl -X PUT -d @header.esp  http://admin:[EMAIL PROTECTED]:8888/apps/foo/header/html.esp

Create the header node:

curl -F"sling:resourceType=foo/header" -F"headline=Hello, Sling world" http://admin:[EMAIL PROTECTED]:8888/content/header

Upload the logo that the script uses (using some sling.jpg or other logo in the current directory):

curl -X MKCOL  http://admin:[EMAIL PROTECTED]:8888/images/
curl -T sling.jpg  http://admin:[EMAIL PROTECTED]:8888/images/sling.jpg

And check that the header is rendered with the logo at http://localhost:8888/content/header.html.

Now, update the html.esp script that we created for our first example above, to include the header: