Simple Usage

Installation

The recommended method to install Media Hosting, is simply using your target website marketplace page. However, if you wish not to use concrete5 internal feature, you can follow the next instructions :

1. Download the zip archive
2. Uncompress the zip archive into your packages/ directory
3. Visit your Add Functionality page (located at http://yoursite.com/index.php/dashboard/extend/install )
4. Click on the Media Hosting Install button

After installing Media Hosting (either through downloading or preferably directly through your concrete5 website interface), you will be provided with 3 blocks :

• File Embed Block to embed a media (audio/video/anything) and record its viewing stats
• Image Hosting Block to view an image and record its viewing stats
• Media Hosting Upload Form to allow users to upload files to be shared

Media Hosting will also install a dashboard menu, and 5 files attributes :

• Hosted Shared Path recording the path by which the file is to be shared through the streamer
• MD5SUM will be automatically filled with the md5 sum of the file upon upload
• Record Stats boolean used to activate (or deactivate) the stat recording
• Shared boolean used to activate (or deactivate) the file sharing
• HTTP Redirect actually redirects to an external URL (do not directly serve the file)

Media Hosting finally comes with 2 automated jobs :

• Fix missing view location stats to retry all 'Unknown' locations
• Recompute all location stats to recompute all IPs locations.

(see the Jobs section for more details)

Embedding a media file in a page

File Embed Block comes with an image block. This block lets you embed an file in various ways within any page area, then record viewing statistics of that file. To add an image into your page, edit the page and add an instance of the File Embed Block to your page. The add dialog will ask you to select the type of embedding and the file to embed.

 

The following embedding types are available :

• generic embed embed any type of file directly in the page
• audio embed to embed audio files
• video embed to embed video files
• download link to place a simple download link to the file

The audio and video embed type support multiple sources. To add a source to your media embedding, click on the Add Source  button (only displayed for audio and video embeds).

The Embed Options will let you specify exactly how the embed will behave and be shown. Options depends on the type of embed selected.

The View Options tab will let you choose the size of the image, and as well as statistics recording options:

The Thumbnail tab let you add a thumbnail to the embed, and specify the thumbnail dimensions.

The Click Behavior tab will let you choose what behavior to apply if the image (or thumbnail) is clicked :

Here is a description of the choices available :

• No Link Nothing will be performed upon click
• External Link  Link the image to an external url
• Link to Page  Link to a concrete5 page
• Link to File Link to the image itself
• Custom Javascript Execute a custom javascript line upon click

Viewing an image in a page

Image Hosting Block comes with an image block. This block lets you show an image in various way within any page area, then record viewing statistics of that image. To add an image into your page, edit the page and add an instance of the Image Hosting Block to your page. The add dialog will ask you to select an image to show and specify an optional alt attribute :

 

The View Options tab will let you choose the size of the image, and as well as statistics recording options:

The Thumbnail tab let you specify how the image is seen as a thumbnail.

When the image is seen as a thumbnail, you have the choice to record the view statistics on the thumbnail view, and or on the image. In the latter case, the image view statistic will only be recorded if the image is shown in a lightbox overlay or if the image is linked to the click behavior.

 

The Click Behavior tab will let you choose what behavior to apply if the image (or thumbnail) is clicked :

Here is a description of the choices available :

• No Link Nothing will be performed upon click
• External Link  Link the image to an external url
• Link to Page  Link to a concrete5 page
• Link to Image  Link to the image itself
• Open the image in Lightbox Open the image in lightbox, with a custom title
• Custom Javascript Execute a custom javascript line upon click

In thumbnail mode and if the image is set to link to either the image itself or open in lightbox, the target image will be opened at the size defined in the View Options size (in case the Resize image option is activated), or full sized if not.

 

In normal mode, (as opposed to thumbnail mode), if the click behavior is set to Link to Image, the image will be opened full size.

Creating an uploader queue

Uploader queue are the way Media Hosting manages jobs to be run on upload. To upload an image, you need first to create an uploader.

 

To create an uploader, go to the dashboard uploaders page then click on the Add a new uploader button:

Each uploader must have a name. Each uploader can have a unique key, this key is used to upload automatically a file using the uploader page (see advanced an developer section of this documentation).

 

 

Each uploader performs specific tasks upon file upload based on the options selected :

Prefix Add a prefix to the shared path (when recording the sharing path). This prefix will be the first prepended to the recorded path (before the path given to the page and before the block prefix if the upload is coming from the upload form block).

HTTP Redirect Sets the http rediect attribute by prefixing a custom content to the path computed for this file. This enables you to actually serve the file from a different location (for instance from a CDN).

Record sharing path record the sharing path of uploaded files. The path can be either set directly in the uploader page parameters or via the upload block form.

Share uploaded files automatically share uploaded files (set the corresponding file attribute to Yes )

Record view stats of uploaded files automatically enable stat recording for uploaded files. (set the corresponding file attribute).

Automatically add uploaded files to sets, if enabled, will add the uploaded files to the file sets recorded. To add a fileset to the list, select it in the file set list, then click add. To remove a fileset, click on the x aside the fileset name.

Create file set based on path elements, if enabled, the path will be split in elements and for each element a file set will be created. For example, if the final path of an uploaded file is a/b/c/file.png, then filesets "a", "b", and "c" will be created and the uploaded file will be added to all these file sets.

Force owner, if enabled, the owner of the file will be changed to the "Upload As" option

Set Http Redirect, if enabled, the http redirect attribute will be set automatically by adding the path to the Http Redirect Prefix in the Http redirect option.

Upload files from a page

Media Hosting comes with the Media Hosting Upload Form block. This block will let your users upload a file through an uploader directly from a page. To do so, just add the block into your page. The following options will be available:

• User prompt Text message displayed on the block
• Enable Captcha Asks the user to fill a captcha for uploading
• Allow uploader choice Asks the user to select an uploader queue, or decide for him
• Share uploaded file Automatically share the uploaded file
• Allow overwrite Allow the user to overwrite files having the same path
• Path from filename Creates the shared path directly from the filename (add the prefix)
• Path Prefix Prefix the shared path with a fixed prefix
• Record sharing path Record a sharing path upon uploading
• Record view stats Automatically set to record view statistics on uploaded file
• Ajax refresh upload files in background, not redirecting to the upload page

Here is an example of the block in page:

 

Managing shared files

Media Hosting includes a Files dashboard page. From this page, you will be able to manage all existing shared files, as well as share new files. This page works exactly in the same way the File Manager does, except it adds some new menus to the context menu and to the operation list

 

The Shared page gives you the following choice of operation on single elements and files selections:

• View statistics will redirect you to the View Statistics page for that selection
• Share will redirect you to the Share page page for that selection
• Delete View Statistics will redirect you to the Settings page for that selection

By default, the Files manager will only show shared files (either through an image block, file embed block, or through a share path attribute), if you want to see not shared files, open the Advanced Search menu located on the top right part of the window, then click on Show not shared files checkbox, and finally refresh the list by clicking Search button.

 

 

Finally, You can directly upload and share a file using the built-in Upload button.

 

The afore mentioned interfaces are highlighted on the next screenshot:

Sharing an image

You can share a file through a number of ways :

• Share the file through an image block
• Share the file through an file embed block
• Using the Share dashboard page
• Uploading the file through the uploader block pointing to a sharing uploader queue
• Uploading the file through the uploader page directly (via an external program)
• Manually filling the Hosting Shared Path and Shared file attribute

The recommended way of sharing an existing file is either using the image block/file embed block to show it on your website, or using the Share  dashboard page. The next screenshot show an highlight of that page :

Accessing viewing statistics

All the statistics are available in the View statistics dashboard page.

 

By default, the statistics page will show the aggregated results of all existing view log stat. Five reports are computed :

1. Country: showing the repartition by country, based on the IP address
2. Cities: showing the repartition by city (globally), based on the IP address
3. Language: showing the repartition by language advertised by the web browser
4. Domain: showing the repartition by referer domain name
5. Keywords: showing the repartition by custom keywords

You can collapse a report by clicking on the report heading itself. Each report can be filtered to only include the most relevant results by changing the limit to value and then clicking on Update button.

 

 

Each report have 5 panes :

• All Times Overview showing the global overview (repartition only) of all time recorded views
• This Year showing a repartition and an evolution (grouped by month)
• This Month showing a repartition and an evolution (grouped by day)
• Last 24 Hours showing a repartition and an evolution (grouped by hours)
• Last 3 Hours showing a repartition and a evolution (grouped by 5 minutes)

Each pane will include a pie chart and a bar chart to show the repartition in the concerned time period. All interval constraint panes (year/month/24 hours/3 hours) will additionally show an evolution of that repartition with an area chart and a line chart.

 

 

Finally you can filter the statistics with various filters:

• By file, file set, or prefix (using the file filter, or making a selection from the Files dashboard page)
• By view date, country, city, language, domain, or keyword (using the advanced filters)

The afore mentioned interfaces are highlighted in the next screenshot :

For advanced users

Deleting part of or all view statistics

The Settings dashboard page will allow you to delete a part of or all the view statistics. The same filters used on the statistics page can be used on the settings page to select the statistics as well.

 

By default the deletion interface is hidden, to show it, click on the show deletion options button in the Settings dashboard page.

 

 

The following screenshot shows the deletion options :

Customizing the upload page

The upload page includes several areas. You can edit and add blocks to this page by either visiting directly the page at http://yoursite.com/gnt_image_hosting/upload (or to your custom upload page if you created one), or by choosing it in the Full site map. By default, this page is excluded from navigation.

 

 

The following screenshot shows the upload page in edit mode :

The page contains the following areas

• Upload Header, and Upload Footer : always shown
• Upload Success : only shown when a file had been successfully uploaded
• Upload Error : only shown if an upload attempt failed for any reason (mostly security)

Beware that this page is only shown when using the upload block in non ajax mode.

Serving files from a CDN

Media Hosting comes with an HTTP redirect ability. When used appropriately, you can actually manage your media files on your server but serve them from another server, e.g.: a CDN (and still collect view stats on them), here is how:

To make this work, you will have to create a directory structure that matches your path structure on the CDN. For instance, if you have a file that is shared under /my/share/path/thefile.mp4, and that your CDN base url is http://www.mycdn.com/pub/, then you must make your file accessible through http://www.mycdm.com/pub/my/share/path/thefile.mp4.

Once this is done, just set the HTTP redirect attribute to http://www.mycdn.com/pub. At this point, the stremer and the blocks (file or image block), will record the view stats, but take the file from the location you specified.

For more automation, the attribute can be automatically set in the uploader queue.

At the moment, only files can be served using HTTP redirect, not thumbnails, if you need this feature, please contact us directly.

Custom stream or upload page

Media Hosting allows you to use your own custom stream/upload page.

 

 

For instance, if you wanted to have your own custom url, say, http://yoursite.com/oh/streamit for the streamer or uploader instead of the default http://yoursite.com/gnt_image_hosting/stream  or http://yoursite.com/gnt_image_hosting/upload :

1. Go to the Settings page,
2. Select Create New Custom Page in the drop down menu in front of the page you want to change.
3. Enter the url you want to use (in our example oh/streamit )
4. And finally, click on the Save button.

Media Hosting will then create a page at the desired location and use it as a stream or upload page based on your choice.

streamer page parameters

Media Hosting stream page will let you manipulate images (if streaming images) as well as record other statistics information along with streaming the corresponding image. Here is the list of supported parameters :

• path the shared path of the file to stream
• width the width you want the image resized to
• height the height you want the image to be resized to
• crop in case the image is resized, shall we crop it ? (1 means crop)
• keywords a comma separated list of keywords you want to be recorded along with the view stats

In case both path and bID parameters are omitted, the first parameter name will be considered to be the path.

 

Examples:

Will stream the image name /my/path/file.png, resize the image to 640x480 (no cropping), and record the keywords foo, bar, and turtle along with the view stat (if the corresponding path is setup to record stats).

 

The preceding url was equivalent to :

uploader page API usage

Media Hosting is designed to let you upload files directly from another program. The uploader page located at http://yoursite.com/gnt_image_hosting/upload can be very simply commanded from any http request.

 

To upload a file, you will need to create an uploader (see preceding documentation), then record its key (say UPLOADERKEY). Then issue a POST or GET request to the uploader page to upload it (although parameters can be read from GET for convinience, the file will need to be posted).

 

Here are the available parameters :

• file must contain the file information to upload (mandatory).
• key must contain the uploader key in our case UPLOADERKEY (mandatory).
• path must contain the path under which the file will be shared
• prefix if present, will be pre-pended to the path
• share if 0, will disable sharing (but still recording the sharing path)
• recordStats if 0, will disable recording view stats for this element
• recordPath if 0, will disable recording the sharing path (hence disabling the sharing)
• ajax if 1, only simple content will be printed in the response (no html header/footer)
• parseable if 1, only output text, no html (implies ajax)

For example, posting a file to the following url :

Will upload the file, sets its shared path to /some/where/my_image.png and disable recording view stat for this uploaded file.

 

In case a file with the same sharing path is found, that file is overwritten. Actually, the MD5sum of the new uploaded file is compared to the old one, and the new one only gets updated if the MD5sum mismatches, so it is safe to upload twice the same file, nothing will actually happen.

Fixing 'Unknown' IP locations statistics

By default, this addon uses HostIP.info online service to lookup IP locations. This API does not give 100% results and sometimes does not know about the IP location. Fortunately, updates to that API is done on a daily basis, which means that an Unknown IP yesterday may not be unknown anymore today! Media Hosting provides two automated jobs to take advantage of those updates :

• Fix missing view location stats to retry all 'Unknown' locations
• Recompute all location stats to recompute all IPs locations.

By running the Fix missing view location stats once in a while (or yet better, by automating it), your statistics will get refined every time with the latest Hostip.info data.

Changing the default IP Locator engine

As mentioned, by default this addon uses HostIP.org online service to lookup IP locations. You can change this by first installing other IP locators engine (for example look at the Maxmind IP GeoLoc addon), and then changing the default engine in the settings page.

For developers

Using your own uploader/streamer page

This is for developers only, but what if you wanted to have your own custom url for the streamer or uploader instead of the default http://yoursite.com/gnt_image_hosting/stream  or http://yoursite.com/gnt_image_hosting/upload for instance?

 

Well that is actually pretty simple, create a single page where you want it, at for instance : http://yoursite.com/this/is/where/I/want/my/streamer and include this into your page code :

include( DIR_PACKAGES . "/gnt_image_hosting/single_pages/gnt_image_hosting/stream.php" );

or (for the uploader) :

include( DIR_PACKAGES . "/gnt_image_hosting/single_pages/gnt_image_hosting/upload.php" );

Those two single pages actually don't have any controller so you can safely include them directly. If you want then Media Hosting  to use your custom page internally, go to the Menu page and select your page as Stream or Upload Page. Media Hosting can only use one stream page or one upload page by default, but multiple pages can exist separately (you can use them directly just fine). Additionally, uou can directly create a sample page from the Settings page in the dashboard.

Programmatically record stats

To programmatically record view stats onto a file, you will need to retrieve the HostedMedia object associated to the file and record the view log. Assuming that $fID holds the file ID :

Loader::model( 'hostedmedia', 'gnt_image_hosting');
HostedMedia::getByID($fID)->recordView();

That code will automatically check if the Record Stats attribute is set onto that file before recording the stats. You can find more information on the API by having a look at models/hostedmedia.php class.

For Concrete5 addon developers

If, like me, you are a concrete5 addon developer, you already noticed you can not add images into your marketplace addon documentation pages since c5 website will not host them for you. Well, I initially built this addon for that reason.

 

Simply speaking, here is the workflow I would recommend for you :

1. Create your html doc files into your project somewhere
2. Place your images into that project
3. Link your images from your documentation adding a pattern string into the src attribute of the img 
, say PREFIX
4. Now to test it in local, just replace that prefix by the local path using something like this sed -i yourfile -e "s,PREFIX,your_actual_path," (notice the use of "," as pattern delimiter instead of / as path do contain / ) 
5. To actually test it on remote, go for this procedure
   1. install the Media Hosting package onto your website
   2. setup an uploader (see the former spec) and get the key
   3. upload your files using the uploader from your build script with something like this : curl -F key=UPLOADER_KEY -F path=your_handle/localfile.png -F file=@localfile.png http://mysite.com/gnt_image_hosting/upload 
   4. replace the PREFIX by your website stream url with something like this : sed -i yourfile -e "s,PREFIX,http://mysite.com/gnt_image_hosting/stream?your_handle/localfile.png" 

And that's it!

 

This can be simply achieved with the following simple makefile script for instance:

BUILD=build
DOCDIR=doc
LOCAL=$(BUILD)/$(DOC)/local
REAL=$(BUILD)/$(DOC)/real
UPLOADERKEY=283987198778877287
BASEURL=http://www.mysite.com
HANDLE=my_package_handle
 
UPLOAD=$(BASEURL)/gnt_image_hosting/upload
STREAM=$(BASEURL)/gnt_image_hosting/stream
 
build_doc_local:
	mkdir -p $(LOCAL)
	cp $(DOCDIR)/*png $(LOCAL)/
	( for $$x in $(DOCDIR)/*.html; do cat $$x | sed -e "s/PREFIX//" > $(LOCAL)/$$x )
 
build_doc_real:
	mkdir -p $(REAL)
	# uploading files
	( \
		cd $(DOCDIR) ;\
		for $$x in *png; do \
		do curl -F path=$(HANDLE)/$$x -F file=@$$x -F key=$(UPLOADERKEY) $(UPLOAD); 
		done ; \
	)
	#replacing image links
	( \
		for $$x in $(DOCDIR)/*.html; do \
		base=$$(basename $$x); \
		cat $$x | sed -e "s,PREFIX,$(STREAM)?$(HANDLE)/$$base," > $(REAL)/$$x ; \
		done; \
	)
 

I hope this will help concrete5 developers to build awesome documentations for their addons.

 

As a bonus, you will then be able to record view statistics on the images you embed in your documentation. 

Creating your own IP locator

Media Hosting can use an external IP locator service either from your site override, or onto a package you are creating. To add an ip locator in your site override, create the following directory:

your_site/blocks/gnt_image_hosting/models/iplocators

To add an ip locator to a package you are creating, create the following directory :

your_package/models/gnt_image_hosting/iplocators

Within the created directory, create a file with the named after the ip locator class you want, for instance my_service.php. Now in that file, you will need to define a class inheriting from IPLocator named after your file name (camel-cased) and suffixed with Locator. Following our example, if the file is named my_service.php then the class should be MyServiceLocator

 

Here is what such a class could look like :

<?php defined('C5_EXECUTE') or die('Access Denied.');
 
class MyServiceLocator extends IPLocator
{
	public function name() { return t("My Service IP locator" ); }
	public function isFunctionnal() { return true; }
	public function getStandardCountryName($ip)
	{
		// return a string "Country (ISO CODE)" for that ip
		// return null if not known
		return "France (FR)";
	}
 
	public function getCityName($ip)
	{
		// return the name of the city or null if not known
		return "Paris";
	}
}
 
 
// vim: set noexpandtab ts=4 :
 

In order to override an existing IP Locator engine, just copy the file in your site override your_site/blocks/gnt_image_hosting/models/iplocators directory and the ip locator will be auto-magically overridden by your new file.

Support

If you need any assistance regarding this addon, please use the support forum directly.

 

 

In case you need a new feature, or anything else, feel free to contact us threw concrete5 PM system, or contact us directly.