Actions

J3.x

Difference between revisions of "Install From Web For Developers"

From Joomla! Documentation

(Web installation with joomlaapps-plugin)
m (Changing paths for the repos)
 
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{JVer|3.2|Joomla 3.2|long}} introduced the new Install from web feature that allows direct installations of extensions that are listed on JED. Making your extensions that are already on JED is a two step process:
+
{{version|3.2}}
 +
Joomla! 3.2 introduced the new Install from web feature that allows direct installations of extensions that are listed on JED. Making your extensions listed on JED available to Install from web is a two step process:
 +
# '''Fill out two new fields on the JED'''
 +
# '''Set up your site accordingly'''
  
==1. Fill out the 2 new fields on JED==
+
==Fill out two new fields on JED==
 
[[File:Install_from_Web_JED_Listing.png]]
 
[[File:Install_from_Web_JED_Listing.png]]
  
If you edit your extension listing on JED you will see the following new fields. Select the type of your extension from the list - there are four options:
+
If you edit your extension listing on JED you will see two new fields.  
 +
 
 +
The first is '''Download Type''', where you can select the download type for your extension from the four provided options:
 
# None
 
# None
 
# Free Direct Download Link:
 
# Free Direct Download Link:
 
# Free but Registration Required at Link:
 
# Free but Registration Required at Link:
# Commerical Purchase Required at Link:
+
# Commercial Purchase Required at Link:
 
+
And, '''Download/registration/purchase URL''' field. URL can target:
+
  
 +
The second field is '''Download/registration/purchase URL''' and can contain one of the following URL:
 
# A zip URL E.g. http://www.example.com/updates/com_extension_v9.9.zip
 
# A zip URL E.g. http://www.example.com/updates/com_extension_v9.9.zip
 
# A update XML URL E.g. http://www.example.com/updates/extension_update.xml
 
# A update XML URL E.g. http://www.example.com/updates/extension_update.xml
  
Note, the caching on the server for the Install from Web feature is set for 2-6 hours and so you probably won't see your changes right away in the Joomla backend.
+
'''Please note''': the caching on the server for the "Install from Web" feature is set for 2-6 hours and so you probably won't see your changes right away in the Joomla backend.
  
If your extension is a free direct download link then all your work is done and you can ignore the next steps :)
+
If your extension is a free direct download link then all your work is done and you can ignore the second step :)
  
== None ==
+
Here's some more detail on the download type.
  
This the most common case today. Only JED mandatory fields are filled, and 'Install From Web' fields are empty. The entry is shown, 'Download' button is shown and there's no 'Install' button.  
+
=== None ===
 +
This the most common case today, and it basically means that you can't or don't want to provide a direct install URL for your extension. Only JED mandatory fields are filled, and "Install from Web" fields remain empty.  
  
If your extension is just a '''free direct download link''' - then put in a link to the update XML you have or direct URL to the zip file.
+
When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found, the "Download" button is shown but there's no "Install" button.  
  
== Free Direct Download Link ==
+
=== Free Direct Download Link ===
 +
This is the option to choose if your extension is freely available, without registration or purchase. On the "Download/registration/purchase URL" you should put the URL of the update XML or directly the URL of the zip file.
  
If the URL field is filled with a zip or an update XML URL; 'Install' button appears, and the user can just click to install.
+
When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found and the "Install" button appears, so the user can just click to install your extension.
  
== Free but Registration Required at Link ==
+
=== Free but Registration Required at Link ===
 +
This is the option to choose if your extension requires registration to be downloaded. On the "Download/registration/purchase URL" you should put the URL of your site '''Registration Page'''.
  
If your extension requires registration then you need to put a link to your site '''Registration Page'''; 'Install' button appears, and the user can just click to be redirected to your site.
+
When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found and the "Install" button appears; when the user click on the install button, he/she will be redirected to the registration page on your site.
  
== Commerical Purchase Required at Link ==
+
When you setup your site correctly (see Step 2 below) after successful registration the user will be redirected back to his/her site to complete the web install.
  
If your extension requires a payment then you need to put a link to your site '''Purchase Page'''; 'Install' button appears, and the user can just click to be redirected to your site.
+
=== Commercial Purchase Required at Link ===
 +
This is the option to choose if your extension requires a purchase to be downloaded. On the "Download/registration/purchase URL" you should put the URL of your extension '''Purchase Page'''.
  
==2. Setting your site and extensions up for -Free but Registration Required at Link- Extension==
+
When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found and the "Install" button appears; when the user click on the install button, he/she will be redirected to the purchase page page on your site.
 +
 
 +
When you setup your site correctly (see Step 2 below) after successful puchase the user will be redirected back to his/her site to complete the web install.
 +
 
 +
[What about subscription? Is that more similar to "registration-based" or to "commercial-based"?]
 +
 
 +
== Setting up your site ==
 +
 
 +
As stated before, if your extension is freely available without the need for registration or purchase, you don't need to do anything else so skip this step.
 +
 
 +
=== Setting your site and extensions up for -Free but Registration Required at Link- Extension ===
  
 
If you require a consumer to register then you have to set up your site to deal with the user registration.
 
If you require a consumer to register then you have to set up your site to deal with the user registration.
Line 43: Line 61:
 
If not, the user fills the registration, and the last step of the web installation is NOT completed.
 
If not, the user fills the registration, and the last step of the web installation is NOT completed.
  
== How web installation works ==
+
=== How web installation works ===
  
 
When user clicks on the 'Install' button, Joomla submits these parameters:
 
When user clicks on the 'Install' button, Joomla submits these parameters:
  
# installat E.g. http://yourdomain.com/administrator/index.php?option=com_installer&view=install
+
# installat E.g. http://client.domain.com/administrator/index.php?option=com_installer&view=install
 
# installapp E.g. 99999
 
# installapp E.g. 99999
  
Line 56: Line 74:
 
While the registration is filled and processed, Joomla is expecting to receive the zip URL or an update XML URL. When it's received, Joomla finally completes the installation.
 
While the registration is filled and processed, Joomla is expecting to receive the zip URL or an update XML URL. When it's received, Joomla finally completes the installation.
  
== Web installation with joomlaapps-plugin ==
+
=== Web installation with jefreg-plugin ===
  
The '''joomlaapps-plugin''' is the reference implementation. A good starting point that was developed specifically for this purpose found [https://github.com/emavro/jefreg-plugin here].
+
The '''jefreg-plugin''' is the reference implementation. A good starting point that was developed specifically for this purpose found [https://github.com/joomla-extensions/install-from-web-plugins here].
  
 
The plugin has two parameters:
 
The plugin has two parameters:
Line 77: Line 95:
 
About Entry URL: this plugin is specifically designed for the Joomla User Component (Defaul value index.php?option=com_users&view=login) however it will also integrate nicely with any registration page. E.g. in Community Builder case simply by changing the entry point URL in the plugins parameters - generally it is recommended (but by no means compulsory) to point this to your login page. Note an empty value of this parameter will default to pointing to the Joomla User Component Login page.
 
About Entry URL: this plugin is specifically designed for the Joomla User Component (Defaul value index.php?option=com_users&view=login) however it will also integrate nicely with any registration page. E.g. in Community Builder case simply by changing the entry point URL in the plugins parameters - generally it is recommended (but by no means compulsory) to point this to your login page. Note an empty value of this parameter will default to pointing to the Joomla User Component Login page.
  
=== How to build joomlaapps-plugin ===
+
==== How to build jefreg-plugin ====
  
 
# Download the files from github
 
# Download the files from github
Line 83: Line 101:
 
# Zip all files, and install it in the Extension Manager
 
# Zip all files, and install it in the Extension Manager
  
== Setting your site and extensions up for a Commercial Extension ==
+
=== Setting your site and extensions up for a Commercial Extension ===
  
 
This will need more work than the previous step. It is advised that you download the same plugin - however you will have to integrate into the plugin an extra check to see if the user has purchased your extension. As different extensions implement this in many different ways it is left to extension developers to implement this functionality.
 
This will need more work than the previous step. It is advised that you download the same plugin - however you will have to integrate into the plugin an extra check to see if the user has purchased your extension. As different extensions implement this in many different ways it is left to extension developers to implement this functionality.
Line 89: Line 107:
 
The plugin can be used to get '''installat''' and '''installapp''' parameters, but it must NOT return the zip URL or update XML URL onUserLogin. When the purchase is completed, the operation can return to fill the web installation.
 
The plugin can be used to get '''installat''' and '''installapp''' parameters, but it must NOT return the zip URL or update XML URL onUserLogin. When the purchase is completed, the operation can return to fill the web installation.
  
== Source code for the feature ==
+
=== Source code for the feature ===
 
You can contribute bug fixes and new features to the following repositories:
 
You can contribute bug fixes and new features to the following repositories:
  
* https://github.com/joomla/extensions/tree/installfromweb
+
* https://github.com/joomla-extensions/install-from-web-client (client plugin)
* https://github.com/joomla-projects/joomla-cms/tree/feature-appstore-server
+
* https://github.com/joomla-extensions/install-from-web-server (server part)
* https://github.com/joomla/joomla-cms
+
* https://github.com/joomla-extensions/install-from-web-plugins (example plugin to be used by developers)
* https://github.com/joomla-projects/joomla-cms/tree/feature-appstore-client
+
* https://github.com/joomla/joomla-cms (CMS repo)
 +
 
 +
[[Category:Extension development]]
 +
[[Category:Extensions]]
 +
[[Category:Extension Installation]]

Latest revision as of 08:28, 15 January 2014

Joomla! 3.2 introduced the new Install from web feature that allows direct installations of extensions that are listed on JED. Making your extensions listed on JED available to Install from web is a two step process:

  1. Fill out two new fields on the JED
  2. Set up your site accordingly

Contents

Fill out two new fields on JED

Install from Web JED Listing.png

If you edit your extension listing on JED you will see two new fields.

The first is Download Type, where you can select the download type for your extension from the four provided options:

  1. None
  2. Free Direct Download Link:
  3. Free but Registration Required at Link:
  4. Commercial Purchase Required at Link:

The second field is Download/registration/purchase URL and can contain one of the following URL:

  1. A zip URL E.g. http://www.example.com/updates/com_extension_v9.9.zip
  2. A update XML URL E.g. http://www.example.com/updates/extension_update.xml

Please note: the caching on the server for the "Install from Web" feature is set for 2-6 hours and so you probably won't see your changes right away in the Joomla backend.

If your extension is a free direct download link then all your work is done and you can ignore the second step :)

Here's some more detail on the download type.

None

This the most common case today, and it basically means that you can't or don't want to provide a direct install URL for your extension. Only JED mandatory fields are filled, and "Install from Web" fields remain empty.

When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found, the "Download" button is shown but there's no "Install" button.

Free Direct Download Link

This is the option to choose if your extension is freely available, without registration or purchase. On the "Download/registration/purchase URL" you should put the URL of the update XML or directly the URL of the zip file.

When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found and the "Install" button appears, so the user can just click to install your extension.

Free but Registration Required at Link

This is the option to choose if your extension requires registration to be downloaded. On the "Download/registration/purchase URL" you should put the URL of your site Registration Page.

When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found and the "Install" button appears; when the user click on the install button, he/she will be redirected to the registration page on your site.

When you setup your site correctly (see Step 2 below) after successful registration the user will be redirected back to his/her site to complete the web install.

Commercial Purchase Required at Link

This is the option to choose if your extension requires a purchase to be downloaded. On the "Download/registration/purchase URL" you should put the URL of your extension Purchase Page.

When a user goes into his/her backend and click on the "Install from Web" tab, your extension can be found and the "Install" button appears; when the user click on the install button, he/she will be redirected to the purchase page page on your site.

When you setup your site correctly (see Step 2 below) after successful puchase the user will be redirected back to his/her site to complete the web install.

[What about subscription? Is that more similar to "registration-based" or to "commercial-based"?]

Setting up your site

As stated before, if your extension is freely available without the need for registration or purchase, you don't need to do anything else so skip this step.

Setting your site and extensions up for -Free but Registration Required at Link- Extension

If you require a consumer to register then you have to set up your site to deal with the user registration.

If not, the user fills the registration, and the last step of the web installation is NOT completed.

How web installation works

When user clicks on the 'Install' button, Joomla submits these parameters:

  1. installat E.g. http://client.domain.com/administrator/index.php?option=com_installer&view=install
  2. installapp E.g. 99999

installat is the return URL, and installapp is JED's extension ID.

To fill the web installation step, you backend has to receive these parameters, process the registration, and return to the installat URL.

While the registration is filled and processed, Joomla is expecting to receive the zip URL or an update XML URL. When it's received, Joomla finally completes the installation.

Web installation with jefreg-plugin

The jefreg-plugin is the reference implementation. A good starting point that was developed specifically for this purpose found here.

The plugin has two parameters:

  1. Files to download
  2. Entry URL

In the Files to Download parameter, the first parameter you have to set up is to point the plugin to your extensions update XML files, zip files or script (one per line).

99999=>http://www.example.com/updates/com_extension_v9.9.zip

30458=>http://www.example.com/updates/extension_update.xml

77777=>http://www.example.com/updates/download.php

If the line starts with an asterisk [*], it is ignored and left to be handled by plugins that support downloads after payment has been received. Examples of such plugins can be found as branches in the repository mentioned above.

About Entry URL: this plugin is specifically designed for the Joomla User Component (Defaul value index.php?option=com_users&view=login) however it will also integrate nicely with any registration page. E.g. in Community Builder case simply by changing the entry point URL in the plugins parameters - generally it is recommended (but by no means compulsory) to point this to your login page. Note an empty value of this parameter will default to pointing to the Joomla User Component Login page.

How to build jefreg-plugin

  1. Download the files from github
  2. Copy language files into the system plugin directory
  3. Zip all files, and install it in the Extension Manager

Setting your site and extensions up for a Commercial Extension

This will need more work than the previous step. It is advised that you download the same plugin - however you will have to integrate into the plugin an extra check to see if the user has purchased your extension. As different extensions implement this in many different ways it is left to extension developers to implement this functionality.

The plugin can be used to get installat and installapp parameters, but it must NOT return the zip URL or update XML URL onUserLogin. When the purchase is completed, the operation can return to fill the web installation.

Source code for the feature

You can contribute bug fixes and new features to the following repositories: