Social Media

imperia 10 provides a comfortable way to connect with and manage your Facebook and Twitter accounts. This is handled by imperia's social plug-in. The following chapter describes the processing instructions that you can use. For information on how to configure the social plug-in see Social Media in the administration documentation.

Invocation#

As a minimum, you need the following processing instructions in order to use the social media plug-in in a template:

<?imperia social 
  id: 101 
  channel: ralf.schneider.1654 
  method: post
  other parameters: ...
?>

  • social - defines the plug-in to be used (in this case “social”).

  • id - defines the ID of the instance. The ID has to be unique.

  • channel - defines the Facebook or Twitter user. The example above is with a Facebook user; with a Twitter account the instruction should be channel: @ImperiaAG.

  • method - defines the method to be

Processing Instruction with Facebook#

Mandatory Parameters#

id

This parameter defines the ID of the social plug-in instance. It is mandatory and has to be unique.

channel

Defines your Facebook username (e.g. ralf.schneider.1654). You can check your user name at Facebook -> Settings -> General -> Username.

method

Defines the method to be used. This could either be post or photo. For more information on both methods consult with Facebook's Documentation - post method and photo method.

Optional Parameters#

page

If you wish to post or upload a photo on a Facebook page, managed by you, provide the name of the corresponding page (e.g. “Imperia AG”). If it is defined the post will be added to imperia AG timeline and not to your user account.

trigger

Provide a meta field that has to return “1” or “0”, depending on whether a user wants to post the document's information on Facebook or not (e.g. via a checkbox).

Parameters Used with the “Post” Method#

This documentation provides only a brief overview of the available options. For more information refer to Facebook Graph API Documentation as a starting point.

message

Provide a meta field that will contain the actual message of the post. (see examples)

link

Provide a meta field that will contain a link to be posted. (see examples)

name

Provide a meta field that will contain a name for a “link” or “video” post. (see examples)

caption

Provide a meta field that will contain a caption for a “link” or “video” post. (see examples)

description

Provide a meta field that will contain a description for a “link” or “video” post. (see examples)

picture

Provide a meta field that will contain a preview picture for a “link” or “video” post. (see examples)

source

If you are using the post method, the source parameter should contain a URI to a Flash movie or a video file.

anotherParameter: expand:

The “expand” function should be used if some of the meta fields contain template variables (e.g. XX variables), so that the Hermes knows that it should expand their content before posting.

Parameters Used with the “Photo” Method#

This documentation provides only a brief overview of the available options. For more information refer to Facebook Graph API Documentation as a starting point.

message

Provide a meta field that will contain the actual message of the post. (see examples)

source

If you are using the photo method, the source parameter is used to upload an image onto Facebook. You should provide a relative to the system.conf DOCUMENT-ROOT variable path.

album_id

Provide either the album id or your Facebook user account (e.g. ralf.schneider.1654).

Important

The album you are uploading to must have been created by this application, you cannot use an album created in Facebook's user interface.

album_name

This parameter will create a Facebook album with the corresponding name. If such an album already exists, the application will upload the relevant image into the existing album.

Important

The album you are uploading to must have been created by this application, you cannot use an album created in Facebook's user interface.

album_description

Provide a description for your Facebook album.

Important

The album you are uploading to must have been created by this application, you cannot use an album created in Facebook's user interface.

no_story

If this parameter is set, the upload of an image will not be posted on your Timeline.

anotherParameter: expand:

The “expand” function should be used if some of the input fields contain template variables (e.g. XX variables), so that the Hermes knows that it should expand their content before posting.

Examples#

This subchapter contains some examples to better illustrate how these processing instructions work.

Note

All the examples are with a flex module, hence, the input fields contain a Flex_INDEX and Flex_ID.

A simple message post (the code is wrapped for representation purposes):

<label class="helptext">{%__('Facebook')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_facebook" 
type="checkbox" /></span> <br />
Message:<textarea name="IMPERIA:fb_teaser_101" class="autosize" rows="1"
    placeholder="{% __('Message') %}"></textarea><br/>

<?imperia social
  id: 101
  channel: Your Facebook User Account
  method: post
  page: Your Facebook Page Name
  message: fb_teaser_101_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  trigger: social_networks_facebook
?>

A link post with a preview picture and details (the code is wrapped for representation purposes):

Link:<textarea name="IMPERIA:fb_link_102" class="autosize" rows="1"
    placeholder="{% __('The link to post.') %}"></textarea><br/>
Link Name: <input name="IMPERIA:fb_name_102" value="Some name"><br/>
Link Description: <input name="IMPERIA:fb_descr_102" value="Some description"><br/>
Link Caption: <input name="IMPERIA:fb_capt_102" value="Some caption"><br/>
Link Preview: <img src="IMPERIA:fb_lp_102" width="155"></img>
<input name="fb_pic_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->" type="hidden" 
value="<{%'!'%}--SYSTEM_CONF:ABS-DOC-ROOT-->
        <{%'!'%}--XX-fb_lp_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->-->">

<?imperia social
  id: 102
  channel: Your Facebook User Account
  method: post
  page: Your Facebook Page Name
  link: fb_link_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  name: fb_name_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  description: fb_descr_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  caption: fb_capt_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  picture: expand:fb_pic_102_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

A video post with image preview and details (the code is wrapped for representation purposes):

Link:<textarea name="IMPERIA:fb_link_103" class="autosize" rows="1"
    placeholder="https://www.youtube.com/watch?v=pni1rlrgnZw"></textarea><br/>
Message:<textarea name="IMPERIA:fb_msg_103" class="autosize" rows="1"
    placeholder="{% __('Message') %}"></textarea><br/>
Link Name: <input name="IMPERIA:fb_name_103" value="Some name"><br/>
Link Description: <input name="IMPERIA:fb_descr_103" value="Some description"><br/>
Link Caption: <input name="IMPERIA:fb_capt_103" value="Some caption"><br/>
Source: <input name="IMPERIA:fb_src_103" type="text" 
        value="http://www.youtube.com/v/pni1rlrgnZw"><br/>
Preview Picture: <input name="IMPERIA:fb_pic_103" type="text" 
        value="http://path/to/some/img">

<?imperia social
  id: 103
  channel: Your Facebook User Account
  method: post
  page: Your Facebook Page Name
  message: fb_msg_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  link: fb_link_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  name: fb_name_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  description: fb_descr_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  caption: fb_capt_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  source: fb_src_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  picture: fb_pic_103_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Upload an image with privacy settings. Defining the privacy of a post or a picture upload is not possible if you are posting on a Facebook page (the code is wrapped for representation purposes):

Message:<textarea name="IMPERIA:fb_msg_104" class="autosize" rows="1"
    placeholder="{% __('Message') %}"></textarea><br/>
Picture: <input name="IMPERIA:fb_pic_104" type="text" 
value="http://path/to/some/img"><br/>
Privacy: <select name="fb_priv_104_<!--FLEX_INDEX-->_<!--FLEX_ID-->" type="text">
    <option value='{"value":"SELF"}'>Me Only</option>
    <option value='{"value":"ALL_FRIENDS"}'>Friends</option>
    <option value='{"value":"EVERYONE"}'>Everyone</option>
</select>

<?imperia social
  id: 104
  channel: Your Facebook User Account
  method: post
  message: fb_msg_104_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  picture: fb_pic_104_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  privacy: fb_priv_104_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Upload an image to a given album:

Message:<textarea name="IMPERIA:fb_msg_105" class="autosize" rows="1"
    placeholder="{% __('Upload picture test') %}"></textarea><br/>
Album Name:<textarea name="IMPERIA:fb_alb_name_105" class="autosize" rows="1"
    placeholder="{% __('Album name') %}"></textarea><br/>
Album Description:<textarea name="IMPERIA:fb_alb_msg_105" class="autosize" rows="1"
    placeholder="{% __('Album description') %}"></textarea><br/>
Picture: <img src="IMPERIA:fb_pic_105" width="480"></img>

<?imperia social
  id: 105
  channel: Your Facebook User Account
  method: photo
  page: Your Facebook Page Name
  album_id: Your Facebook User Account
  album_name: fb_alb_name_105_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  album_message: fb_alb_msg_105_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  message: fb_msg_105_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  source: fb_pic_105_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Processing Instructions with Twitter#

Mandatory Parameters#

id

This parameter defines the ID of the social plug-in instance.

channel

Defines your Twitter account name.

method

Defines the method to be used. The following methods are available:

  • update - a simple tweet.

  • update_with_media - a tweet with an image.

  • update_profile_background_image - changes your Twitter account background image.

  • update_profile_image - changes your Twitter account profile image.

  • update_profile_banner - changes your Twitter account header image.

  • update_profile_colors - changes your Twitter profile page color scheme.

More information on the individual methods see in Methods.

Optional Parameters#

trigger

Provide a meta field that has to return “1” or “0”, depending on whether a user wants to tweet the document's information on Twitter or not (e.g. via a checkbox). This parameter is optional

Other Parameters#

This documentation provides only a brief overview of the available options. For more information refer to Twitter REST API Documentation as a starting point.

status

Provide a meta field that will contain the actual message of the tweet. (see examples)

media[]_upload:

Provide a meta field that will contain an image path (relative to the system.conf DOCUMENT-ROOT variable path) to be tweeted (see examples). You can also use Twitter API's parameter media[], but in this case you should provide the raw data of the image.

image_upload

Provide a meta field that will contain an image path (relative to the system.conf DOCUMENT-ROOT variable path) that will change your Twitter account background image or your profile image (see examples). You can also use Twitter API's parameter image, but in this case you should provide the raw, base64 encoded data of the image.

banner_upload

Provide a meta field that will contain an image path (relative to the system.conf DOCUMENT-ROOT variable path) that will change your the Twitter account header image. You can also use Twitter API's parameter banner, but in this case you should provide the raw data of the image.

profile_background_color

Provide a meta filed that will contain a hex color value for your profile background color (e.g. 3D3D3D).

profile_sidebar_border_color

Provide a meta filed that will contain a hex color value for your profile sidebar's border color (e.g. 3D3D3D).

profile_sidebar_fill_color

Provide a meta filed that will contain a hex color value for your profile sidebar's background color (e.g. 3D3D3D).

profile_text_color

Provide a meta filed that will contain a hex color value for your profile text color (e.g. 000000).

lat

The latitude of the location this tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter.

long

The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding lat parameter.

Some of the parameter in this documentation do not correspond to the parameters provided by Twitter, because imperia allows you to provide an image path (relative to the system.conf DOCUMENT-ROOT variable path) and then manipulates that image, so that it meets Twitter's requirements for image upload. You may also use the Twitter API's parameters, but in that case you have to provide Base64-encoded or raw image data. Here is a list of the parameters (mapping) in question:

Imperia Twitter
media[]_upload media[]
image_upload image with base64 encoding
image_upload image
banner_upload banner

Methods#

The following list is a brief overview of the methods and the available to them parameters. For more information refer to Twitter REST API Documentation.

update

Updates your user's status (tweeting).

Available parameters for this method are: status, trigger, lat and long.

update_with_media

Updates your user's status and attaches media for upload.

Available parameters for this method are: status, trigger, lat and long.

update_profile_background_image

Updates your user's profile background image. This method can also be used to enable or disable the profile background image.

Available parameters for this method are: trigger, image_upload and use.

update_profile_image

Updates your user's profile image.

Note

The method expects raw multipart data, not a URL to an image.

Available parameters for this method are: trigger and image_upload

update_profile_banner

Uploads your user's profile header image.

Available parameters for this method are: trigger and banner_upload

update_profile_colors

Sets one or more hex values that control the color scheme of your user's profile page.

Available parameters for this method are: trigger, profile_background_color, profile_link_color, profile_sidebar_border_color, profile_sidebar_fill_color and profile_text_color.

Examples#

This subchapter contains some examples to better illustrate how these processing instructions work.

A simple tweet:

<label class="helptext">{%__('Twitter')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_twitter" 
        type="checkbox" /></span> <br />
Message:<textarea name="IMPERIA:tw_teaser_1" class="autosize" rows="1" 
        placeholder="{% __('Message') %}"></textarea><br/>
<?imperia social
  id: 1
  channel: @YourTwitterAccount
  method: update
  status: tw_teaser_1_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  trigger: social_networks_twitter
?>

A tweet with an image:

<label class="helptext">{%__('Twitter')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_twitter" 
        type="checkbox" /></span> <br />
Title:<input name="IMPERIA:tw_title_2" value="Cologne Cathedral"><br/>
Image: <img src="IMPERIA:tw_img_2" width="512"></img><br/>
Lat:<input name="IMPERIA:tw_lat_2" value="50.941357"><br/>
Long:<input name="IMPERIA:tw_long_2" value="6.958307"><br/>
<?imperia social
  id: 2
  channel: @YourTwitterAccount
  method: update_with_media
  trigger: social_networks_twitter
  status: tw_title_2_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  media[]_upload: tw_img_2_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  lat: tw_lat_2_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  long: tw_long_2_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Customizing your Twitter profile page's skin

The next four examples are used to cutomize how your Twitter profile page looks. You may use them separately or combine them to meet your desires.

Change your profile background image:

<label class="helptext">{%__('Twitter')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_twitter" 
      type="checkbox" /></span> <br />
Image: <img src="IMPERIA:tw_img_3"></img><br/>
Use: <input name="IMPERIA:tw_use_3" value="1"><br/>
<?imperia social
  id: 3
  channel: @YourTwitterAccount
  method: update_profile_background_image
  trigger: social_networks_twitter
  image_upload: tw_img_3_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  use: tw_use_3_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Change your profile image:

<label class="helptext">{%__('Twitter')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_twitter" 
        type="checkbox" /></span> <br />
Twitter Profile Image:<br/>
Image: <img src="IMPERIA:tw_img_4" width="128"></img><br/>
<?imperia social
  id: 4
  channel: @YourTwitterAccount
  method: update_profile_image
  trigger: social_networks_twitter
  image_upload: tw_img_4_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Change your profile header image:

<label class="helptext">{%__('Twitter')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_twitter" 
    type="checkbox" /></span> <br />
Image<img src="IMPERIA:tw_profile_banner_5" width="400"></img><br/>
<?imperia social
  id: 5
  channel: @YourTwitterAccount
  method: update_profile_banner
  trigger: social_networks_twitter
  banner_upload: tw_profile_banner_5_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>

Change your twitter profile page color scheme (code is wrapped for representation purposes):

<label class="helptext">{%__('Twitter')%}</label>
<span class="social_checkbox"><input name="IMPERIA:social_networks_twitter"
     type="checkbox" /></span> <br />
Profile Background Color(C0DEED):
    <input name="IMPERIA:tw_background_color_6" value="FF0020"><br/>
Profile Link Color(0084B4):
    <input name="IMPERIA:tw_link_color_6" value="803010"><br/>
Profile Sidebar Border Color:
    <input name="IMPERIA:tw_sidebar_border_color_6" value="DF6060"><br/>
Profile Sidebar Fill Color:
    <input name="IMPERIA:tw_sidebar_fill_color_6" value="5F5040"><br/>
Profile Text Color:
    <input name="IMPERIA:tw_text_color_6" value="EEA0A0"><br/>
<?imperia social
  id: 6
  channel: @YourTwitterAccount
  method: update_profile_colors
  trigger: social_networks_twitter
  profile_background_color: tw_background_color_6_
                            <!--FLEX_INDEX-->_<!--FLEX_ID-->
  profile_link_color: tw_link_color_6_<!--FLEX_INDEX-->_<!--FLEX_ID-->
  profile_sidebar_border_color: tw_sidebar_border_color_6_
                                <!--FLEX_INDEX-->_<!--FLEX_ID-->
  profile_sidebar_fill_color: tw_sidebar_fill_color_6_
                            <!--FLEX_INDEX-->_<!--FLEX_ID-->
  profile_text_color: tw_text_color_6_<!--FLEX_INDEX-->_<!--FLEX_ID-->
?>