search

AdamMoses-GitHub / MMM-TweetsByTimelineOrList

A module for the Magic Mirror to display tweets from a user's timeline or list.
MIT License
14 stars 5 forks source link
display-tweets list magicmirror timeline tweets twitter

readme

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:

Full

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.