diff --git a/source/includes/figures/quickstart-sinatra-list.png b/source/includes/figures/quickstart-sinatra-list.png new file mode 100644 index 00000000..8adc6c1c Binary files /dev/null and b/source/includes/figures/quickstart-sinatra-list.png differ diff --git a/source/quick-start-sinatra.txt b/source/quick-start-sinatra.txt index 11814e03..5b9e69c4 100644 --- a/source/quick-start-sinatra.txt +++ b/source/quick-start-sinatra.txt @@ -9,7 +9,7 @@ Quick Start (Sinatra) :values: tutorial .. meta:: - :keywords: php framework, odm + :keywords: ruby framework, odm .. contents:: On this page :local: @@ -58,7 +58,6 @@ that connects to a MongoDB deployment. /quick-start-sinatra/create-a-deployment/ /quick-start-sinatra/create-a-connection-string/ /quick-start-sinatra/configure-mongodb/ - -.. /quick-start-sinatra/view-data/ -.. /quick-start-sinatra/write-data/ -.. /quick-start-sinatra/next-steps/ + /quick-start-sinatra/view-data/ + /quick-start-sinatra/write-data/ + /quick-start-sinatra/next-steps/ diff --git a/source/quick-start-sinatra/next-steps.txt b/source/quick-start-sinatra/next-steps.txt new file mode 100644 index 00000000..d2c03d89 --- /dev/null +++ b/source/quick-start-sinatra/next-steps.txt @@ -0,0 +1,31 @@ +.. _mongoid-quick-start-sinatra-next-steps: + +========== +Next Steps +========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: learn more + +Congratulations on completing the Quick Start tutorial for Sinatra! + +After you complete these steps, you have a Sinatra web application that +uses {+odm+} to connect to your MongoDB deployment, run a query on +the sample data, and render retrieved results. + +.. TODO You can download the completed web application project by cloning the +.. `mongoid-quickstart <>`__ +.. GitHub repository. + +.. TODO Learn more about {+odm+} features from the following resources: + +.. - :ref:`mongoid-fundamentals-connection`: Learn how to configure your MongoDB +.. connection. +.. +.. - :ref:`mongoid-usage-examples`: See code examples of frequently used MongoDB +.. operations. + diff --git a/source/quick-start-sinatra/view-data.txt b/source/quick-start-sinatra/view-data.txt new file mode 100644 index 00000000..8498eb4f --- /dev/null +++ b/source/quick-start-sinatra/view-data.txt @@ -0,0 +1,150 @@ +.. _mongoid-quick-start-sinatra-view-data: + +================= +View MongoDB Data +================= + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +.. procedure:: + :style: connected + + .. step:: Create an application file + + At the root level of your project, create a file called ``app.rb``. + Paste the following contents into the ``app.rb`` file to + load the necessary gems and your configuration file: + + .. code-block:: ruby + + require 'sinatra' + require 'mongoid' + + Mongoid.load!(File.join(File.dirname(__FILE__), 'config', 'mongoid.yml')) + + .. step:: Create a data model + + In the ``app.rb`` file, create a model called ``Restaurant`` + to represent data from the sample ``restaurants`` collection in + the ``sample_restaurants`` database: + + .. code-block:: ruby + + class Restaurant + include Mongoid::Document + + field :name, type: String + field :cuisine, type: String + field :borough, type: String + + end + + .. step:: Generate a view + + Create a **view** to display your data in a specified way by using + HTML and {+language+}. + + At the root level of your project, create a directory + called ``views``. Then, create a file called + ``list_restaurants.erb``. Paste the following code into the + ``list_restaurants.erb`` file: + + .. code-block:: html + + + + + Restaurants List + + +

Restaurants List

+ + + + + + + <% @restaurants.each do |restaurant| %> + + + + + + <% end %> +
NameCuisineBorough
<%= restaurant.name %><%= restaurant.cuisine %><%= restaurant.borough %>
+ + + + .. step:: Add a web route + + In the ``app.rb`` file, add a ``get`` route called + ``list_restaurants``, as shown in the following code: + + .. code-block:: ruby + + get '/list_restaurants' do + @restaurants = Restaurant + .where(name: /earth/i) + + erb :list_restaurants + end + + This route retrieves restaurant documents in which the value of + the ``name`` field contains the string ``"earth"``. The route + uses the ``list_restaurants`` view to render the results. + + .. _mongoid-quick-start-sinatra-json: + + .. step:: (Optional) View your results as JSON documents + + Instead of generating a view to render your results, you can + use the ``to_json()`` method to display your results in JSON + format. + + Replace the ``list_restaurants`` route in the ``app.rb`` file with + the following code to return the results as JSON documents: + + .. code-block:: ruby + + get '/list_restaurants' do + restaurants = Restaurant + .where(name: /earth/i) + + restaurants.to_json + end + + .. step:: Start your Sinatra application + + Run the following command from the application root directory + to start your {+language+} web server: + + .. code-block:: bash + + bundle exec ruby app.rb + + After the server starts, it outputs the following message + indicating that the application is running on port ``4567``: + + .. code-block:: none + :copyable: false + + [2024-10-01 12:36:49] INFO WEBrick 1.8.2 + [2024-10-01 12:36:49] INFO ruby 3.2.5 (2024-07-26) [arm64-darwin23] + == Sinatra (v4.0.0) has taken the stage on 4567 for development with backup from WEBrick + [2024-10-01 12:36:49] INFO WEBrick::HTTPServer#start: pid=79176 port=4567 + + .. step:: View the restaurant data + + Open the URL http://localhost:4567/list_restaurants in your web browser. + The page shows a list of restaurants and details about each of + them: + + .. figure:: /includes/figures/quickstart-sinatra-list.png + :alt: The rendered list of restaurants + +.. include:: /includes/quick-start/troubleshoot.rst diff --git a/source/quick-start-sinatra/write-data.txt b/source/quick-start-sinatra/write-data.txt new file mode 100644 index 00000000..5eebb2af --- /dev/null +++ b/source/quick-start-sinatra/write-data.txt @@ -0,0 +1,46 @@ +.. _mongoid-quick-start-sinatra-write-data: + +===================== +Write Data to MongoDB +===================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +.. procedure:: + :style: connected + + .. step:: Add a web route to insert data + + In the ``app.rb`` file, add a ``post`` route called + ``add_restaurant``, as shown in the following code: + + .. code-block:: ruby + + post '/add_restaurant' do + Restaurant.create!(params[:restaurant]) + end + + .. step:: Post a request to create a restaurant entry + + Send a ``Restaurant`` instance to the ``add_restaurant`` endpoint + by running the following command from the application root + directory: + + .. code-block:: bash + + curl -d \ + 'restaurant[name]=Good+Earth+Cafe&restaurant[cuisine]=Cafe&restaurant[borough]=Queens' \ + http://localhost:4567/add_restaurant + + .. step:: View the data + + Refresh http://localhost:4567/list_restaurants in your web browser + to view the new restaurant entry that you submitted. The inserted + restaurant appears at the bottom of the list. + +.. include:: /includes/quick-start/troubleshoot.rst