At its simplest, an Acre application is:
This tutorial will walk you through the process of creating a very simple application that only uses these two files to return a list of all the albums by an artist in Freebase. Some knowledge of HTML and JavaScript will help you understand how the code in this application works, but you can also cut-and-paste this code into your own applications, make minor changes, and create your own applications without much additional knowledge or effort.
There are three aspects of the Acre language that are used in this tutorial:
API Commands - Acre API commands like acre.mqlread and acre.require let Acre make requests to the Freebase API and Acre server, like requesting information from the Freebase database or a file from a library on the server.
Template scripting - Acre templating commands are used within the body of an HTML file to execute operations when the pages loads or when a user interacts with the page content. In this way Acre scripting is the same as JavaScript, in that it can be used to perform logical operations and manipulate the appearance of page elements within the browser.
Text Substitution - text substitution lets Acre take the results of any of the operations above and insert them into a text string. For example, after getting the results of an acre.mqlread, you might want to insert the number of results into a sentence like "There are __ results in the Freebase database." This is accomplished through the use of a $.
An important feature of App Editor is the ability to clone files or applications created by you or someone else. This lets you easily re-use or adapt code from other applications.
All the code that you will enter in the following steps will go between the<html> <body> </body> </html>
<body></body> tags.
Enter any text you want to display on your page and add HTML markup to format it. For example:
<h1>Album Lister</h1> <p>This Acre application makes a query to the Freebase database to find all the albums in the database by a specific musical artist.</p>
We recommend that you write all your code as valid XHTML, so all tags should be closed and in lower-case. We also recommend that, after each stage of your applicaiton development, you use the Open Preview link to view the changes you've made.
The Metaweb Query Language (MQL) is the mechanism for retrieving information from the Freebase database. The Metaweb Query Language Reference Guide provides complete information about Freebase architecture and how to create simple and complex queries, while the Query Editor tool provides an environment to test them.
MQL queries, stored in Queries files, are an essential component of Acre applications, since the basic functionality of any Acre application is to retrieve information from Freebase through a MQL query and then present the results in a template. For this sample application the MQL query is very simple. If you open the police-albums file you'll see the following code:
{
"type":"/music/artist",
"name":"The Police",
"album":[]
}
This query is asking for a list of items (indicated by the []) associated with the album property that is part of the musical artist type, and, specifically, from the musical artist known as The Police. You could change this query to ask for any albums from any other musical artist in Freebase simply by changing the name value.
<acre:script>
var query = acre.require("police-albums").query;
var result = acre.freebase.MqlRead(query).result;
</acre:script>
Here you can see the JavaScript-like aspects of Acre. Like JavaScript, Acre scripting commands can be embedded in the HTML file by placing them within <acre:script> tags, and the scripting will be executed when the page loads. In this case, two variables, query and result, are being set, and their values are globally available for use in the rest of the file.
For query, the acre.require API method is used to retrieve the query file and use its contents to set the value of query, while result uses that value to perform a read of the Freebase database through the acre.freebase.MqlRead API method. If you created a new query file in Step 3, you would substitute its name for "police-albums" to use that query in your application.
Copy and paste this code into your template:
The Police have ${result.album.length} albums in Freebase
Here you can see the object-oriented aspect of JavaScript, and Acre, in action.
Queries to Freebase, and the results, are in the JavaScript Object Notation (JSON) data format. A JavaScript Object is simply a name:value pair, or collection of name: value pairs, where each name is a property of the object, and the value is the value of that property. If you look back at the query you created in Step 3, we used JSON to define the object we were interested in by using the type and name properties, and then said we wanted to know what values were associated with the album property.
When our query returns results, it returns name:value pairs that become the properties of our result object. You can see how this works by using the Query Editor.
The query results show the property name (albums) and its values. We can now use a JavaScript function like .length to find out more about the property album in the object result. Having performend this operation, we can insert the results into the text using $ substitution. Note that in the example above, we enclosed the results in {}. This is because we want the browser to process a complex JavaScript expression before performing the substitution. If we had a simple JavaScript value to substitute, we could use only the $, as you'll see in the next step.
A very simple description of JSON, with examples that should look familiar, is here: http://www.hunlock.com/blogs/Mastering_JSON_(_JavaScript_Object_Notation_)
Copy and paste the code below into your template:
<ul> <li acre:for="album in result.album">$album</li> </ul>
Many of the Acre templating commands can be directly appended to an HTML tag like an HTML attribute (and are appropriately called attributes in the Acre documentation). In this case, appending acre:for to the <li> tag means that for every album value in the album property of the result object, list the name of that album in place of $album.
${acre.require("/freebase/apps/attribution/templates").blanket()}