launchpad-reviewers team mailing list archive
-
launchpad-reviewers team
-
Mailing list archive
-
Message #30279
[Merge] ~lgp171188/launchpad:tutorial-creating-a-new-page-in-launchpad into launchpad:master
Guruprasad has proposed merging ~lgp171188/launchpad:tutorial-creating-a-new-page-in-launchpad into launchpad:master.
Commit message:
Add a tutorial for creating a new page in Launchpad
Requested reviews:
Launchpad code reviewers (launchpad-reviewers)
For more details, see:
https://code.launchpad.net/~lgp171188/launchpad/+git/launchpad/+merge/447281
--
Your team Launchpad code reviewers is requested to review the proposed merge of ~lgp171188/launchpad:tutorial-creating-a-new-page-in-launchpad into launchpad:master.
diff --git a/doc/index.rst b/doc/index.rst
index bab273e..2a44820 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -23,6 +23,8 @@ Contents
.. list-table::
+ * - :doc:`tutorials/index`
+ - A hands-on introduction to Launchpad for new developers
* - :doc:`how-to/index`
- Step-by-step guides covering key operations and common tasks
* - :doc:`explanation/index`
@@ -68,6 +70,7 @@ Thinking about using Launchpad for your next project? `Get in touch!
:hidden:
Home <self>
+ tutorials/index
how-to/index
explanation/index
reference/index
diff --git a/doc/tutorials/creating-a-page-in-launchpad.rst b/doc/tutorials/creating-a-page-in-launchpad.rst
new file mode 100644
index 0000000..81e7853
--- /dev/null
+++ b/doc/tutorials/creating-a-page-in-launchpad.rst
@@ -0,0 +1,120 @@
+================================
+Creating a new page in Launchpad
+================================
+
+In this tutorial, we will be creating a new page in Launchpad that shows the
+answers submitted by a user.
+
+Pre-requisites
+==============
+
+You have the :doc:`Launchpad development environment set up <../how-to/running>`.
+
+Introduction
+============
+
+A page in Launchpad requires a view class, an interface it is related to,
+and a page template to render the HTML. Let us learn how to do this in
+the following sections.
+
+Identifying the interface
+=========================
+
+Since the page should show the answers submitted by a user, the context is the
+user. In Launchpad, a user is represented by the ``IPerson`` interface, which
+is defined in ``lib/lp/registry/interfaces/person.py``.
+
+
+Creating a view class
+=====================
+
+The view classes are implemented in the ``browser/`` sub-directory of a package
+in Launchpad. Since this view is providing functionality related to the Answers
+application in Launchpad, we will be adding this view class in that package.
+
+Open ``lib/lp/answers/browser/person.py`` and add the following view class at
+the end of the file.
+
+.. code-block:: python
+
+ class PersonAnswersSetView(LaunchpadView):
+ """View used to show all the answers submitted by a IPerson."""
+
+ @property
+ def label(self):
+ return "Answers submitted by {}".format(self.context.displayname)
+
+ page_title = label
+
+This view inherits from the ``LaunchpadView`` class that provides a lot of
+the functionality needed by a Launchpad page. Here, we have created a property
+named ``label`` and assigned its value to the ``page_title`` attribute of the
+class.
+
+Creating the page template
+==========================
+
+We need a page template to render the data provided by the view class as HTML.
+So create a file named ``person-answers.pt`` in the ``lib/lp/answers/template``
+directory and add the following contents.
+
+.. code-block:: html
+
+ <html
+ xmlns="http://www.w3.org/1999/xhtml";
+ xmlns:tal="http://xml.zope.org/namespaces/tal";
+ xmlns:metal="http://xml.zope.org/namespaces/metal";
+ xmlns:i18n="http://xml.zope.org/namespaces/i18n";
+ xml:lang="en"
+ lang="en"
+ dir="ltr"
+ metal:use-macro="view/macro:page/main_only"
+ i18n:domain="launchpad"
+ >
+ </html>
+
+Connecting the view, the interface, and the template
+====================================================
+
+Now we have to configure Launchpad to serve this page. To do so, add the
+following ZCML directive to ``lib/lp/answers/browser/configure.zcml``, just
+below the ``<lp:renamed-page>`` directive for the ``IPerson`` interface and
+the ``+tickets`` name.
+
+.. code-block:: xml
+
+ <browser:page
+ for="lp.registry.interfaces.person.IPerson"
+ class="lp.answers.browser.person.PersonAnswersSetView"
+ name="+answers"
+ permission="zope.Public"
+ template="../templates/person-answers-set.pt"
+ />
+
+This specifies that there is a new browser page for the `IPerson` interface,
+using the ``PersonAnswersSetView`` view class and the ``person-answers-set.pt``
+page template. The permission, ``zope.Public``, allows the page to be viewed
+by everyone. The value of the ``name`` attribute, ``+answers``, specifies
+the path at which this page can be accessed, relative to the URL of the
+``IPerson`` interface. So if the URL for an ``IPerson`` page is ``/~username``,
+this page should be available at ``/~username/+answers``.
+
+Viewing the page in the browser
+===============================
+Navigate to the top-level directory of the Launchpad repository inside the
+Launchpad LXC container. Run ``make run`` to start the development server and wait
+for it to finish loading.
+
+Open the browser and navigate to `<https://launchpad.test/~name16/+answers>`_.
+Once the page loads, you can see that it is a typical Launchpad site page and
+that the ``Answers`` tab is active. You can also see a heading
+``Answers submitted by Foo Bar`` heading below the tab bar.
+
+TODO: Add a screenshot with the expected result.
+
+Displaying the comments submitted by the user in the page
+=========================================================
+
+TBD - can either be added in this tutorial or we could make this a multi-part
+tutorial where the first part ends here and the rest is covered in the next
+part(s).
diff --git a/doc/tutorials/index.rst b/doc/tutorials/index.rst
new file mode 100644
index 0000000..c1b8e48
--- /dev/null
+++ b/doc/tutorials/index.rst
@@ -0,0 +1,12 @@
+:hide-toc:
+
+Tutorials
+=========
+
+Common development tasks
+------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ creating-a-page-in-launchpad
Follow ups
