Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/framework7io/framework7-plugin-feeds

Framework7 Feeds plugin brings easy RSS feeds integration into Framework7 app.
https://github.com/framework7io/framework7-plugin-feeds

app-development cordova framework7 mobile phonegap plugin

Last synced: 3 days ago
JSON representation

Framework7 Feeds plugin brings easy RSS feeds integration into Framework7 app.

Awesome Lists containing this project

README 

        



# Framework7 Feeds Plugin



Framework7 Feeds plugin brings easy RSS feeds integration into Framework7 app.



Plugin comes with easy and powerful JS API to integrate and customize RSS feeds. But in most cases you will not need to use JavaScript at all.



## Installation



Just grab plugin files from `dist/` folder or using npm:



```

npm install framework7-plugin-feeds

```



And link them to your app right AFTER Framework7's scripts and styles:



```



...



```



## Usage



### Install & Enable Plugin



After you included plugin script file, you need to install plugin before you init app:



```js

// install plugin to Framework7

Framework7.use(Framework7Feeds);



// init app

var app = new Framework7({

  ...

})

```



### ES Module



This plugin comes with ready to use ES module:



```js

import Framework7 from 'framework7';

import Framework7Feeds from 'framework7-plugin-feeds';



// install plugin

Framework7.use(Framework7Feeds);



// init app

var app = new Framework7({

  ...

})

```



### API



Plugin extends initiliazed `app` instance with new methods:



  * `app.feeds.create(parameters)` - init Feeds. This method returns initialized Feeds instance.

  * `app.feeds.get(feedsEl)` - get Feeds instance by HTML element. Method returns initialized Feeds instance.

  * `app.feeds.destroy(feedsEl)` - destroy Feeds instance



### Feeds Parameters



  

    

      Parameter

      Type

      Default

      Description

    

  

  

    

      el

      string
HTMLElement

      

      Target List Block element. In case of string - CSS selector of list block element where to put parsed feeds list.

    

    

      feedUrl

      string

      

      URL of RSS feed to parse and load

    

    

      openIn

      string

      page

      Could be `'page'` or `'popup'`. Defines how to open generated page of single feed item

    

    

      formatDate

      function (date)

      

      Function to format RSS item date, this function should return string with formatted date

    

    

      virtualList

      object
boolean

      false

      Object with Virtual List parameters. If specified, then RSS feed will be loaded as Virtual List

    

    

      customItemFields

      array

      []

      Array with additional item fields (xml tags) that also should be parsed from RSS, for example `['content:encoded', 'author']`. Such custom RSS tags with colon (:) will be parsed and available in template without colon, for example, the value of `content:encoded` tag will be available in templates as `contentencoded` property.

    

    

      renderVirtualListItem

      function(item, index)

      

      Function to render virtual list item in case of enabled virtual list. Must return item HTML string

    

    

      renderList

      function(data)

      

      Function to render feeds list. Must return list HTML string

    

    

      renderItemPage

      function(item)

      

      Function to render single feeds item page. Must return page HTML string

    

    

      renderItemPopup

      function(item)

      

      Function to render single feeds item popup. Must return popup HTML string

    

    

      routableModals

      boolean

      true

      Will add opened feeds item modal (when `openIn: 'popup'`) to router history which gives ability to close dynamic feeds item page by going back in router history and set current route to the feeds item modal

    

    

      url

      string

      feed/

      Feeds item URL that will be set as a current route url

    

    

      view

      object

      

      Link to initialized View instance which is required for Feeds to work. By default, if not specified, it will be opened in parent View

    

    

      pageBackLinkText

      string

      Back

      Feeds item page back link text

    

    

      popupCloseLinkText

      string

      Close

      Feeds item popup close link text

    

  



Usage example with manual initialization:



```html



```

```js

var feed = app.feeds.create({

  el: '.my-feed',

  feedUrl: 'http://path-to-rss.com/rss.xml',

  openIn: 'popup'

});

```



### Automatic initialization



If you need minimal parser setup you may use automatic initialization without JavaScript at all. In this case you need to add additional `feeds-init` class to feeds container and specify all parameters from table above using `data-` attributes, for example:



```



```



### Feeds Events



  

    

      Event

      Target

      Arguments

      Description

    

  

  

    

      ajaxStart

      feeds

      (feeds)

      Event will be triggered when right before XHR request to specified feed url

    

    

      feedsAjaxStart

      app

      (feeds)

      Event will be triggered when right before XHR request to specified feed url

    

    

      ajaxComplete

      feeds

      (feeds, response)

      Event will be triggered when when XHR request completed

    

    

      feedsAjaxComplete

      app

      (feeds)

      Event will be triggered when when XHR request completed

    

    

      open

      feeds

      (feeds)

      Event will be triggered when Feeds item starts its opening animation (page transiton on popup open transition)

    

    

      feedsOpen

      app

      (feeds)

      Event will be triggered when Feeds item starts its opening animation (page transiton on popup open transition)

    

    

      opened

      feeds

      (feeds)

      Event will be triggered after Feeds item completes its opening animation (page transiton on popup open transition)

    

    

      feedsOpened

      app

      (feeds)

      Event will be triggered after Feeds item completes its opening animation (page transiton on popup open transition)

    

    

      close

      feeds

      (feeds)

      Event will be triggered when Feeds item starts its closing animation (page transiton on popup open transition)

    

    

      feedsClose

      app

      (feeds)

      Event will be triggered when Feeds item starts its closing animation (page transiton on popup open transition)

    

    

      closed

      feeds

      (feeds)

      Event will be triggered after Feeds item completes its closing animation (page transiton on popup open transition)

    

    

      feedsClosed

      app

      (feeds)

      Event will be triggered after Feeds item completes its closing animation (page transiton on popup open transition)

    

  



### Usage with Pull To Refresh



Feeds plugin fully compatible with Pull To Refresh component, and will automatically refresh feed on pull to refresh. No additional actions or code are required.



## Demo



Plugin comes with demo example to see how it works and looks. To make demo works you need to run in terminal:



```

$ npm run prod

```



## Contribute



All changes should be done only in `src/` folder. This project uses `gulp` to build a distributable version.



First you need to install all dependencies:



```

$ npm install

```



Then to build plugin's files for testing run:

```

$ npm run build:dev

```



If you need a local server while you developing you can run:



```

$ gulp server

```

or

```

$ npm run dev

```



And working demo will be available at `http://localhost:3000/demo/`



## Live Preview



https://framework7io.github.io/framework7-plugin-feeds/