Permalink
Browse files

docs(tutorials): updated Hello world

I made the Hello world tutorial clearer and included how to create
the manifest file, which was missing completely but is required by
newer (1.9+ apparently) versions of Elgg.

Fixes #9875
  • Loading branch information...
lehkonev committed Jun 10, 2016
1 parent d56369d commit dc5a4ade129f2ef2c7c8defae23e5498946078bf
Showing with 49 additions and 13 deletions.
  1. +49 −13 docs/tutorials/hello_world.rst
@@ -1,16 +1,45 @@
Hello world
###########
This tutorial shows you how to add a new page and print the text "Hello world" on it.
This tutorial shows you how to create a new plugin that consists of a new page with the text "Hello world" on it.
Before anything else, you need to :doc:`install Elgg</intro/install>`.
In this tutorial we will pretend your site's URL is ``https://elgg.example.com``.
First, you need to:
First, create a directory that will contain the plugin's files. It should be located under the ``mod/`` directory which is located in your Elgg installation directory. So in this case, create ``mod/hello/``.
Manifest file
=============
Elgg requires that your plugin has a manifest file that contains information about the plugin. Therefore, in the directory you just created, create a file called ``manifest.xml`` and copy this code into it:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
<name>Hello world</name>
<id>hello</id>
<author>Your Name Here</author>
<version>0.1</version>
<description>Hello world, testing.</description>
<requires>
<type>elgg_release</type>
<version>2.0</version>
</requires>
</plugin_manifest>
* :doc:`Install Elgg</intro/install>`
* Create a file called ``start.php`` at the root of your app.
This is the minimum amount of information in a manifest file:
Copy this code into ``start.php``:
- ``<name>`` is the display name of the plugin
- ``<id>`` must be the same as the directory you just created
- ``<requires>`` must include which version of Elgg your plugin requires
- ``<author>``, ``<version>`` and ``<description>`` should have some appropriate values but can be filled freely
Initializer
===========
Next, create ``start.php`` in the ``mod/hello/`` directory and copy this code into it:
.. code-block:: php
@@ -22,7 +51,7 @@ Copy this code into ``start.php``:
}
This piece of code tells Elgg that it should call the function
The above code tells Elgg that it should call the function
``hello_world_init()`` once the Elgg core system is initiated.
Registering a page handler
@@ -31,7 +60,7 @@ Registering a page handler
The next step is to register a page handler which has the purpose of handling
request that users make to the URL ``https://elgg.example.com/hello``.
Update the ``start.php`` to look like this:
Update ``start.php`` to look like this:
.. code-block:: php
@@ -48,13 +77,15 @@ Update the ``start.php`` to look like this:
}
The call to ``elgg_register_page_handler()`` tells Elgg that it should
call the function ``hello_world_page_handler()`` when user goes navigates to
call the function ``hello_world_page_handler()`` when a user navigates to
``https://elgg.example.com/hello/*``.
The ``hello_world_page_handler()`` passes off rendering the actual page to the
``resources/hello`` view.
The ``hello_world_page_handler()`` passes off rendering the actual page to a view file called ``hello.php``.
View file
=========
Create ``views/default/resources/hello.php`` with this content:
Create ``mod/hello/views/default/resources/hello.php`` with this content:
.. code-block:: php
@@ -71,7 +102,7 @@ Create ``views/default/resources/hello.php`` with this content:
echo elgg_view_page('Hello', $body);
We give an array of parameters to the ``elgg_view_layout()`` function, including:
The code creates an array of parameters to be given to the ``elgg_view_layout()`` function, including:
- The title of the page
- The contents of the page
@@ -80,4 +111,9 @@ We give an array of parameters to the ``elgg_view_layout()`` function, including
This creates the basic layout for the page. The layout is then run through
``elgg_view_page()`` which assembles and outputs the full page.
You can now go to the address https://elgg.example.com/hello/ and you should see your new page!
Last step
=========
Finally, activate the plugin through your Elgg administrator page: ``https://elgg.example.com/admin/plugins`` (the new plugin appears at the bottom).
You can now go to the address ``https://elgg.example.com/hello/`` and you should see your new page!

0 comments on commit dc5a4ad

Please sign in to comment.