diff --git a/docs/Introduction_to_IFTTT_Applets.rst b/docs/Introduction_to_IFTTT_Applets.rst new file mode 100644 index 0000000..b010b15 --- /dev/null +++ b/docs/Introduction_to_IFTTT_Applets.rst @@ -0,0 +1,16 @@ +Introduction to IFTTT Applets +============================= + +What is an Applet? +------------------ + +An Applet connects two or more apps or devices together. +It enables you to do something that those apps or devices couldn't do on their own. + +Applets are composed of triggers and actions. +Triggers tell an Applet to start, and actions are the end result of an Applet run. +To use an Applet, you'll need a `free IFTTT account `_. +Then you need to connect your apps and devices to IFTTT. + +Follow this `link `_ +for easy creation of an IFTTT Applet. diff --git a/docs/Trigger_IFTTT_Action.rst b/docs/Trigger_IFTTT_Action.rst index 7c15ebf..b3d28ad 100644 --- a/docs/Trigger_IFTTT_Action.rst +++ b/docs/Trigger_IFTTT_Action.rst @@ -1,152 +1,34 @@ -Trigger IFTTT Action -================================= +Trigger IFTTT" Content Rule Action +================================== -In this section we will discuss what are `IFTTT actions` and -how to configure and use them. +`Plone Content Rules `_ +are a powerful mechanism to automate dealing with content using `conditions` and `actions`. +It will automatically perform an action when certain events (known as “triggers”) takes place under desired condition. -Eagle View ---------------- +**Collective.ifttt** contains a new content rule action, `IFTTT Trigger`, +that posts an event to the IFTTT web service when a content rule's conditions are satisfied. -IFTTT actions are a powerful mechanism to automate dealing with -content and 3rd party web services. -They are created and configured using Plone Content Rule. +Content rules with the `IFTTT Trigger` is used to implement the IFTTT triggers, +which is a powerful mechanism to automate dealing with 3rd party web services +that collective.ifttt provides (Content Trigger, Event Trigger, etc.) -There are several steps, that follow one another: - -**Define the IFTTT action configuration** - -1. create and name a new rule, specifying what triggers it to be executed -2. then narrow it down, by using conditions, to execute only on the content items you want -3. and configure the IFTTT action that should be taken - -But by default it will not execute yet; there is one more step to take: - -Apply it to a portion of your site. Or to the whole site, if you so choose to. -You can also apply different/multiple IFTTT actions onto different/multiple -part of your site. - -Triggers, conditions, actions ------------------------------ - -A general overview what makes up a IFTTT actions, -some sample use cases, and who can set up and use content rules. - -**What is a `IFTTT action`?** - -A `IFTTT action` will automatically perform -an action when certain events (known as “triggers”) take place. - -You can set up an `IFTTT action` to email (the action) -whenever certain (or any) content is modified to a specific folder (the trigger). - -**Who can set up and use IFTTT actions?** - -Site Manager permissions are required to in order to set up and apply IFTTT actions. - -**What are the triggers and conditions that come with Plone 5.0?** - -The following general **triggers** are available by default: - -- Comment added -- Comment removed -- Comment reply added -- Comment reply removed -- Object added to this container -- Object copied -- Object modified -- Object removed from this container -- User created -- User logged in -- User logged out -- User removed -- Workflow state changed - -These triggers can be made more specific by using conditions - -The following general **conditions** are available by default: - -- Content type: the type has to be one or more specific ones, like a Page or News Item -- File extension: do only for type .PDF, for instance -- Workflow state: only act on unpublished items, for instance -- Workflow transition: only act when an item is being published -- User’s Group: only act when one of the “Sports Team” members logs in -- User’s Role: only act when a Site Administrator logs in -- TALES expression: an advanced, programmable condition. +You can create your own custom IFTTT trigger event by combining the `IFTTT Trigger` content rule action with +your own conditions Creating and Defining Content Rules ----------------------------------- -IFTTT actions are configured inside content rules. -So before starting with IFTTT actions, content rules have to be defined. - -Creating a Rule -^^^^^^^^^^^^^^^ - -Content rules are created globally through the Plone Control Panel (“Site Setup” link) -and then selected from the Rules tab for the desired folder -(or at the Plone site root if you want the rule applied site-wide). - -In this example, -you’re going to create a content rule that will send an email any time a News item is modified. - -- Go to site setup - -.. image:: _static/images/Trigger_IFTTT_Action/site_setup.png - -- Select “Content Rules” in General tab. - -.. image:: _static/images/Trigger_IFTTT_Action/Content_Rules_on_site_setup.png - -- The first option, “Disable Globally”, allows you to disable ALL content rules. - This is the emergency brake, for when you have created rules that are not doing what you want. -- In the second section of the main page for Content Rules is where - any existing content rules will be listed. - There are also some checkboxes to filter them, which can be useful if there are many rules defined. - -.. image:: _static/images/Trigger_IFTTT_Action/add_content_rule.png - -If no content rules exist, the only option is an “Add content rule” button. Click that. - -An “Add Rule” form comes up. Enter a descriptive title – -for this example, use: “Send Email when any News item is Modified”. Enter a description if desired. - -For the “Triggering event” select “Object modified”. Leave “Enabled” checked, -and “Stop executing rules” and “Cascading rule” unchecked. +Following the instructions given on the Plone documentation `link `_. +Create a content rule as follows and assign it to a folder on your site (or at the site root): -.. image:: _static/images/Trigger_IFTTT_Action/configure_content_rule.png - -Click the “Save” button. -At this point, you have essentially created a “container” for the content rule. - -Next you’ll further define the trigger and actions for this rule. - -.. image:: _static/images/Trigger_IFTTT_Action/save_content_rule.png - - -Defining conditions and actions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After creating a content rule, -you need to actually define the specific conditions of the trigger and -actions that will occur based on those conditions. - -**For the condition:** - -- By default, “Content type” is selected and since you want a trigger only for News item, - click on the “Add” button. -- From the “Add Content Type Condition” page, select “News item” and click on “Save” - -.. image:: _static/images/Trigger_IFTTT_Action/configure_trigger.png - -**For the action:** - -- Select “IFTTT Trigger Action” from the drop down menu and click on the “Add” button. +- Triggering event: Object modified +- Condition: Content type equals News Item +- Action: Select “IFTTT Trigger” from the drop down menu and click on the “Add” button. .. image:: _static/images/Trigger_IFTTT_Action/select_action.png -- From the “Add IFTTT Trigger Action” page, fill out the form: -- For the “IFTTT applet name” enter: the IFTTT applet which you want to trigger. - For the given example, enter "send_email" +- From the “Add IFTTT Trigger” page, fill out the form: +- For the “IFTTT event name” enter: the IFTTT event which you want to trigger. - Choose the 3rd payload from available options (values of which will be dynamically fetched from the content which trigger this action) : @@ -157,78 +39,21 @@ actions that will occur based on those conditions. .. image:: _static/images/Trigger_IFTTT_Action/configure_action.png -Congratulations, you have created a working IFTTT Trigger Action content rule! - - Data sent to IFTTT applet ^^^^^^^^^^^^^^^^^^^^^^^^^ -In the data sent to IFTTT, following values will be dynamically included +In the data sent to IFTTT, following payload (values) will be dynamically included (for which content on the site this content rule triggers): - Title - absolute_url - Chosen 3rd Payload -In the next sections, -you’ll learn how easy it is to apply this content rule to any part (or all) -of your Plone site. - -Assigning a Content Rule ------------------------- - -Now that you’ve set up a content rule, how does it actually get used? - -At this point, you have successfully created a content rule. -However, this content rule isn’t actually in use until it has been assigned -and enabled on one or more folders. - -- Navigate to the folder where you want the content rule to be in effect. - This can be any folder on the Plone site or it can be for the entire Plone site (“Home”) - with the condition that, it only be triggered by configured content type - (in this case we have configured it to ``news item`` in earlier section). - So, in this example we’re going to the “News” folder. -- Click on the “Rules” tab. - From there you will see a drop down menu of possible content rules: - -.. image:: _static/images/Trigger_IFTTT_Action/rules_tab.png - -- Select the desired content rule (“Send Email…” in this example) and - click on the “Add” button. -- By default, the rule has now been applied to the current folder only as - indicated by the symbol in the “Enabled here” column indicates. - -.. image:: _static/images/Trigger_IFTTT_Action/select_content_rule.png - -There will be several buttons near the bottom. - -Tick the check box for the rule you want (“Send Email…”) -and then click on either “Apply to subfolders” button. - -Now this content rule will also apply to any subfolder that exist now or are created in the future. - -If you wish to have this rule apply to all the subfolders but not to the current folder -, then tick the check box next to the rule and click on the “Disable” button. - -Managing Multiple Rules ------------------------ - -For each rule, you can define if additional rules should be applied after it, -or if it is the end of the pipeline. - -Furthermore, you can configure if you want rules to be cascading or not. -The configuration is available in content rule configurations under General Tab of site setup. - -An example: the first ContentRule is triggered for a content item, -which is then moved to a folder. But, in this folder, another ContentRule is active, -which will operate on any new content item that gets moved into that folder. -Cascade means that yes, the second rule should be applied. - -Working example of IFTTT Action -------------------------------- +Working example of IFTTT Trigger +-------------------------------- -Now, that rules have been configured for "New folder". -So IFTTT actions will be triggered if any content on News is modified. +Now that following the `Plone Content Rule `_ +we can see `IFTTT Trigger` in action. For example, below we will create a new `news item` and further update it's content to trigger IFTTT ``send_email`` applet. diff --git a/docs/Using_Plone_RSS_Feeds_in_IFTTT_Applets.rst b/docs/Using_Plone_RSS_Feeds_in_IFTTT_Applets.rst new file mode 100644 index 0000000..6c5f975 --- /dev/null +++ b/docs/Using_Plone_RSS_Feeds_in_IFTTT_Applets.rst @@ -0,0 +1,59 @@ +Using Plone RSS Feeds in IFTTT Applets +====================================== + +To learn how to create an IFTTT applet using an +RSS feed, follow the demonstration below. + +This applet will add a new row +on Google Spreadsheet each time an RSS Feed get publishes. +However, one may teak this configuration based on user requirement. + +------------------- + +- Signup at `free IFTTT account `_. + +- Navigate to your Username in the upper right corner + +- Select **New Applet** from the dropdown menu + +- Click the blue 'this' text + +- Search ``rss`` in search box. And select ``RSS Feed`` + +.. image:: _static/images/plone_rss_applet/search_rss.png + +- Choose `New feed item` + +- Fill RSS feed url in the given space. And click `Create Trigger` + +.. image:: _static/images/plone_rss_applet/fill_rss_url.png + +- Click the blue 'that' text + +- Choose `Google Sheets` as Action Service + +.. image:: _static/images/plone_rss_applet/choose_google_sheets.png + +- Choose `Add row to spreadsheet` + +- Configure the form based on required tweaks and hit `Create Action` + +.. image:: _static/images/plone_rss_applet/configure_action.png + +- Click `Finish` + +.. image:: _static/images/plone_rss_applet/finish.png + +Hurrah!! We successfully created our IFTTT Applet. + +.. image:: _static/images/plone_rss_applet/successfull_creation.png + +Now Every time an RSS get publishes, it will automatically be added as a new row +to our Google Spreadsheet. + +.. image:: _static/images/plone_rss_applet/google_spreadsheet.png + + + + + diff --git a/docs/What_is_IFTTT.rst b/docs/What_is_IFTTT.rst new file mode 100644 index 0000000..cd8615c --- /dev/null +++ b/docs/What_is_IFTTT.rst @@ -0,0 +1,32 @@ +What is IFTTT? +============== + +`ifttt.com `_ - If This Then That, also known as IFTTT (pronounced /ɪft/) - +is a free web-based service to create chains of simple conditional statements, +called applets. These applets can +perform a configured action in response to a trigger. Triggers and actions are web services provided by +platforms such as Facebook, Pinterest, Youtube, Spotify - and now, Plone sites. + +Below are a few examples of IFTTT applets for better understanding: + + - If a video is liked on Youtube, then save the video details in Evernote + - If a profile picture gets changed on Facebook, then update the same profile picture on Twitter + - If I'm tagged in a photo on Facebook, then save it to my phone gallery + - If I receive an email about a new Twitter follower in my Gmail inbox, + then tweet the new follower a welcome message + - If NASA posts a new astronomy picture of the day, then add it to my screensaver gallery. + - Email me about Top Apps that have become FREE in the Apple App Store. + - Automatically unmute my Android phone when I get back home. + - Add a Spotify song from a liked YouTube Video. + +**collective.ifttt** is an addon which enables any Plone site to play in the +IFTTT ecosystem by allowing you to create IFTTT applets. + +Below are a few examples of using IFTTT with Plone sites. + + - If a news item is published, then tweet about it or post it on Facebook. + - If an event is published, then add it to my calendar. + - If new users sign up for an event, then add them to a Slack channel. + - If content changes, then record who edited it in a Google spreadsheet. + + diff --git a/docs/_static/images/Trigger_IFTTT_Action/IFTTT_trigger.png b/docs/_static/images/Trigger_IFTTT_Action/IFTTT_trigger.png index dfea2a0..2288182 100644 Binary files a/docs/_static/images/Trigger_IFTTT_Action/IFTTT_trigger.png and b/docs/_static/images/Trigger_IFTTT_Action/IFTTT_trigger.png differ diff --git a/docs/_static/images/Trigger_IFTTT_Action/configure_action.png b/docs/_static/images/Trigger_IFTTT_Action/configure_action.png index 159f088..9b74512 100644 Binary files a/docs/_static/images/Trigger_IFTTT_Action/configure_action.png and b/docs/_static/images/Trigger_IFTTT_Action/configure_action.png differ diff --git a/docs/_static/images/Trigger_IFTTT_Action/select_action.png b/docs/_static/images/Trigger_IFTTT_Action/select_action.png index 2d29707..f2336ff 100644 Binary files a/docs/_static/images/Trigger_IFTTT_Action/select_action.png and b/docs/_static/images/Trigger_IFTTT_Action/select_action.png differ diff --git a/docs/_static/images/Trigger_IFTTT_Action/update_new_news_item.png b/docs/_static/images/Trigger_IFTTT_Action/update_new_news_item.png index 29c3aff..d1751f4 100644 Binary files a/docs/_static/images/Trigger_IFTTT_Action/update_new_news_item.png and b/docs/_static/images/Trigger_IFTTT_Action/update_new_news_item.png differ diff --git a/docs/_static/images/plone_rss_applet/choose_google_sheets.png b/docs/_static/images/plone_rss_applet/choose_google_sheets.png new file mode 100644 index 0000000..ffae6d7 Binary files /dev/null and b/docs/_static/images/plone_rss_applet/choose_google_sheets.png differ diff --git a/docs/_static/images/plone_rss_applet/configure_action.png b/docs/_static/images/plone_rss_applet/configure_action.png new file mode 100644 index 0000000..056413c Binary files /dev/null and b/docs/_static/images/plone_rss_applet/configure_action.png differ diff --git a/docs/_static/images/plone_rss_applet/fill_rss_url.png b/docs/_static/images/plone_rss_applet/fill_rss_url.png new file mode 100644 index 0000000..1d19770 Binary files /dev/null and b/docs/_static/images/plone_rss_applet/fill_rss_url.png differ diff --git a/docs/_static/images/plone_rss_applet/finish.png b/docs/_static/images/plone_rss_applet/finish.png new file mode 100644 index 0000000..fa77770 Binary files /dev/null and b/docs/_static/images/plone_rss_applet/finish.png differ diff --git a/docs/_static/images/plone_rss_applet/google_spreadsheet.png b/docs/_static/images/plone_rss_applet/google_spreadsheet.png new file mode 100644 index 0000000..9338cc2 Binary files /dev/null and b/docs/_static/images/plone_rss_applet/google_spreadsheet.png differ diff --git a/docs/_static/images/plone_rss_applet/search_rss.png b/docs/_static/images/plone_rss_applet/search_rss.png new file mode 100644 index 0000000..5812e92 Binary files /dev/null and b/docs/_static/images/plone_rss_applet/search_rss.png differ diff --git a/docs/_static/images/plone_rss_applet/successfull_creation.png b/docs/_static/images/plone_rss_applet/successfull_creation.png new file mode 100644 index 0000000..c4ceaaf Binary files /dev/null and b/docs/_static/images/plone_rss_applet/successfull_creation.png differ diff --git a/docs/index.rst b/docs/index.rst index 7724b42..5eadcd8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,36 +1,9 @@ Welcome to collective.ifttt! ============================================ -.. image:: https://travis-ci.org/collective/collective.ifttt.svg?branch=master - :target: https://travis-ci.org/collective/collective.ifttt -.. image:: https://coveralls.io/repos/github/collective/collective.ifttt/badge.svg - :target: https://coveralls.io/github/collective/collective.ifttt -.. image:: https://readthedocs.org/projects/collectiveifttt/badge/?version=latest - :target: https://collectiveifttt.readthedocs.io/en/latest/?badge=latest - -Introduction ---------------------- - -`ifttt.com `_ - If This Then That, also known as IFTTT (pronounced /ɪft/) - -is a free web-based service to create chains of simple conditional statements, -called applets. These applets can -perform a configured action in response to a trigger. Triggers and actions are web services provided by -platforms such as Facebook, Pinterest, Youtube, Spotify - and now, Plone sites. - -Below are a few examples of IFTTT applets for better understanding: - - - If a video is liked on Youtube, then save the video details in Evernote - - If a profile picture gets changed on Facebook, then update the same profile picture on Twitter - - If I'm tagged in a photo on Facebook, then save it to my phone gallery - - If I receive an email about a new Twitter follower in my Gmail inbox, - then tweet the new follower a welcome message - - If NASA posts a new astronomy picture of the day, then add it to my screensaver gallery. - - Email me about Top Apps that have become FREE in the Apple App Store. - - Automatically unmute my Android phone when I get back home. - - Add a Spotify song from a liked YouTube Video. - -**collective.ifttt** is an addon which enables any Plone site to play in the -IFTTT ecosystem by allowing you to create IFTTT applets. +collective.ifttt is a Plone addon which enables any +Plone site to play in the IFTTT (pronounced /ɪft/) ecosystem +by allowing you to create IFTTT applets at `ifttt.com `_. Below are a few examples of using IFTTT with Plone sites. @@ -39,7 +12,6 @@ Below are a few examples of using IFTTT with Plone sites. - If new users sign up for an event, then add them to a Slack channel. - If content changes, then record who edited it in a Google spreadsheet. - Contents -------- @@ -48,10 +20,14 @@ We'll start with setting up a Plone RSS feed, which can be used on IFTTT without In the sections after that you will learn how to set up your IFTTT secret key and create IFTTT triggers, so you can create more customized applets. + .. toctree:: :maxdepth: 3 + What_is_IFTTT + Introduction_to_IFTTT_Applets Enable_RSS_feed_on_Plone + Using_Plone_RSS_Feeds_in_IFTTT_Applets Configuring_Your_IFTTT_Secret_Key Trigger_IFTTT_Action diff --git a/src/collective/ifttt/actions/configure.zcml b/src/collective/ifttt/actions/configure.zcml index ae50fe6..1cc942e 100644 --- a/src/collective/ifttt/actions/configure.zcml +++ b/src/collective/ifttt/actions/configure.zcml @@ -34,7 +34,7 @@