Merge pull request #36 from archriss/dev

v3.5.0

Demo/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "react": "16.0.0-alpha.12",
     "react-native": "0.48.3",
-    "react-native-render-html": "3.4.0"
+    "react-native-render-html": "3.5.0"
   },
   "devDependencies": {
     "babel-jest": "21.0.2",

Demo/src/HTMLDemo.js

@@ -11,7 +11,8 @@ const DEFAULT_PROPS = {
     htmlStyles: CUSTOM_STYLES,
     renderers: CUSTOM_RENDERERS,
     imagesMaxWidth: IMAGES_MAX_WIDTH,
-    onLinkPress: (evt, href) => { Linking.openURL(href); }
+    onLinkPress: (evt, href) => { Linking.openURL(href); },
+    debug: true
 };
 
 export default class Demo extends Component {

Demo/src/snippets.js

@@ -3,14 +3,14 @@ import { View } from 'react-native';
 import { _constructStyles } from 'react-native-render-html/src/HTMLStyles';
 
 export const paragraphs = `
-    <p style="font-size:1.3em;">This paragraph is styled a font size set in em !</p>
-    <em>This one showcases the default renderer for the "em" HTML tag.</em>
-    <p style="padding:10%;">This one features a padding <strong>in percentage !</strong></p>
-    <hr />
-    <i>Here, we have a style set on the "i" tag with the "tagsStyles" prop.</i>
-    <p>And <a href="http://google.fr">This is a link !</a></p>
-    <a href="http://google.fr"><div style="background-color: red; height: 20px; width:40px;"></div></a>
-    <p class="last-paragraph">Finally, this paragraph is styled through the classesStyles prop</p>
+<p style="font-size:1.3em;">This paragraph is styled a font size set in em !</p>
+<em>This one showcases the default renderer for the "em" HTML tag.</em>
+<p style="padding:10%;">This one features a padding <strong>in percentage !</strong></p>
+<hr />
+<i>Here, we have a style set on the "i" tag with the "tagsStyles" prop.</i>
+<p>And <a href="http://google.fr">This is a link !</a></p>
+<a href="http://google.fr"><div style="background-color: red; height: 20px; width:40px;"></div></a>
+<p class="last-paragraph">Finally, this paragraph is styled through the classesStyles prop</p>
 `;
 
 export const lists = `
@@ -77,6 +77,31 @@ export const layoutStyles = `
     </div>
 `;
 
+export const textsStylesBehaviour = `
+<p>Styling texts is a very tricky part of converting HTML into react-native components.</p>
+<p>The way react-native's <em>Text</em> components behaves is a lot different from our browsers' implementation.</p>
+<p>Let's see how styles are applied to texts with this plugin.</p>
+
+<div style="color:red;">This text is inside a div, without a text tag wrapping it. The <em>div</em> tag only has <em>color:red;</em> as style.</div>
+
+In the example above, you may find, if you inspect the rendered components, that it's the <em>Text</em> component inside that actually receives the color attribute.
+This is because this library parses every text-only style of <em>View</em> wrappers and moves them to each <em>Text</em> child.
+
+<div style="color:red">
+    <p>This first paragraph doesn't have a specific styling.</p>
+    <p style="color:blue;">This one is blue.</p>
+</div>
+
+<p>Here, the <em>div</em> wrapper still has <em>color:red;</em> as style.</div>.</p>
+
+<p>The first paragraph inside it doesn't have any style attribute, either from HTML or from the <em>tagsStyles</em> or <em>classesStyles</em> props.</p>
+<p>The second one is set to be blue from its <em>style</em> attribute.</p>
+
+<p>You can see the order of priorities that applies to styling. The less important are your <em>tagsStyles</em>, 
+then your <em>classessStyles</em> and finally the styles parsed from your HTML content.</p>
+`;
+
+
 export const ignoringTagsAndStyles = `
     <p>The following tag (h2) is ignored with the "ignoredTags" prop</p>
     <h2>This shouldn't be rendered !</h2>
@@ -155,6 +180,14 @@ export default {
     images404: { name: '404 images', props: { baseFontSize: 20 } },
     trickyStuff: { name: 'Tricky stuff' },
     layoutStyles: { name: 'Layout styles' },
+    textsStylesBehaviour: {
+        name: 'Texts styles behaviour',
+        props: {
+            tagsStyles: {
+                div: { borderWidth: 1, padding: 10, marginBottom: 10 }
+            }
+        }
+    },
     ignoringTagsAndStyles: {
         name: 'Ignoring tags & styles',
         props: {

README.md

@@ -15,6 +15,8 @@ An iOS/Android pure javascript react-native component that renders your HTML int
     - [Props](#props)
     - [Demo](#demo)
     - [Creating custom renderers](#creating-custom-renderers)
+        - [Custom HTML tags](#custom-html-tags)
+        - [Lists prefixes](#lists-prefixes)
     - [Styling](#styling)
     - [Images](#images)
     - [Altering content](#altering-content)
@@ -60,18 +62,24 @@ Prop | Description | Type | Required/Default
 `uri` | *(experimental)* remote website to parse and render | `string` | Optional
 `decodeEntities` | Decode HTML entities of your content | `bool` | Optional, defaults to `true`
 `imagesMaxWidth` | Resize your images to this maximum width, see [images](#images) | `number` | Optional
+`imagesInitialDimensions` | Default width and height to display while image's dimensions are being retrieved, see [images](#images) | `{ width: 100, height: 100 }` | Optional
 `onLinkPress` | Fired with the event and the href as its arguments when tapping a link | `function` | Optional
+`onParsed` | Fired when your HTML content has been parsed, 1st arg is `dom` from htmlparser2, 2nd is `RNElements` from this module | `function` | Optional
 `tagsStyles` | Provide your styles for specific HTML tags, see [styling](#styling) | `object` | Optional
 `classesStyles` | Provide your styles for specific HTML classes, see [styling](#styling) | `object` | Optional
+`listsPrefixesRenderers` | Your custom renderers from `ul` and `ol` bullets, see [lists prefixes](#lists-prefixes) | `object` | Optional
 `containerStyle` | Custom style for the default container of the renderered HTML | `object` | Optional
 `customWrapper` | Replace the default wrapper with a function that takes your content as the first parameter | `function` | Optional
+`remoteLoadingView` | Replace the default loader while fetching a remote website's content | `function` | Optional
+`remoteErrorView` | Replace the default error if a remote website's content could not be fetched | `function` | Optional
 `emSize` | The default value in pixels for `1em` | `number` | `14`
-`baseFontSize` | The default fontSize applied to `<Text>` components | `number` | `14`
+`baseFontStyle` | The default style applied to `<Text>` components | `number` | `14`
 `alterData` | Target some specific texts and change their content, see [altering content](#altering-content) | `function` | Optional
 `alterChildren` | Target some specific nested nodes and change them, see [altering content](#altering-content) | `function` | Optional
-`ignoredTags` | HTML tags you don't want rendered, see [ignoring HTML content](#ignoring-html-content) | `array` | Optional, `['head', 'scripts']`
+`ignoredTags` | HTML tags you don't want rendered, see [ignoring HTML content](#ignoring-html-content) | `array` | Optional, `['head', 'scripts', ...]`
 `ignoredStyles` | CSS styles from the `style` attribute you don't want rendered, see [ignoring HTML content](#ignoring-html-content) | `array` | Optional
 `ignoreNodesFunction` | Return true in this custom function to ignore nodes very precisely, see [ignoring HTML content](#ignoring-html-content) | `function` | Optional
+`debug` | Prints the parsing result from htmlparser2 and render-html after the initial render | `bool` | Optional, defaults to `false`
 
 ## Demo
 
@@ -85,6 +93,8 @@ Feel free to write more advanced examples and submit a pull-request for it, it w
 
 This is very useful if you want to make some very specific styling of your HTML content, or even implement custom HTML tags.
 
+### Custom HTML tags
+
 Just pass an object to the `renderers` prop with the tag name as the key, an a function as its value, like so :
 
 ```javascript
@@ -113,6 +123,21 @@ Your renderers functions receive several arguments that will be very useful to m
 * `convertedCSSStyles` : conversion of the `style` attribute from CSS to react-native's stylesheet
 * `passProps` : various useful information : `groupInfo`, `parentTagName`, `parentIsText`...
 
+### Lists prefixes
+
+The default renderer of the `<ul>` and `<ol>` tags will either render a bullet or the count of your elements. If you wish to change this without having to re-write the whole list rendering implementation, you can use the `listsPrefixesRenderers` prop.
+
+Just like with the `renderers` prop, supply an object with `ul` and/or `ul` as functions that recevie the [same arguments as your custom HTML tags](#custom-html-tags). For instance, you can swap the default black bullet of `<ul>` with a blue cross :
+
+```javascript
+// ... your props
+ul: (htmlAttribs, children, convertedCSSStyles, passProps) => {
+    return (
+        <Text style={{ color: 'blue', fontSize: 16 }}>+</Text>
+    );
+}
+```
+
 ## Styling
 
 In addition to your custom renderers, you can apply specific styles to HTML tags (`tagsStyles`) or HTML classes (`classesStyles`). You can also combine these styles with your custom renderers.
@@ -121,6 +146,8 @@ Styling options override thesmelves, so you might render a custom HTML tag with
 
 The default style of your custom renderer will be merged to the one from your `classesStyles` which will also be merged by the `style` attribute.
 
+> **IMPORTANT NOTE : Do NOT use the `StyleSheet` API to create the styles you're going to feed to `tagsStyle` and `classesStyles`. Although it might look like it's working at first, the caching logic of `react-native` makes it impossible for this module to deep check each of your style to properly apply the precedence and priorities of your nested tags' styles.**
+
 Here's an usage example
 
 ```javascript
@@ -130,7 +157,7 @@ Here's an usage example
 
 const html = `
     <i>Here, we have a style set on the "i" tag with the "tagsStyles" prop.</i>
-    <p class="last-paragraph">Finally, this paragraph is style through the classesStyles prop</p>`;
+    <p class="last-paragraph">Finally, this paragraph is styled through the classesStyles prop</p>`;
 ```
 
 ![](https://puu.sh/xF7Jx/e4b395975d.png)
@@ -145,6 +172,8 @@ A nice trick, demonstrated in the [basic usage of this module](#basic-usage) is
 
 Please note that if you set width AND height through any mean of styling, `imagesMaxWidth` will be ignored.
 
+Before their dimensions have been properly retrieved, images will temporarily be rendered in 100px wide squares. You can override this default value with prop `imagesInitialDimensions`.
+
 Images with broken links will render an empty square with a thin border, similar to what safari renders in a webview.
 
 Please note that all of these behaviours are implemented in the default `<img>` renderer. If you want to provide your own `<img>` renderer, you'll have to make this happen by yourself. You can use the `img` function in `HTMLRenderers.js` as a starting point.
@@ -204,7 +233,7 @@ You can't expect native components to be able to render *everything* you can fin
 * `ignoredStyles` : array of ignored CSS rules. Nothing is ignored by default
 * `ignoreNodesFunction` : this is a cumbersome, yet powerful, way of ignoring very specific stuff.
 
-**Please note** that if you supply `ignoredTags`, you will override the default ignored ones. There are *a lot* of them, if you want to keep them and add you own, you can do something like : 
+**Please note** that if you supply `ignoredTags`, you will override the default ignored ones. There are *a lot* of them, if you want to keep them and add you own, you can do something like :
 
 ```javascript
 import { IGNORED_TAGS } from 'react-native-render-html/HTMLUtils';

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-render-html",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "author": "Archriss",
   "license": "BSD-2-Clause",
   "repository": "https://github.com/archriss/react-native-render-html",
@@ -17,6 +17,7 @@
     "events": "^1.1.0",
     "html-entities": "^1.2.0",
     "htmlparser2": "^3.9.0",
+    "lodash.isequal": "4.5.0",
     "stream": "0.0.2"
   },
   "peerDependencies": {