adammoses-github / mmm-tweetsbytimelineorlist

A module for the Magic Mirror to display tweets from a user's timeline or list.

Module: Tweets By Timeline Or List

The MMM-TweetsByTimelineOrList module is a module designed to display tweets from a user's home timeline or from a list. The tweets show can be configured in a variety of ways and are shown in a slideshow like fashion, showing just a few and then rotating into the next set.

Example:

Dependencies / Requirements

This module requires the use of the twitter and bad-words packages for node.js. To install them, please run:

npm install twitter
npm install bad-words

from the MMM-TweetsByTimelineOrList module directory inside your Magic Mirror installation directory.

This module also requires Twitter access tokens and keys. For more information on acquiring these please visit https://dev.twitter.com/oauth/overview/application-owner-access-tokens.

Operation

This module displays a number of tweets at time in a row by row fashion with the tweet's full username and age of the tweet also being display. Tweets are set in alternating gray-level colors to distinguish them.

Tweets that are displayed have all links, media, quotes, and emojis stripped from them. This is done to simplify the display to simple text only.

The choice of displayed tweets can either be a user's timeline or a user's list. By default the timeline will show the timeline for the user for whom the API access keys will generated. Setting the username in the config will confirm the user.

There are many configuration options controlling which, how many, how often, etc, tweets are shown and used, so please read through those that are available.

Using the module

To use this module, add it to the modules array in the config/config.js file:

modules: [
	{
		module: 'MMM-TweetsByTimelineOrList',
		position: 'bottom_left',
		config: {
		// visit the url below for the twitter keys/tokens
		// https://dev.twitter.com/oauth/overview/application-owner-access-tokens
			consumer_key: 'FILL IN',
			consumer_secret: 'FILL IN',
			access_token_key: 'FILL IN',
			access_token_secret: 'FILL IN',
		// set the username and either timeline or listname
	        screenName: 'someusername',
	        listToShow: 'TIMELINE',
		}
	}	
]

Configuration options

The following properties can be configured:

Option	Description
consumer_key	Used by the Twitter package in order to collect the trends. For more visit https://dev.twitter.com/oauth/overview/application-owner-access-tokens. This value is REQUIRED
consumer_secret	Used by the Twitter package in order to collect the trends. For more visit https://dev.twitter.com/oauth/overview/application-owner-access-tokens. This value is REQUIRED
access_token_key	Used by the Twitter package in order to collect the trends. For more visit https://dev.twitter.com/oauth/overview/application-owner-access-tokens. This value is REQUIRED
access_token_secret	Used by the Twitter package in order to collect the trends. For more visit https://dev.twitter.com/oauth/overview/application-owner-access-tokens. This value is REQUIRED
screenName	Should be set to either a) your username if you want to show your TIMELINE or one of your user lists, or b) another username if accessing one of their user lists. This value is REQUIRED
listToShow	Should be set to either a) 'TIMELINE', if you want to show your timeline, or b) the stub name of one of your user lists or another user's user lists. This is configured tightly with the above screenName configuratoin option so set accordingly. This value is REQUIRED
tweetsToShowAtATime	The number of tweets to display on screen at a time. Example: 7 Default value: 5 This value is OPTIONAL
onScreenRefreshRate	The delay between changing the on-screen displayed tweets for the next set. In milliseconds. Example: 15000 Default value: 25000 This value is OPTIONAL
tweetUpdateRefreshRate	How often to fetch a new set of tweets. In milliseconds. Should not be done more than once every few minutes since the on-screen refresh will delay the need for constant new tweets. Example: 180000 Default value: 300000 (5 minutes) This value is OPTIONAL
moduleWidth	The width of the module specified via CSS widths, usually in 'px' pixels. Example: '250px' Default value: '300px' This value is OPTIONAL
animationSpeed	The animation speed sent to updateDom to fade in between new sets of on-screen tweets. Example: 4500 Default value: 3000 This value is OPTIONAL
showHeader	Boolean that sets if a header should be shown or not. When enabled show's username and use of timeline or list name. Example: true Default value: false This value is OPTIONAL
totalTweetsPerUpdate	The number of tweets max to get in any given update. Does equal the number of tweets that will finally qualify for displaying, so should be larger. Should not be changed in most cases. Example: 100 Default value: 1500 This value is OPTIONAL
excludeTweetsWithQuotes	Boolean the determines if tweets that have another quote in them should excluded from display. Example: false Default value: true This value is OPTIONAL
excludeRetweets	Boolean the determines if tweets that are re-tweeted should be excluded from display. Example: false Default value: true This value is OPTIONAL
excludeMediaTweets	Boolean the determines if tweets that have media (i.e. image or video) should excluded from display. Example: true Default value: false This value is OPTIONAL
excludeLinkTweets	Boolean the determines if tweets that have a link should excluded from display. Example: true Default value: false This value is OPTIONAL
excludeTweetLengthLessThan	Tweets with less than this number of characters will be excluded from display. Example: 20 Default value: 16 This value is OPTIONAL
excludeTweetsWithoutText	This is an array of strings that are checked against a given tweet. If a tweet includes any of the strings in the array than it would be included, otherwise it is excluded. If an empty array is specified than no checking of this kind will occur at all. NOTE: This compairison is made case insensitive. Example: [ 'elephants', 'deer' ] Default value: [ ] This value is OPTIONAL
maxTweetsPerUser	Limits the number of tweets any one user can have dispalyed, preventing one user from taking up many many of the displayed tweets. If set to zero, no limiting will occur at all. Example: 4 Default value: 1 This value is OPTIONAL
maxTweetAgeMins	Tweets greater than this value specified in minutes will be excluded from display. If set to zero no age limit will be set. Example: 120 Default value: 360 (6 hours) This value is OPTIONAL
allowSpecialCharacters	Determines if non-alphanumerics will be allowed in the display string or not. If set to true Unicode characters that are outside regular English will be allowed in, characters that feature an Umlaute over them for instance. These are typically found in non-English languages, like German. This also may allow in unwanted characters however, like those that are featured as part of an emoji. The code currently does not discriminate here. For most English users this value should remain false. Example: true Default value: false This value is OPTIONAL
displayColors	A list of strings, where each string is a color in the '#RGB' format. The displayed tweets will be displayed in order of the colors listed, cycling through them as needed based on the number of tweets shown. Example: [ '#e00', '#0e0', '#00e'] Default value: [ '#888', '#aaa', ] (darker grey, lighter grey) This value is OPTIONAL
filterBadWords	Defaults to `false`. When set to `true`, objectionable words are replaced with asterisks for a more child-friendly display.