honeymoose
/
sp-dev-fx-webparts
mirror of https://github.com/pnp/sp-dev-fx-webparts.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated the README.md file with the latest changes.

This commit is contained in:
Simon-Pierre Plante 2017-04-25 01:26:49 -04:00 committed by GitHub
parent 0164cddab8
commit f4706497a1
1 changed files with 130 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

195
README.md
View File

@ -1,101 +1,166 @@
## React Content Query WebPart
# React Content Query WebPart
The `React Content Query WebPart` is a modern version of the good old `Content by Query WebPart` that was introduced in SharePoint 2007. Built for *SharePoint 2016* and *Office 365*, this modern version is built against the new **SharePoint Framework (SPFx)** and uses the latest *Web Stack* practices. While the original WebPart was based on a `XSLT` templating engine, this *React* WebPart is based on the well known [Handlebars templating engine](http://handlebarsjs.com), which empowers users to create simple, yet powerfull `HTML` templates for rendering the queried content. This new version also lets the user query `any site collections` which resides on the same domain url, add `unlimited filters`, query *DateTime* fields to the `nearest minute` rather than being limited to a day, and much more.
### Features
## Features
#### Custom tool pane
### User friendly configuration
A custom tool pane helps the user to easily configure his query in the same fashion he used to do with the original WebPart.
A custom tool pane helps the user to easily configure his query in the same fashion he used to do with the original WebPart, with the addition of the reactive toolpane that takes cares of refreshing the WebPart in real time as its settings are modified.
<img src="https://github.com/spplante/react-content-query/blob/master/Misc/toolpart.gif" width="500" />
<img src="https://github.com/spplante/react-content-query/blob/master/Misc/toolpart.gif" />
<br>
### Cross site collection
#### Handlebars templating engine
Provide a link to your handlebars `.html` template and decide how you want to render the queried results.
*Handlebars template :*
```handlebars
<h1>Results : </h1>
<ul id="items">
{{#each items}}
<li>
<span>{{Title.textVaue}}</span>
{{FileRef.htmlValue}}
</li>
{{/each}}
</ul>
```
*Output :*
```handlebars
<h1>Results : </h1>
<ul id="items">
<li>
<span>My Item #1</span>
<a href="...">..</a>
</li>
<li>
<span>My Item #2</span>
<a href="...">..</a>
</li>
...
</ul>
```
#### Query any site collection within the same domain
The WebParts uses the search in order to get all sites under the current domain, which makes it possible to query not only subsites but other site collections and their subsites as well.
The WebPart uses the search in order to get all sites under the current domain, which makes it possible to query not only subsites but other site collections and their subsites as well.
![DateTime](https://github.com/spplante/react-content-query/blob/master/Misc/allsites.gif "DateTime")
<br>
#### Add unlimited filters
### Unlimited filters
The user isn't limited to 3 filters anymore, an unlimited amount of filters can be added.
The user isn't limited to 3 filters anymore, an unlimited amount of filters can be added to narrow down your query
<img src="https://github.com/spplante/react-content-query/blob/master/Misc/filters.gif" width="500" />
<br>
### Improved date time filters
#### Include time in date filters if needed
It is now possible to include time validation when querying date fields, giving the user more possibilities when it comes to filtering events etc...
It is now possible to include time validation when querying date fields, giving the ability to be more precise when it comes to querying items against date values.
<img src="https://github.com/spplante/react-content-query/blob/master/Misc/datetime.gif" width="500" />
<br>
#### Built in page context available within the template
### Handlebars templating engine
The SPFx [PageContext](https://github.com/SharePoint/sp-dev-docs/blob/master/reference/spfx/sp-page-context/pagecontext.md) object is exposed directly within the handlebars template context, which allows the user to interact with many usefull dynamic properties such as the current language for instance.
Enjoy a simple, yet powerfull html-based templating engine for rendering your results. The WebPart even generates a default Handlebars template for you based on the view fields you have selected during the configuration!
For advanced users, more than 150 Handlebars block helpers are available by default within the user defined template. For a list of all block helpers, see [handlebars-helpers](https://github.com/helpers/handlebars-helpers#helpers)
<br>
## Getting Started
### Adding the WebPart to your page
To add the `React Content Query WebPart` to your site page you have two options :
- Either clone this repository, build the project yourself and connect it to SharePoint (see [officedev documentation](https://dev.office.com/sharepoint/docs/spfx/web-parts/get-started/connect-to-sharepoint))
- Or download the `react-content-query-webpart.sppkg` file available in the `sharepoint/solution` folder of the repository and add it directly in your app catalog in order to be able to use it in your site.
Note : The second method will only work for Office 365 sites, since the **.ppkg** file points to an Office 365 public CDN url which expects the referer to come from a valid https://**\*.sharepoint.com\*** url.
<br>
### Configuring the WebPart
As seen in the [User friendly configuration](### User friendly configuration) section, configuring the WebPart is quite straight forward. However, here's a list of *gotchas* that could save you some time :
- The `Web Url` property uses the search to find all sites that are under the current domain. That being said, newly created sites can take a while to appear within the dropdown options, based on the search crawl schedule.
- The `Filters` property still supports query string expressions like *[PageQueryString:ParamName]* for text fields, and date expressions such as *[Today]* or *[Today] + 4* for date fields.
- The `Template` property stops getting automtically generated while selecting view fields as soon as the template is manually updated, in order to prevent unwanted loss of templating efforts.
- The `Template Url` property has priority over the `Template` property, which means if a valid handlebars template url is provided, the inline template will be kept, but ignored at runtime.
<br>
### Designing your Handlebars template
#### Basics
Before anything, make sure you understand the basics of Handlebars and its associated syntax by reading their [documentation](http://handlebarsjs.com)
<br>
#### Available tokens
To make it simple, a `template context` is automatically exposed within the handlebars template, giving the user the ability to work with the following exposed tokens :
Property | Description
-----------------|------------------
{{items}} | The array of objects that represents the items returned from the CAML query
{{pageContext}} | The SPFx [PageContext](https://github.com/SharePoint/sp-dev-docs/blob/master/reference/spfx/sp-page-context/pagecontext.md) object which contains usefull informations about the current web, list, user, language etc...
{{accessDenied}} | A boolean value indicating if the current user has a denied access to the configured site that gets queried. This gives the designer the power to decide what to render in a case where the current user doesn't have access to the queried site.
{{webNotFound}} | A boolean value indicating if the configured site that gets queried doesn't exist anymore. This also gives the designer the power to decide what to render in a case where the queried site doesn't exist anymore.
<br>
#### Available block helpers
Besides the available tokens above, nearly 150 [block helpers](http://handlebarsjs.com/block_helpers.html) are also available for use in the Handlebars template, see [handlebars-helpers](https://github.com/helpers/handlebars-helpers#helpers) for a list of all available block helpers.
*Example using the "compare" block helper for conditional rendering based on current language :*
```handlebars
<h1>Current language : {{pageContext.web.language}} </h1>
<h1>Current web title : {{pageContext.web.title}} </h1>
<h1>Current user display name : {{pageContext.user.displayName}} </h1>
<h1>Current user login name : {{pageContext.user.loginName}} </h1>
<h1>Current user email : {{pageContext.user.email}} </h1>
{{#compare pageContext.web.language '==' 1033}}
<h1>This is rendered if current language is 1033</h1>
{{else}}
<h1>This is rendered if current language is anything else
{{/compare}}
```
<br>
#### Displaying items and their values
For displaying items and their field values, we must first iterate through the exposed **{{items}}** token using a **{{each}}** block helper :
*Handlebars : *
```handlebars
{{#each items}}
<div class="item"></div>
{{/each}}
```
*Output : *
```handlebars
<div class="item"></div>
<div class="item"></div>
<div class="item"></div>
...
```
#### Three predefined type of values for any field
Once we can loop within the items, we can render any field, as long as the field has been selected in the `View Fields` property of the toolpane. The Handlebars token corresponsding to a field is always the field's internal name, which is displayed in between {{brackets}} next to the field's display name in the property pane for reference.
For every view field returned by the query, three predefined types of values are available for an easier integration by the user who designs the handlebars template.
*Handlebars template :*
*Handlebars : *
```handlebars
<h1>Text Value : {{MyUserField.textValue}}</h1>
<h1>Html Value : {{MyUserField.htmlValue}}</h1>
<h1>Raw Value : {{MyUserField.rawValue}}</h1>
{{#each items}}
<div class="item">
<p>MyField value : {{MyField}}</p>
</div>
{{/each}}
```
*Output :*
*Output : *
```handlebars
<h1>Text Value : Simon-Pierre Plante</h1>
<h1>Html Value : <a href="..." onclick="...">Simon-Pierre Plante</a></h1>
<h1>Raw Value : { ID: 18 }</h1>
<div class="item">[object]</div>
<div class="item">[object]</div>
<div class="item">[object]</div>
```
We are almost there, the above code is rendering a *[object]* the Content Query Webpart offers 3 different ways to render a field value:
### Building the code
Property | Description
---------|---------------
{{MyField.textValue}} | Renders the text value of the field, a more readable end-user value to use for display.
{{MyField.htmlValue}} | Renders the HTML value of the field. For example, a *Link* field HTML value would render something like \<a href="...">My Link Field\</a>
{{MyField.rawValue}} | Returns the raw value of the field. For example, a *Taxonomy* field raw value would return an object which contains the term wssId and it's label
*Handlebars : *
```handlebars
{{#each items}}
<div class="item">
<p>MyUserField text value : {{MyUserField.textValue}}</p>
<p>MyUserField html value : {{MyUserField.htmlValue}}</p>
<p>MyUserField raw value : {{MyUserField.rawValue}}</p>
</div>
{{/each}}
```
*Output : *
```handlebars
<div class="item">
<p>MyUserField text value : Simon-Pierre Plante</p>
<p>MyUserField html value : <a href="..." onclick="...">Simon-Pierre Plante</a></p>
<p>MyUserField raw value : 26</p>
</div>
...
```
<br>
## Building the code
```bash
git clone the repo