Applications

Community Documentation

Congratulations on choosing a Filemobile Media Community, our most advanced application.

The Media Community is fully functional, feature-rich interactive web application that enables you to provide a unique and engaging experience for your users. This application includes everything you need to collect and publish user-generated content including user profiles, galleries, uploaders, webcam recording, maps flexible categories and robust search.

While the Media Community can be completely customized, it can also be branded and deployed very quickly - it is a fully functional website out of the box. This documentation assumes a basic design implementation. There are few key concepts that you should understand in order to prepare your deployment and you should review this documentation site before you dive in.



Quick Start Guide

Here is a quick run-down of everything you need to do to get the Media Community loaded up into a browser error-free:

  1. Read the System Overview
  2. Install the Application in your Media Factory project
  3. Set up responding domains
  4. Create some groups
  5. Create channels
  6. Create a collection
  7. Configure Facebook Login
  8. Configure Global Variables
  9. Edit email copy

Next, you'll want to make it look your own:

  1. Edit and replace the sprites
  2. Add other images
  3. Edit the CSS
  4. Change form fields



System Overview

Templates

All Media Factory applications consist of the following types of templates:

TypeDescription
Wrapper templatesThe main wrapper includes the HTML file headers, meta and content to be included on every page of the site. Other wrappers can be XML, text only, HTML email, etc. All application templates are assigned a wrapper.
Application templatesThe "meat" of the application. Application templates are assigned URLs and contain the code specific to each page, for example: /home, /profile, /mediadetail, etc. There are also sub-templates that are not assigned URLs but are instead called from within application templates with parameters using the <fm:Include> component.
CSS stylesheetsAn application can contain many stylesheets that are loaded in sequence from the global.css stylesheet by /services/cssloader which is optimized for performance cache. Tip: During development, put a copy of your stylesheet in your assets folder for quicker updates.
Email templatesSimilar to application templates, these are all the emails that the system is going to send out for you. There is more information on email templates in the developer docs.

Tip: For in-depth template code documentation, please visit http://developer.mediafactory.fm.

Backups

Backing up your Media Community is easy.

If you plan on making changes to an application (live or staging), we recommend you first make a backup. Inside the Application click "Backup and Restore". On this page, on the left hand side, change the filename field (something like "myappname_todaysdate" works well) and click "Download". This will download a XML file of all the templates and translations in that app. This is a great way to move your staging application changes to the live application. If something goes wrong, or you want to update a live app with the staging version, simply restore that XML file. On the right side of the same page, click "browse", find that XML backup, and click "Restore".

It is recommended that you have two applications for each project. A live app and a staging app. The live app will contain your custom URL(s) (http://www.mydomain.com/) and the project.fm domain (myappname.projects.fm) and will be what the the world sees. The staging app will only need a projects.fm domain (staging.myappname.projects.fm) and it's where you should do all your development. And only after testing should you backup and restore the staging app to live.



Editing Templates

The Media Factory CMS includes a basic template editor that uses file locking and records that last edit by time and user. The editor is accessed via the applications tab in Media Factory.

The web-based editor may not provide an ideal experience for a developer working for many hours on customizing the application. If you prefer a desktop editor experience, you will need to configure WebDAV for Media Factory. The instructions can be found in the developer documentation.

Caution: Please note that WebDAV for Media Factory is beta, and while it is well used by many developers it can be unpredicatable in some configurations.

Caution: WebDAV for Media Factory does not support file locking, so be careful not to overwrite other developers if you are working in a group.

Caution: WebDAV for Media Factory does not support time and user stamping.



Assets

Assets are the static files that your application uses such as images, custom JavaScripts, custom CSS or anything else you might need.

There are two ways to manage your assets: the Asset Manager web interface in Media Factory and via WebDAV.

The Asset Manager can be accessed via Applications > Assets in Media Factory. This basic interface is limited to uploading one file at time, whereas WebDAV allows batch uploading using drag and drop.

Note the two fields highlighted above: Template URL and Absolute URL. The absolute URL is the actual path to the image which MUST be used in the template application - relative URLs will not work. The Template URL makes use of the {$assetbase} variable, which renders the base path to your assets. So, when placed in a Media Factory template, both of these strings will render the same URL path.

Why would we do such a thing? The first and most important reason is that your assetbase URL can change if you choose to enable secure HTTPs on your project. Recent changes in Facebook now require all apps to be HTTPS, and if you used {$assetbase}, all your URLs can be updated at once. Another benefit is portability across projects, each of which have their own asset base URLs.



System Updates and Application Upgrades

The Media Factory system consists of three main components: the Media Factory CMS, Applications and the API. Each are handled differently with respect to upgrades.

ComponentDescription
Media FactoryThe back-end system, fully hosted by Filemobile. Upgrades happen regularly and automatically following emailed release notes that are also available at the Developer Portal and Twitter. These upgrades do not affect the front-end community website.
Application - JavaScriptsOur static JS files are upgraded with bug fixes automatically and tested for backwards compatibility. Major new releases of the application use new JS files. This is rare, and implications should be discussed if a major application upgrade is requested. It is highly recommended not to download and edit our static JS files. Better to create a new JS file for your functions or submit a feature request / support from Filemobile.
Application - HTML, CSS and FMLThe front-end website, hosted by Filemobile and customized by you. We’ve made efforts to keep the application as modular as practical to simplify upgrades (ie. sub templates) but this can be challenging if the application has been heavily customized. We recommend creating a separate CSS stylesheet for your custom styles.
APIThere is one version of the API. Web services are regularly extended and are tested to ensure backwards compatibility. Changes to web services should not affect any live applications. In rare cases where an interruption may occur, we will notify you via the release notes, Media Factory email list and Twitter.

Configuration

Your Media Community was likely installed for you. Now you need to configure it.

Back to Quick Start Guide

Responding Domains Setup

One of the first things that you will likely ask yourself is, "how do I see the website?" By default, the application has probably been set up on a URL similar to http://your-app.projects.fm. This URL is configurable in the Settings section of your application.

First, visit the application settings for your application:

Domains are configured on the first tab: General.

Tip: To use your own domain, create a CNAME to www.filemobile.com and enter your domain in the Application Settings section. Media Factory takes care of the rest.

On the General tab, you can change the name of the application and edit the responding domains. You can also add additional domains to the list. For example, if you are hosting a website in multiple languages, you would configure on URL for each language with a corresponding language parameter beside the domain name (en). When that URL is requested, the application is automatically displayed in the appropriate language. For more information on the translator, see Translation below.

FieldDescription
Application nameThe name of the application. Tip: Using the URL as the Application name makes it easier to identify in lists and in WebDAV environments.
Main application domainThis domain name will be used to determine links to your application, in for example RSS feeds. It must match one of the responding domains below. Do not include 'http://'.
Responding domainsAdd in any subdomains (or additional domains) and languages that should link to your application. The second field is a 2-letter ISO countrycode for the translated language you want to use for this domain. Do not include 'http://'."
GMaps keyThe GMaps Key field is only used in legacy, pre-3.0 applications using the deprecated Google Maps API V2. Newer apps don't require this key, and this field can be left blank. You can still get a key at http://code.google.com/apis/maps/signup.html
FB App IDIf you are using Facebook Login, you'll need to enter the App ID and Secret keys that are associated with that domain. For more information on setting up Facebook, see Facebook Setup below.
FB SecretIf you are using Facebook Login, you'll need to enter the App ID and Secret keys that are associated with that domain. For more information on setting up Facebook, see Facebook Setup below.
Report Offensive EmailWebsite users can report media and comments as offensive. These reports are sent to the email address entered here.

Back to Quick Start Guide



Groups Setup

Groups represent the organization of media in the application. Groups can be found in the Community > Groups section of Media Factory.

Tip: Check out the article about groups, channels and collections on the Filemobile Blog.

The hierachy and list order of groups is displayed on the /grouplist and /galleries pages on the website. The application is optimized for displaying groups up to three layers deep, although the template code can be customized to meet your exact needs if necessary. If you want to change the order of the groups, just drag and drop in Media Factory. If you want to hide a group, simply deny it. The top-level group is configured in the galleryGroupFilter parameter of the Global Variables.

Tip: Create two top-level groups - one for displaying content, and one for content not for display. This is handy for keeping things organized.

Users can upload into multiple groups, and by default all bottom-level groups that appear on the website can accept uploads. You can modify what groups are displayed for upload in the sub_group_selector template. Use caution, this is for advanced users.

Tip: Create stand-alone upload forms by repurposing the /upload template using a single group as a fixed hidden field. Put them anywhere!

Another important feature of groups is that each group can have its own homepage, similar to the main community homepage. A group page aggregates everything within the group, including (optional) sub-groups. To access and edit the details of a group, click the group name on the /communitygroups page in Media Factory.

On the group info page, there are number of fields you should become familiar with.

Below is an explanation of the various fields that apply to the Media Community application. There are lot of other things that you can do with groups, but let's stick to what we need for this project!

FieldDescription
LogoEnter a media ID of a file uploaded into Media Factory. Various thumbnail sizes of this image are used throughout the application.
NameThe name of the group, used throughout the application.
DescriptionA brief description of the group. Not currently used in the application, but the field is available in the templates.
Parent groupThe containing group in the hierarchy - this group's mom or dad. You can use the drop down to reassign the group to a different parent group.
EmailThe email address of the group. Any images, video, audio or text emailed to this address ends up in this group.
MapThe map is used to populate the Longitude and Latitude fields below. These values are used to center maps on a geographic areas representative of the group, or placing the group logo on a map.
Email TemplateThe email template to use when sending email to group members. If this is set, any time content is added to the group, all group members receive the email. This is useful for alerting moderators or producers that new content has arrived.
toutThis is an example of custom metadata. You can add as much metadata as you want, but "tout" is recommended. The value of this field should be a tout header image for the group homepage.
Custom 1This is a custom field that can be used for search and sorting. For example, if your group had a membership fee, you could use this field to sort all groups by price. Sorry about the uncreative name of the field.

Back to Quick Start Guide



Channels Setup

Channels are used to keep different types of media separate. This is important for filtering in the application as well as reporting. Channels also govern geo-fencing.

Tip: Check out the article about groups, channels and collections on the Filemobile Blog.

Channels can be found in the Media > Channels section of Media Factory.

You should set up at least these standard channels:

ChannelDescription
ContentThis is where all the uploads from users will reside. If you are planning a multilingual website, you can create sub-channels in order to keep the content separate. For each language of the website, the content channel must be configured in the Global Vars
CommentsThis is where all the comments will reside. If you are planning a multilingual website, you can create sub-channels in order to keep the comments separate. For each language of the website, the content channel must be configured in the Global Vars
AvatarsThis is where all user avatars will reside. Since avatars should not show up in galleries, we filter them out with a channel of their own.
Group LogosYou can upload media to be used as logos for your groups. Upload them here. Since avatars should not show up in galleries, we filter them out with a channel of their own

To create a new channel, follow these steps:

  1. Inside Media Factory, hover over "Media Manager" and click on "Channels".
  2. Click "Add Channel".
  3. Fill in the name field with "Content". When you click on the shortname field, it should autofill with "content".
  4. No other information is required at this point.
  5. Click "Create".
  6. The new channel should now show up in the list. Note the id number. You will need it for setting up the global variables.
  7. Repeat these steps for the other channels.

Next, you should configure the Content channel to send the appropriate moderation emails. Also make sure that the Project Settings are correct.

From the drop-down menus, select the appropriate Approved moderation email and Denied moderation email. These emails should be included in your Media Community.

Back to Quick Start Guide



Collections

Collections are like playlists, and have lots of uses in Media Factory applications. In order to get up and running with the Media Community application, you need to create at least one collection for featured content.

To create a collection, visit the Media > Collections section of Media Factory:

Create the "Featured" collection.

  1. Inside Media Factory, hover over "Media Manager" and click on "Collections".
  2. Click "New Collection".
  3. Fill in the name field with "Featured".
  4. Set a description and select "Saved Search".
  5. Click "Create".
  6. Set your search preferences, and click Update. The logic used in this collection will govern how the featured item is selected on the main homepage and all group home pages.
  7. The new collection should now show when you return to the list. Note the id number. You will need this for configuring Global Variables.

Back to Quick Start Guide



Facebook Setup

If you want to use Facebook Login in the Media Community, you'll have to first create a Facebook Application.

  1. Login to the Facebook developer section and create a new application.


  2. You should arrive in the Settings > Basic section, where you can edit your app icon and name. These elements show up when users login to your site with Facebook for the first time.


  3. In the Website section below, enter the public URL of your Media Community website. If you have more than one URL, you'll need multiple Facebook Apps for login.
  4. Copy the App ID and App Secret keys and paste them into your Media Community application settings. See Responding Domains above.
  5. Go to the Setting > Advanced section and make sure that you have a support email entered. This is a Facebook requirement.



When a user submits an entry or adds a comment, they are prompted to add it to Facebook. You can change the default text that appears in the "entry" category of the Translator.

VariableDefaultNotes
facebookApp on Filemobile's Media CommunityThe text that comes after the title when submitting a new entry.
facebookCaptionComment onWhen submitting a comment, this goes next to the title of the media the user is commenting on.
facebookCommentYour Facebook comment isWhen adding a new comment
facebookEventuploadedThe text that comes before the entry title when uploading.

Tip: Create a Facebook alter-ego for testing

You are going to be testing the behaviour and copy of messages shared to Facebook. In order to avoid annoying your friends and spoiling the surprise for your sponsor, create a second or third Facebook account. Connect your alter-egos so you can see what the feed messages will look like.

Back to Quick Start Guide



Translation

The Media Factory application template system includes a powerful translation tool. Each application has its own table of translations that can be found in the Translator section:


Translations are broken out into categories, and are made up of keywords and associated strings. The usage syntax in a template is {%category:keyword}. The template will render the appropriate translation based on URL, which is configured in Responding Domains above.

More detailed information can be found in the developer documentation, or watch this quick video:

Back to Quick Start Guide



Global Vars

In addition to managing language translations for multilingual websites, the Translator tool also manages global variables.

Open the translator section of the application inside Media Factory and open the var section:


The following table describes each of these variables, and identifies which ones MUST be changed:

variablechange requiredpossible valuesnotes
allowedFiletypesCommentno['1','2','3,'4']Sets the types of files accepted as comments (1=image, 2=video, 3=audio, 4=text)
allowedFiletypesEnterno['1','2','3,'4']Sets the types of files accepted as uploads (1=image, 2=video, 3=audio, 4=text)
anonymousCommentsno'true' or 'false'Determines whether your site will accept anonymous comments
appNameyesThe name of your communitySets the name of the application that is used within the application
channelCommentsyesID of the 'Comments' channel you createdSets the base channel for the comments. If this value isn't changed, the site will break
channelContentyesID of the 'Content' channel you createdSets the base channel for uploads. If this value isn't changed, the site will break
collectionFeaturedyesID of the 'Featured' collection you createdSets the collection used to populate featured content across all groups, including the homepage featured item. Tip: Use a saved search to automate the featured items across your website!
fbConnectno'true' or 'false'Anything other then 'true' will hide all Facebook buttons and information
fblangnoen_USUsed to tell Facebook the language of our site
fbMessageLinknochannelsThis page name is used when directing Facebook users to your channels gallery
fileSizeLimitnoint >0 in MB (default 50)The maximum file size accepted by the uploader. Can be up to 1000MB, but very large files can negatively impact user experience.
file_upload_limitnointegerThe maximum number of files that can be uploaded at once.
galleryGroupFilteryesGroup IDThe ID of the top-level group to be included in the application. All child groups are also included.
groupListSortnosort parameterDetermines how groups are sorted on media details pages. (of approvedmediacount, notdeniedmediacount)
imageResizeUrlLivenohttp://cimg.filemobile.comThe address of the service to fetch resized images. FM support only, do not change.
imageResizeUrlStagingnohttp://mf.staging.filemobile.comThe address of the service to fetch resized images. FM support only, do not change.
langno'en', 'fr', etc...Language code used to tell our application how to render multilingual content
languageToggleyesThe public URLs of your applicationUsed to toggle between languages. Note that the English URL is on the French side, and vice versa.
maxDescriptionLengthnoint > 0Maximum number of characters allowed in the description on /upload
medialistCommentFiletypeno1,2,3,4Types of comments to appear in comment lists
moderationCommentno'approved' or 'notdenied''approved' will only show approved comments, 'notdenied' will show approved and unmoderated comments
moderationGroupsno'approved' or 'notdenied''approved' will only show approved media, 'notdenied' will show approved and unmoderated media
moderationMediano'approved' or 'notdenied''approved' will only show approved groups, 'notdenied' will show approved and unmoderated group
multimediaCommentsno'true' or 'false'Select whether your community will allow multimedia comments
pendingno'true' or 'false'Determines whether users can see their unmoderated content on their own dashboard.
privacyno'true' or 'false'Determines whether users can set their content as hidden.
subChannelUploadyes'true' or 'false'Only valid as false if you are NOT using groups for uploading - this should be set to true in most cases.
shareEmailnono-reply@yourdomain.comWhen people send email to each other from within the contest, this is the "from" address
subChannelUploadno'true' or 'false'If you have entry sub channels you'll want to set this to 'true' so users can choose what category their entries belong to. If you don't have sub channels, leave it set to 'false' so the 'Entries' channel will be automatically chosen
transcoderHDnoint > 0DEPRECATED - This is the transcoder profile ID for HD video. Leave this blank if you don't want to display the SD/HD toggle on /mediadetail
transcoderSDnoint > 0This is the transcoder profile ID for videos. The default is 22, but you can also set up custom transcoder profiles.
transcoderThumbnoint > 0 (default 15)This is the transcoder profile ID for video thumbnails. Change this if you have created a custom transcoder profile for watermarks or other effects.
uploadTonogroupsDetermines whether users are presented with groups or channel upload interface. The default and recommended setting is groups.
webcamCommentno'true' or 'false'Anything other then 'true' will hide the webcam in the comments
webcamUpload *no'true' or 'false'Anything other then 'true' will hide the webcam in the upload

* Caution: Webcam upload is beta only.

Back to Quick Start Guide



Project Settings

Project settings concern configuration that affects all applications, media and users in the project. They can be found under Settings > Project settings in Media Factory:

Below is a table describing the various projects settings:

SettingDescription
Project titleThe title of the project as it appears in the project drop-down menu in Media Factory. If you only have one project, you can't see the drop-down menu.
Media moderationSets the overall rule of whether to ever show unmoderated content in an application. It is recommended to set this to Post, since this allows more flexibility in the application.
Media moderation emailSets the overall rule of whether to ever send moderation email. If you intend to send moderation email - when media is approved or denied - set this to Send by default.
Media moderation email - Approved / DeniedThis the email template that will be sent when ANY MEDIA is approved or denied. This should be set to None. You should set email templates on the channel configuration page, so that you can specify different emails for content uploads and comments.
Group moderation email - Approved / DeniedThis the email template that will be sent when ANY GROUP is approved or denied. You probably won't send these types of emails with the Media Community, so leave it set to none.
Event moderation email - Approved / DeniedThis the email template that will be sent when ANY EVENT is approved or denied. You probably won't send these types of emails with the Media Community, so leave it set to none.
Storage domainThese needs to edited if you are using a CDN to deliver your media.
Media callback URLSome actions like approve and deny can trigger an XML payload to be posted to this URL.


Emails

There are a number of system emails that are going to be sent out to your users. You can customize the copy and graphics in the emails by visiting the Email templates section of your application:

EmailDescription
registrationThe email that will be sent when users register on your site. Plain text by default, but you can use the HTML wrapper to really wow them.
Media added to GroupThis email is sent to group members when content arrives. This is handy for notifying different groups of moderators.
Media Approved (en/fr)This is an HTML email that is sent to the user once their content has been approved by moderators. We've provided you with both an English and French version. Set the appropriate email in the channel configuration.
tellafriendThis is the email that is sent when users click to email a file from the media detail page.
lostpasswordThis email contains instuctions and a system-generated link to reset a user's password.

Tip: You can find information on the variables available in the system email templates in the Developer Documentation.



Design

Overview

The Media Community can be completely customized in its layout, look and feel. However, using the guidelines found here, you can apply your branding and color scheme to the application in a relatively short amount of time. This section provides a workflow walkthrough with everything you need to personalize the creative in your community.

Most of the image assets in the application are contained in sprites. A sprite is a single image file that contains multiple background images used in CSS. The stylesheet design.css includes all the paths to the sprites and some images. Once you've edited the image PSDs, upload your new sprite PNGs to your asset folder.

Tip: A Firefox plugin that is very, very highly recommended is Firebug. It allows you to inspect and modify HTML and CSS in the browser and see the results in realtime.



Image List

Below is a table describing the graphic elements that need to be considered when designing your application:

Creative elementDescription
sprite.pngThis sprite image is used for menu bar items, tabs, icons, form buttons, pager, and search box. Change the path in design.css.
corners.pngThis sprite image is used for the menu bar background, tab contents background, and the top and bottom of the various boxes. Change the path in design.css.
backgrounds.pngThis sprite image contains the small, medium and large content box backgrounds that will tile vertically. Change the path in design.css.
toutsTouts are the big call-to-action graphics at the top of the home and group pages, below the navigation. Change the path in the /home template and configure your groups to each have their own tout.



PSDs

Each sprite PSD contains a layer with information saying what part of the site the image belongs to, and what CSS style uses that part of the image (in case you need to change the CSS height or width).

You are free to edit the sprite as much as you want, but the further you stray from the default image sizes and postition, the more changes you'll have to make to the CSS.

sprite.png

corners.png

backgrounds.png

Other Images

There are some images that can't, or shouldn't, be added to the sprites. These include the homepage tout, gallery thumbnail backgrounds, form element background, loading icon and default thumbnail icons. You can modify these graphics as standalone images.

Download tout PSD
tout


Translating Images

If you are planning a multilingual website, you will most likely have images that are language-specific. Our recommended approach is to create two folders in assets, say "en" for English and "fr" for French. Within each of these folders, place all the images for both of the sites, maintaining the same file names for both.

Now, to render the correct path when the page loads, use the {$lang} variable:

<img src="{$assetbase}/images/{$lang}/tout.png">

On http://english.my-app.projects.fm, this will render <img src="http://assets.newspark.ca/681/images/en/tout.png">


CSS

Included in the Media Community templates are four CSS files: global.css, reset.css, base.css and lightwindow.css

StylesheetDescription
global.cssThis stylesheet calls the other three CSS files. It is called by our cssloader in the header of application.
layout.cssThis stylesheet contains a standard browser CSS reset.
base.cssThis stylesheet contains all the layout styles for the boxes.
design.cssThis stylesheet holds all of the design styles, including links to the sprites.
comments.cssThis stylesheet holds all of the styles for comments.

Caution: While you are free to edit any of the CSS as much as you'd like, there are a few things that may be better left alone. Inside base.css, any style that appears before where the sprite included has to do with the overall structure of the site, the three different box sizes and the thumbnail layout. There probably won't be a need to change anything in here except the colours and thumbnail background image URL


Forms

When adding custom form fields you should use meta data. To use meta data, make sure the 'name' attribute of the form field has to be 'meta[varname]'. And to access the variable in a <fm:MediaList> use the variable {$$media_metadata.user.varname}

Registration

Adding custom meta data to the register form in the 'sub_form' template

Text input
<li class="label"><label for="meta_title">Title</label></li>
<li><input type="text" class="fmInput required" id="meta_title" name="meta[title]" title="Title"/></li>
Check box (commonly used for newsletter opt-ins)
<li class="label checkbox clearfix">
    <fm:Form_CheckBox name="meta[opt1]" formType="simple" class="left" id="opt1" />
    <label for="opt1"> I want this opt-in</label>
</li>
Select
<select name="meta[title]" class="fmSelect">
    <option value="Mr.">Mr.</option>
    <option value="Ms.">Ms.</option>
    <option value="Mrs.">Mrs.</option>
    <option value="Miss.">Miss.</option>
</select>

0 comments

Be the first to comment on Community Documentation.

Add a Comment

  • captcha