Installation And Configuration Of Tweet Product Search

1.) Install Files

Extract, all files into their respective directories from the archive for your version of Magento. You may download the extension at any time, by logging in into this site with the account created with us at checkout, and going to the Downloads section of this site at the top. Go to your Magento admin, and clear cache, then log out of the admin section and back in.

Tweet Product Search should now be installed. You can verify it's installed by seeing the settings in System->Configuration, on the left you should see a new section called Tweet Product Search, under that, click All Extension Options. If this page loads successfully with all the extension options, you have installed the extension!

2.) Setup

  • a. Twitter API Setup

    The first thing you must do, is configure the twitter API to connect to your twitter account. You must firstly have a twitter account to connect to. Once you have created a twitter account, go to https://dev.twitter.com/, and login. Once logged in to twitters developer site, go to My Applications and click the button that says Create New Application. Give your application a Name/Description/Website, and click the Create Your Twitter Application at the bottom of the page. Now when you goto My Applications in on the twitter developer site, you should see your newly created application. On the My Applications page, click on the link to your newly created application, with the title you entered. Once this page loads, click the link at the top of the page called OAuth Tool. Copy the Consumer key and Consumer secret values, and place them inside the extension API configuration in Magento Admin System->Config->Tweet Product Search->All Extension Options->Api Settings. Optional (ADVANCED): If you need to use a proxy server, or need to specify a cacert.pem file for connecting to the Twitter's API, you may also enter that information in the System->Config->Tweet Product Search->All Extension Options->Api Settings configuration settings. These configuration options should only be needed if you have issues connecting to the Twitter API at a later step in this installation process.

  • b. Cron Job Configuration

    First ensure that your Magento Cron is setup correctly. Go to your magento admin, and go to System->Config->Tweet Product Search->All Extension Options->Tweet Product Search Cron Options. Select how many tweet product searches you want to update at cron. Twitter has rate-limiting guidelines for use in their API, and setting this number to high, could mean that cron takes a long time to update all your searches. We suggest you set this to 5 or 10 searches, until your confident that the extension is setup and configured properly. Next, select how many tweets you would like to be updated to your tweet product searches every time your search is processed at cron. Selecting a larger number means that cron will take longer to process each search. Next, to keep the database of tweets clean, and keep your website with new data, you can optionally set a expiration date to delete all tweets older than a certain time during cron. Lastly, you may choose how long of a time must elapse before a tweet product search is updated with new tweet data. This setting will force Tweet Product Search to ignore searches that have been updated within the last 2 days as an example. If this is your first time using this extension, we suggest you disable this until your familiar with how this extension works.

  • c. Global Extension Configuration

    Go to your magento admin, and go to System->Config->Tweet Product Search->All Extension Options->Tweet Product Search Global Options. Ensure that the extension is Enabled Globally, if it's disabled, nothing in this extension will work! Provide a default search query, this can be a search like Magento or even a twitter #Magento hash tag. Please ensure that the search term you select has tweets for that search term that are newer than the Cron Job Configuration value for Tweet Expiration's in section 2.)b. We suggest you pick a popular search to start out, see Twitter Search to see what tweets are returned for different search terms. Pick a default block title. This title will be displayed on every product page as the title for the block. (OPTIONAL), If you enter blank, no block title will be displayed at all on the block. Pick a twitter result type, for getting started. We suggest you pick the Both option, if this is your first time using the extension. Pick a language for the tweets you wish to pull. We suggest you pick the All Languages option, if this is your first time using the extension.

  • d. Update Global Search Data With Tweets

    Before doing this, make sure you have completed steps 2.)a-2.)c., and the extension is globally enabled with a default search term. Go to your magento admin, and load Catalog->Tweet Product Search->Tweets For All Products. Once on this page, you should see a empty grid with no tweets in it. On the top right hand corner of the page, click the button labeled Run Tweet Product Search Cron Manually. What this will do is populate our global search with tweets, by calling the Twitter API. Once the cron has finished running, you should see a success or fail message about Cron being ran at the top of the screen. If Cron was updated successfully, reload the Catalog->Tweet Product Search->Tweets For All Products page, and you should now see Tweets for your global search showing up inside the grid! If you see tweets in the grid, your extension is properly setup and you may move on to the 3.) Configuration Section of this document to complete the setup of the extension.

    if you got a cron success message on the screen after running cron manually, but you still don't see any tweets in the grid

    Firstly, make sure that the filters at the top of each column in the grid are empty, so you can see every tweet. Open /var/log/system.log log file. If you see the lines Tweet Product Search: Cron completed successfully! followed by Number of searches processed at cron: 1, then the cron run completed, but your 2.)c. default search term may not have any tweets returned from the twitter API. Additionally, if the last line says Number of expired tweets deleted at cron: has a value larger than 0, it may be that the tweets are too old, and the Tweet Product Search extension is deleting all the tweets it got from the Twitter API. If this is the case, see the 2.)b. Cron Job Configuration about the tweet expiration, and set the expiration time for the tweets to a larger number.

    If you got a cron fail message on the screen after running cron manually

    It could be for a few reasons. Firstly, ensure that you followed the Twitter API configuration from 2.)a., and all the Twitter API configuration values are entered correctly. If your sure you have entered the Twitter API information information about your application correctly and that still did not fix the problem, then go to /var/log/system.log and open it. If you search and find the line Tweet Product Search: Cron terminated due to a invalid twitter search API response, inside of system.log, then open up /var/log/exception.log and search for Twitter Product Search Cron:. If the extension had a problem connecting to the twitter API for some reason, you will find that line somewhere with more details about the error. If the error is related to SSL, try adding the ca.cert file described in the 2.)a. Twitter API Setup , if it's not connecting to the twitter API at all, it might be because you have a firewall running, and need to define a proxy server in the 2.)a. Twitter API Setup. If both of these options fail to resolve the twitter connectivity issue, then contact us with the pasted contents of your system.log and exception.log, for Tweet Product Search, and we will try to figure out the issue.

3.) Configuration

Before going through this section, first make sure that you fully completed parts 1 and 2, and you see tweets appearing in the Tweet Product Search admin page, Catalog->Tweet Product Search->Tweets For All Products.

  • a. Product Block

    Block System Configuration

    Go to your admin section System->Config->Tweet Product Search->All Extension Options->Tweet Product Search Block Settings. These are the block options you have to customize the type of search data that is displayed in the block by default. The most important setting in this section, is the Enable/Disable the Display of the Product Block Globally. setting. If the block is disabled, you will never see the block displayed on any product pages. Default Number of Tweets to Display in Block:, is exactly what you would think it is, it's how many tweets are displayed in the product block by default on every product. Enable/Disable Tweet Author's Profile Image on Each Tweet's Display in Block:, is a setting to disable/enable the profile image of each tweet displayed in the block globally. If you disable this, no profile images for the users will be displayed in the block. Tweet Product Search does not store the images locally, and so the images will come from twitter on page load, if you enable this option. Enable/Disable Tweet Timestamps for Block: are exactly that what it sounds like, if you enable this, the product block will display timestamps about the tweets inside the block. ie- "Sent 5 minutes ago" for each tweet. If this is a feature you want, and you have block caching enabled, then these times could get out of sync, and only be updated during Tweet Product Search's Cron Run or when cache is cleared. Enable/Disable Tweet User Url on Each Tweet's Display for Block: allows you to enable/disable the external link to the twitter user's page, that's displayed inside the block. Once you have configured the global Tweet Product Search block settings, clear your cache.

    Block Front End Configuration

    Once you have completed the block system configuration and cleared your cache, you may navigate to a product page on your Magento site. If everything has been configured correctly, you should see tweets showing up on the product page that are for your global search you configured in 2.)c.) , in a block on the right.

    If The Block Does Not display Where You Want It

    Chances are, the product block does not display exactly where you want it on the product page. That means, you will have to modify where the block is displayed on the product page. To accomplish this open app/design/[your_theme_name]/default/layout/local.xml layout, and modify it as you see fit. We have provided a complete local.xml file, this will move the Tweet Product Block from the reference=right to the reference=head section of the layout. Please note that in order for the product block to work, it must be a product page you insert it into on your new layout.

    If The Block Does Not Display At All

    If this is the case, the most likely situation is that your layout does not have the reference=right in the product-view layout. If this is the case, then see our example local.xml file, and change the layout references from reference=head to the proper reference for layout your using.

  • b. Setup New Tweet Product Search

    Inside the Magento admin, go to Catalog->Tweet Product Search->All Tweet Product Searches. You should see a grid with all the products on your Magento site. The settings on this page are product attributes associated with every product for Tweet Product Search Extension. The settings defined here, will override the default block settings you configured in the Block System Configuration of 3.)a. for each product. To enable product specific search on any product, you enable the search for the product you want, give it a twitter search term and click the update button on the right side of the row associated with the product you want to enable. We suggest you enable one or two products, and then click Run Tweet Product Search Cron Manually to update the new product searches with tweet data. Once you have ran the cron job manually, navigate to the customer-product-page for the product you just added. You should now see tweets displaying in the product block from your search term you defined.

    If You Do Not See Tweets From the Search Term You Defined

    First double check your cron settings in System->Config->Tweet Product Search->All Extension Options->Tweet Product Search Cron Options is set to update at least as many products as you enabled searches for. In other words, if you enabled 5 products, ensure that this setting will update at least 5 searches at cron. If that does not solve the issue, then double check the admin page Catalog->Tweet Product Search->All Tweet Product Searches by refreshing the page, to ensure the Tweet Product Search on that product is enabled.

  • c. Product Widget Configuration

    This section requires that you have enabled at least one product search in 3.)b to work as intended. If you do not have any product searches enabled, the widget will display the default search term's tweets instead of a products tweets!

    Widget System Configuration

    Go to your admin section System->Config->Tweet Product Search->All Extension Options->Tweet Product Search Widget Settings. The widget system configuration is very similar to the block system configuration 3.)a. You must enable the Default Number of Tweets to Display by Default in Every Widget: setting in this configuration for the widget to be displayed anywhere on your site. Default Number of Tweets to Display by Default in Every Widget: This is just how many tweets should be displayed by default in each widget. When creating the widget you may specify a different number. Default Enable/Disable Product Link Display in the Widget: This setting just allows you to enable/disable a link on the widget that links back to the product search for which the tweets are being displayed. Enable/Disable Display of Tweet Authors profile Image in the Widget: Enable/Disable display of the author profile image. NOTE: if you enable this, the images will be pulled from twitter, and not stored locally. Enable/Disable Tweet Timestamps in the Widget: Should we displays timestamps for each tweet inside the widget? Enable/Disable Tweet User Url on Each Tweet's Display in the Widget: Should we display the tiwtter user URL on the widget? The only difference between the widget settings and the block settings you already configured is the widget settings allows you to optionally add a link to the referring product to the widget display.

    Put A Widget In a CMS Page

    Once you are satisfied with the product widget configuration, in the Magento admin, navigate to Cms->Pages, and open a page you wish to add the Tweet Product Search widget to. Once inside the page editor, click on the content tab on the left. Click the Insert Widget button at the top of this page, and pick the Tweet Product Search Widget type from the drop down. Once selected, it should bring up a series of widget options at the bottom of this page. Inside the Widget Options you will be presented with a series of Tweet Product Search options for displaying your widget. First, select a product you enabled in section 3.b. If the product product you select here is not enabled, it will display the default search tweets. Now select how many tweets you want displayed in the widget, and optionally the widget title and product link display for this widget. Once finished, click "Insert Widget" button on the top right. This will insert the widget code into the CMS page. Save the CMS page, and clear your cache. Then navigate to the CMS page you just created on the frontend, and you should now see the Tweet Product Search Widget displaying tweets related to the product you selected for the widget display.

    Widget Instance Creation

    Navigate to Cms->Widgets section. Click the Add New Widget Instance button on the top left of the screen. Under the settings tab, select the type of Tweet Product Search from the drop down menu, and then select your Design Package Theme, then click Continue at the bottom of the screen. Once you have clicked continue, you should be presented with two tabs on the left. Fill out the required information for the frontend properties, then navigate to the Widget Options. Inside the Widget Options you will be presented with a series of Tweet Product Search options for displaying your widget. First, select a product you enabled in section 3.b. If the product product you select here is not enabled, it will display the default search tweets. Now select how many tweets you want displayed in the widget, and optionally the widget title and product link display for the widget.

  • d.Tweet Product Search More Tweets Page Options On Block Only Configuration

    This section requires that you have enabled at least one product search in 3.)b to work as intended. If you do not have any product searches enabled, theclick to see more tweets page will contain the default search term's tweets instead of a products tweets! Navigate to System->Config->Tweet Product Search->All Extension Options->Tweet Product Search More Tweets Page Options On Block Only All the more tweets page settings on here are for the Product Block only. These settings will never show up inside of the widget. This extension allows you to add a Click to See More tweets link at the bottom of every Product Block displayed. This is a separate page from the product page, and will contain only tweets related to your product on this page. The first option is to enable/disable the more tweets display on the tweet product block as a link to the page. If this is disabled, the more tweets page link will not show up anywhere! Number of Items to Display on "Click to See More" Tweet Page: specifies how many tweets you wish to display to the visitor on the Click to See More Tweets page. Enable/Disable Display of Tweet Authors profile image on "Click to See More" Page: specifies whether to display the twitter profile image on the Click to See More Tweets page. Enable/Disable Tweet Timestamps on the More Tweets Page: specifies whether or not timestamps on the Click to See More Tweets page are enabled. Enable/Disable Tweet User Url on Each Tweet's Display on the More Tweets Page: specifies whether or not to add links back to the twitter profile.

  • e. Cache Configuration

    This extension makes use of block caching. Once your satisfied with how the extension is working, you may optionally turn on the Tweet Product Search block cache. This will cache the product block, the widget, and the more tweets page. The one downfall to turning this on, is the timestamps on tweets displayed to the user may not be accurate.

4.) Usage

  • a. Setup More Product Searches, And Wait For Cron To Run

    At this point you should be familiar with how this extension works to start using this extension how it's intended-- With lots of product searches. Firstly, we suggest you go back to Catalog->Tweet Product Search->All Tweet Product Searches and add some new search terms for each of your products. We then suggest you go back to System->Config->Tweet Product Search->All Extension Options->Tweet Product Search Cron Options and increase the number of searches to process at cron to some number comparable to the number of Tweet Product Searches you plan to have on your Magento store. Please bear in mind, that increasing the number of product searches, or the number of tweets to store, will make the cron job take longer to complete. Once you have done this, wait for cron to run. After your certain Cron.php has been ran on your site, you should see the updated tweet data on the product pages and widgets you have set to display data from the product searches you just added. Congratulations, your extension is fully working at this point!

  • b. Tweets For All Products Admin Page

    Navigate to Catalog->Tweet Product Search->Tweets For All Products. In a earlier part of this setup, we went here to check to see if tweets were being added to the database. Now we want to make use of the functionality of this page.

    Ban and Unban

    Tweet Product Search extension has a ban list built into the extension. What this allows you to do, is select any tweets you wish, and ban the user associated with the tweets from ever displaying on the site to customers. You may do this by selecting the tweet's for the users you wish by checking the checkbox on the left. You then select the Ban or Unban option from the actions just above the gird on the right, and click submit.

    Delete Tweets

    From this page, you may select tweets by checking the checkbox on the left of each tweet, and delete them from Magento by selecting the action to delete tweets at the top of the gird and to the right, and then click submit. Since were deleting the tweets, and not banning the users, it's possible that the same tweets might get re-updated at the next cron run.

    Export To CSV or Excel Format

    You may export your tweet data to CSV or Excel format. You may do this by selecting the Export to: options just above the grid displayed. By default this will export all of your tweet data. If you have a lot of tweets, we highly suggest you first submit this form, so that it does not export all of your tweets, as that can take a long time depending on how many tweets you have in the system!


5.) View Customization

  • a. CSS Styling & Icon Change

    Navigate to skin/frontend/base/default/tweetproductsearch/ And copy the contents of that folder too skin/frontend/default/default/tweetproductsearch/, create the directory tweetproductsearch if it does not already exist. If the directory does already exist, use caution, as someone else might of made CSS changes, and so you will be overwriting the changes made. Now you may edit the CSS file for tweet product search, by editing your new files in skin/frontend/default/default/tweetproductsearch/css/tweetproductsearch.css. If you wish to change or edit the icon for tweet product search, you may do so by editing skin/frontend/default/default/tweetproductsearch/images/i_block_tweets.gif. If you wish to remove the icon entirely or make the image a completely different size, you can do this in the tweetproductsearch.css Lastly, once finished making the changes to the CSS/image, clear your cache.

  • b. Template Changes

    Navigate to app/design/frontend/base/default/template/tweetproductsearch, in this directory are the Tweet Product Search templates. There is one template for each type of block:

    tweetproductblock.phtml

    This is the template for the product block.

    tweetproductwidget.phtml

    This is the template file for the widget.

    tweetproductpage.phtml

    This is the template for the more tweets page.

    Copy the template file(s) you wish to make changes to, to app/design/frontend/default/default/template/tweetproductsearch/

    Once you have copied the template file you would like to that directory, you may now edit the template to suit your needs. Lastly, once finished making the changes to the template(s) your editing, clear your cache.