This self-guided tutorial builds up from a simple "Hello, World!" exercise to a dynamic web page that responds to user input. It uses eXist-db and teaches the basic interface elements of the eXide XQuery IDE for developing XQuery-based applications in eXist.
eXist is a free, open source native XML database. It's a great tool for learning how to query, analyze, and transform your data. Among the various interfaces for working with eXist, one of the most convenient is eXide, a browser-based IDE (integrated development environment) for writing XQuery modules and developing XQuery-based applications on your own computer without installing any additional software. eXide comes pre-installed with eXist and has a number of useful features. We'll just cover the basics here. And once you have something you'd like to turn into a web page, eXist has a built-in web server, so you can develop full-fledged web applications by learning just a few additional functions and techniques. This tutorial leads you through basic steps to turn your query into a dynamic web page, with forms that users can enter data into and with the Bootstrap CSS library to make your pages look pretty.
- Download and install eXist. This tutorial assumes the you are running the current release version, 3.6.0.
- Open eXide at http://localhost:8080/exist/apps/eXide
- Download this Gist as a .zip file by clicking on the
Download ZIPbutton at the top of the Gist); we'll use the files mid-way through the tutorial.
-
Copy and paste the following query into the editor pane.
xquery version "3.1"; <p>Hello, World!</p>
-
Submit the query to eXist by selecting the
Evalbutton in eXide's toolbar. -
See the results.
-
Repeat these steps for the following query, observing the change in the code.
xquery version "3.1"; let $addressee := "World" return <p>Hello, { $addressee }!</p>
Instead of running our queries in eXide, we can do so directly in the web browser. This turns our queries into a true web page. But to do so, we first need to save the query in the database so it has a URL that we can call from the browser.
-
For the next query, after pasting it into eXide, save the query to the database by selecting the
Savebutton.xquery version "3.1"; import module namespace request = "http://exist-db.org/xquery/request"; let $addressee := request:get-parameter("addressee", "World") return <p>Hello, { $addressee }!</p>
-
In the
Save Document Asdialog, drill into/db/apps, selectCreate Collection(the folder icon in the toolbar) to create amy-appcollection, and save your query into this collection as03-get-parameter.xq.
- Click on the
Run in new tabbutton (the arrow icon just beneath the editor pane) to run this query in a new browser tab. If you named your collection and module as instructed, the URL for the new browser tab will open to http://localhost:8080/exist/apps/my-app/03-get-parameter.xq. - Add
?addressee=Joeto the end of the URL and hit the return key to submit the query with this new parameter. Try your own values.
Instead of copying, pasting, and saving each query, we can upload these queries in batch. Knowing how to upload and set permissions on the stored queries will save time.
- On your desktop, open the .zip file containing this Gist's files (00 through 06).
- Back in eXide, open the DB Manager again via
File > Manage. - Drill into the
/db/apps/my-appcollection, selectUpload Files(the cloud icon in the toolbar), and either drag-and-drop the files onto the target or select the Upload Files button to navigate to the files. - Once the upload is complete, select the
Donebutton, select all of the files, select thePropertiesbutton (a circular "i" icon), and select all 3 "execute" checkboxes to make the queries executable. - Exit the DB Manager dialog.
Until now the queries have all returned raw XML to the browser. Let's tell the browser to treat the results as HTML.
- Use the
Directorytab to the left of the editor pane to drill down to/db/apps/my-app. Open query 4, and use theRun in new tabbutton to try the query in a new browser tab. - Again, add an
addresseeparameter to the end of the URL.
Open query 5 in the browser and try out the interactive form.
Run query 6 in the browser.
Congratulations! You've developed a simple XQuery into a dynamic, HTML form, and you've learned your way around the eXide IDE for developing XQuery applications with eXist. Here are some ideas for next steps:
- Add some more fields to your form.
- Add
value="{$addressee}"to your<input>elements to place the user-submitted fields back in the form after the user submits the form. - Refactor your code to move the HTML wrapping code into a function,
local:wrap-html, which takes a paramter,$contentand perhaps even a second parameter$title. - Upload your own XML data to eXist, and adapt your code to query the data.
Do you prefer to work in a code editor like Atom? Install the existdb package for Atom to add XQuery syntax highlighting, code completion and validation, and integration with eXist to Atom. Or, if you prefer to work with oXygen XML Editor, you can add eXist-db to oXygen as an External Data Source and XQuery Validation Engine.
Interested in learning more about XQuery? Check out Learning XQuery, a list of great articles, blog posts, and books for learning XQuery.
Interested in learning more about eXist? Check out eXist's documentation. The "Learning XQuery" page also links to the O'Reilly book about eXist.