From fc88b8ccacce23f9b99a376ff95f15bbde7a9069 Mon Sep 17 00:00:00 2001 From: Hannah Trosi Date: Sun, 10 Jul 2016 22:52:58 -0700 Subject: [PATCH] website refactoring clean up optimization docs rearrange sections in nav bar add layout api sizing Q to FAQ add corner rounding to Optimizations + check back soon tags for methods to be released in 2.0 add layoutSpecs Containers overview -> node containers Node overview -> node subclasses remove ASTextCellNode --- _data/nav_docs.yml | 14 +- _docs/automatic-layout-containers.md | 148 +++++++++++++++++++-- _docs/cell-node.md | 1 - _docs/containers-overview.md | 2 +- _docs/corner-rounding.md | 8 +- _docs/debug-tool-hit-test-visualization.md | 2 +- _docs/faq.md | 21 ++- _docs/hit-test-slop.md | 2 +- _docs/layer-backing.md | 19 ++- _docs/layout-api-sizing.md | 6 - _docs/node-overview.md | 2 +- _docs/placeholder-fade-duration.md | 2 +- _docs/subtree-rasterization.md | 17 ++- _docs/synchronous-concurrency.md | 5 +- static/main.css | 16 ++- 15 files changed, 215 insertions(+), 50 deletions(-) diff --git a/_data/nav_docs.yml b/_data/nav_docs.yml index 31396c2f..f22c3f6f 100755 --- a/_data/nav_docs.yml +++ b/_data/nav_docs.yml @@ -21,7 +21,6 @@ items: - display-node - cell-node - - text-cell-node - control-node - button-node - text-node @@ -34,17 +33,22 @@ - scroll-node - title: Layout items: -- title: Optimizations + - automatic-layout-containers +- title: Advanced Layout items: - - layer-backing - - synchronous-concurrency - - subtree-rasterization + - layout-api-sizing - title: Conveniences items: - hit-test-slop - batch-fetching-api - image-modification-block - placeholder-fade-duration +- title: Optimizations + items: + - layer-backing + - subtree-rasterization + - synchronous-concurrency + - corner-rounding - title: Tools items: - debug-tool-hit-test-visualization diff --git a/_docs/automatic-layout-containers.md b/_docs/automatic-layout-containers.md index 39bbe2ed..ef722480 100644 --- a/_docs/automatic-layout-containers.md +++ b/_docs/automatic-layout-containers.md @@ -1,24 +1,146 @@ --- -title: Layout Containers +title: LayoutSpecs layout: docs permalink: /docs/automatic-layout-containers.html prevPage: automatic-layout-basics.html nextPage: automatic-layout-examples.html --- -AsyncDisplayKit includes a library of components that can be composed to declaratively specify a layout. The following LayoutSpecs allow you to have multiple children: +AsyncDisplayKit includes a library of `layoutSpec` components that can be composed to declaratively specify a layout. The **child(ren) of a layoutSpec may be a node, a layoutSpec or a combination of the two types.** -* **ASStackLayoutSpec** is based on a simplified version of CSS flexbox. It allows you to stack components vertically or horizontally and specify how they should be flexed and aligned to fit in the available space. -* **ASStaticLayoutSpec** allows positioning children at fixed offsets. +Both nodes and layoutSpecs conform to the `` protocol. Any `ASLayoutable` object may be the child of a layoutSpec. ASLayoutable properties may be applied to ASLayoutable objects to create complex UIs. -The following layoutSpecs allow you to layout a single children: -* **ASLayoutSpec** can be used as a spacer if it contains no children -* **ASInsetLayoutSpec** applies an inset margin around a component. -* **ASBackgroundLayoutSpec** lays out a component, stretching another component behind it as a backdrop. -* **ASOverlayLayoutSpec** lays out a component, stretching another component on top of it as an overlay. -* **ASCenterLayoutSpec** centers a component in the available space. -* **ASRatioLayoutSpec** lays out a component at a fixed aspect ratio. Great for images, gifs and videos. -* **ASRelativeLayoutSpec** lays out a component and positions it within the layout bounds according to vertical and horizontal positional specifiers. Similar to the “9-part” image areas, a child can be positioned at any of the 4 corners, or the middle of any of the 4 edges, as well as the center. +### Single Child layoutSpecs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LayoutSpecDescription
ASInsetLayoutSpecapplies an inset margin around a component.
ASRatioLayoutSpeclays out a component at a fixed aspect ratio (which can be scaled). Great for images, gifs and videos.
ASOverlayLayoutSpeclays out a component, stretching another component on top of it as an overlay. The order in which subnodes are added matter for this layoutSpec.
ASBackgroundLayoutSpeclays out a component, stretching another component behind it as a backdrop. The order in which subnodes are added matter for this layoutSpec.
ASCenterLayoutSpeccenters a component in the available space.
ASRelativeLayoutSpeclays out a component and positions it within the layout bounds according to vertical and horizontal positional specifiers. Similar to the “9-part” image areas, a child can be positioned at any of the 4 corners, or the middle of any of the 4 edges, as well as the center.
ASLayoutSpeccan be used as a spacer if it contains no child.
+ +### Multiple Child(ren) layoutSpecs + +The following layoutSpecs may contain one or more children. + + + + + + + + + + + + + + + + + + +
LayoutSpecDescription
ASStackLayoutSpecis based on a simplified version of CSS flexbox. It allows you to stack components vertically or horizontally and specify how they should be flexed and aligned to fit in the available space.
ASStackLayoutSpecis based on a simplified version of CSS flexbox. It allows you to stack components vertically or horizontally and specify how they should be flexed and aligned to fit in the available space.
ASStaticLayoutSpecallows positioning children at fixed offsets.
+ +# ASLayoutable Properties + +The following properties can be applied to both nodes _and_ layoutSpecs; both conform to the protocol. + +### ASStackLayoutable Properties + +The following properties will only apply to a child wrapped in an **stack** layoutSpec. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyDescription
CGFloat .spacingBeforeAdditional space to place before this object in the stacking direction.
CGFloat .spacingAfterAdditional space to place after this object in the stacking direction.
BOOL .flexGrowIf the sum of childrens' stack dimensions is less than the minimum size, should this object grow? Used when attached to a stack layout.
BOOL .flexShrinkIf the sum of childrens' stack dimensions is greater than the maximum size, should this object shrink? Used when attached to a stack layout.
ASRelativeDimension .flexBasisSpecifies the initial size for this object, in the stack dimension (horizontal or vertical), before the flexGrow or flexShrink properties are applied and the remaining space is distributed.
ASStackLayoutAlignSelf alignSelfOrientation of the object along cross axis, overriding alignItems. Used when attached to a stack layout.
CGFloat .ascenderUsed for baseline alignment. The distance from the top of the object to its baseline./td> +
CGFloat .descenderUsed for baseline alignment. The distance from the baseline of the object to its bottom.
+ +### ASStaticLayoutable Properties + +The following properties will only apply to a child wrapped in an **static** layoutSpec. + + + + + + + + + + + + + + +
PropertyDescription
.sizeRangeIf specified, the child's size is restricted according to this `ASRelativeSizeRange`. Percentages are resolved relative to the static layout spec.
.layoutPositionThe `CGPoint` position of this object within its parent spec.
+ +### Best Practices + +
    +
  • don't wrap everything in a staticLayoutSpec
    • +
  • avoid using preferred frame size for everything - won't respond nicely to device rotation or device sizing differences
    • +
-##Strategy diff --git a/_docs/cell-node.md b/_docs/cell-node.md index 7b59229a..ae4e3036 100755 --- a/_docs/cell-node.md +++ b/_docs/cell-node.md @@ -140,4 +140,3 @@ With this property set to `YES`, the main thread will be blocked until display h
Using this option does not eliminate all of the performance advantages of AsyncDisplayKit. Normally, a cell has been preloading and is almost done when it reaches the screen, so the blocking time is very short. Even if the rangeTuningParameters are set to 0 this option outperforms UIKit. While the main thread is waiting, subnode display executes concurrently.
- diff --git a/_docs/containers-overview.md b/_docs/containers-overview.md index 047c4ca6..15e22122 100644 --- a/_docs/containers-overview.md +++ b/_docs/containers-overview.md @@ -1,5 +1,5 @@ --- -title: Containers Overview +title: Node Containers layout: docs permalink: /docs/containers-overview.html prevPage: layout-engine.html diff --git a/_docs/corner-rounding.md b/_docs/corner-rounding.md index 59eaa15c..f7c702a4 100644 --- a/_docs/corner-rounding.md +++ b/_docs/corner-rounding.md @@ -65,7 +65,9 @@ A key limitation of precomposited corners is that the corners must only touch on Note that AsyncDisplayKit nodes have a special optimization of `.cornerRadius` that automatically implements precomposited corners **only when using** `.shouldRasterizeDescendants`. It's important to think carefully before you enable rasterization, so don't use this option without first reading all about the concept. -Finally, if you're looking for a simple, flat-color rounded rectangle or circle, AsyncDisplayKit offers a variety of conveniences to provide this. See `UIImage+ASConveniences.h` for methods to create flat-colored, rounded-corner resizable images using precomposited corners (both alpha and opaque are supported). +
+If you're looking for a simple, flat-color rounded rectangle or circle, AsyncDisplayKit offers a variety of conveniences to provide this. See `UIImage+ASConveniences.h` for methods to create flat-colored, rounded-corner resizable images using precomposited corners (both alpha and opaque are supported). These are great for use as placeholders for image nodes or backgrounds for ASButtonNode. More precomposited corner methods will be released with AsyncDisplayKit 2.0 release. +
### Clip Corner @@ -80,6 +82,10 @@ Clip corners applies to two main types of corner rounding situations:
  • Rounded corners on top of a stationary texture or photo background. The photo clip corner method is tricky, but useful!
    • +
    +Check back soon! Clip corner methods may be released in AsyncDisplayKit 2.0 release. +
    + ##Is it ever okay to use CALayer's .cornerRadius property? There are a few, quite rare cases in which it is appropriate to use `.cornerRadius.` These include when there is dynamic content moving _both_ through the inside and underneath the corner. For certain animations, this is impossible to avoid. However, in many cases, it is easy to adjust your design to eliminate one of the sources of movement. One such case was discussed in the section on corner movement. diff --git a/_docs/debug-tool-hit-test-visualization.md b/_docs/debug-tool-hit-test-visualization.md index 4a8fd896..5c764d4f 100755 --- a/_docs/debug-tool-hit-test-visualization.md +++ b/_docs/debug-tool-hit-test-visualization.md @@ -2,7 +2,7 @@ title: Hit Test Visualization layout: docs permalink: /docs/debug-tool-hit-test-visualization.html -prevPage: placeholder-fade-duration.html +prevPage: synchronous-concurrency.html nextPage: debug-tool-pixel-scaling.html --- diff --git a/_docs/faq.md b/_docs/faq.md index 3119e297..e36c906a 100644 --- a/_docs/faq.md +++ b/_docs/faq.md @@ -9,22 +9,24 @@ nextPage: containers-overview.html ###Common Developer Mistakes ###Common Conceptual Misunderstandings ###Common Performance Questions @@ -63,6 +65,11 @@ AsyncDisplayKit does not use cell reuse, for a number of specific reasons, one s A node's layoutSpec gets regenerated every time its `layoutThatFits:` method is called.
    +### Layout API Sizing +
    +If you're confused by `ASRelativeDimension`, `ASRelativeSize`, `ASRelativeSizeRange` and `ASSizeRange`, check out our Layout API Sizing guide. +
    + ### CALayer's .cornerRadius Property Kills Performance
    CALayer's' .cornerRadius property is a disastrously expensive property that should only be used when there is no alternative. It is one of the least efficient, most render-intensive properties on CALayer (alongside shadowPath, masking, borders, etc). These properties trigger offscreen rendering to perform the clipping operation on every frame — 60FPS during scrolling! — even if the content in that area isn't changing. diff --git a/_docs/hit-test-slop.md b/_docs/hit-test-slop.md index 1eea8966..ee36b8da 100755 --- a/_docs/hit-test-slop.md +++ b/_docs/hit-test-slop.md @@ -2,7 +2,7 @@ title: Hit Test Slop layout: docs permalink: /docs/hit-test-slop.html -prevPage: drawing-priority.html +prevPage: layoutSpecs.html nextPage: batch-fetching-api.html --- diff --git a/_docs/layer-backing.md b/_docs/layer-backing.md index d86f4351..7e5df017 100755 --- a/_docs/layer-backing.md +++ b/_docs/layer-backing.md @@ -2,20 +2,29 @@ title: Layer Backing layout: docs permalink: /docs/layer-backing.html -prevPage: layout-options.html -nextPage: synchronous-concurrency.html +prevPage: placeholder-fade-duration.html +nextPage: subtree-rasterization.html --- -In some cases, you can substantially improve your app's performance by using layers instead of views. We recommend enabling layer-backing as a matter of course in any custom node that doesn't need touch handling. +In some cases, you can substantially improve your app's performance by using layers instead of views. We recommend enabling layer-backing as a matter of course in **any custom node that doesn't need touch handling**. With UIKit, manually converting view-based code to layers is laborious due to the difference in APIs. Worse, if at some point you need to enable touch handling or other view-specific functionality, you have to manually convert everything back (and risk regressions!). With all AsyncDisplayKit nodes, converting an entire subtree from views to layers is as simple as... -``` +
    +SwiftObjective-C +
    + 
     rootNode.layerBacked = YES;
-```
+
    + +
    +
    +
    ...and if you need to go back, it's as simple as deleting one line. diff --git a/_docs/layout-api-sizing.md b/_docs/layout-api-sizing.md index 8d43d03e..2efdc9c4 100644 --- a/_docs/layout-api-sizing.md +++ b/_docs/layout-api-sizing.md @@ -4,12 +4,6 @@ layout: docs permalink: /docs/layout-api-sizing.html --- -##Question - -"I don't think I have a clear understanding of `ASRelativeDimension` / `ASRelativeSizeRange`, and I often see many similar methods to create these structures." - -##Answer - The easiest way to understand the compound dimension types in the Layout API is to see all the units in relation to one another. diff --git a/_docs/node-overview.md b/_docs/node-overview.md index 74fcecba..aead8eff 100755 --- a/_docs/node-overview.md +++ b/_docs/node-overview.md @@ -1,5 +1,5 @@ --- -title: Node Overview & Hierarchy +title: Node Subclasses layout: docs permalink: /docs/node-overview.html prevPage: containers-aspagernode.html diff --git a/_docs/placeholder-fade-duration.md b/_docs/placeholder-fade-duration.md index b24cf27f..bfcd4648 100755 --- a/_docs/placeholder-fade-duration.md +++ b/_docs/placeholder-fade-duration.md @@ -3,7 +3,7 @@ title: Placeholder Fade Duration layout: docs permalink: /docs/placeholder-fade-duration.html prevPage: image-modification-block.html -nextPage: debug-tool-hit-test-visualization.html +nextPage: layer-backing.html ---
    😑 This page is coming soon...
    \ No newline at end of file diff --git a/_docs/subtree-rasterization.md b/_docs/subtree-rasterization.md index 27c3c9a9..a086cea3 100755 --- a/_docs/subtree-rasterization.md +++ b/_docs/subtree-rasterization.md @@ -2,16 +2,25 @@ title: Subtree Rasterization layout: docs permalink: /docs/subtree-rasterization.html -prevPage: synchronous-concurrency.html -nextPage: drawing-priority.html +prevPage: layer-backing.html +nextPage: synchronous-concurrency.html --- Flattening an entire view hierarchy into a single layer improves performance, but with UIKit, comes with a hit to maintainability and hierarchy-based reasoning. With all AsyncDisplayKit nodes, enabling precompositing is as simple as: -``` +
    +SwiftObjective-C +
    + 
     rootNode.shouldRasterizeDescendants = YES;
-```
+
    + +
    +
    +
    This line will cause the entire node hierarchy from that point on to be rendered into one layer. diff --git a/_docs/synchronous-concurrency.md b/_docs/synchronous-concurrency.md index 7cf0fa63..b7cebee9 100755 --- a/_docs/synchronous-concurrency.md +++ b/_docs/synchronous-concurrency.md @@ -2,8 +2,8 @@ title: Synchronous Concurrency layout: docs permalink: /docs/synchronous-concurrency.html -prevPage: layer-backing.html -nextPage: subtree-rasterization.html +prevPage: subtree-rasterization.html +nextPage: debug-tool-hit-test-visualization.html --- Both `ASViewController` and `ASCellNode` have a property called `neverShowPlaceholders`. @@ -23,5 +23,6 @@ node.neverShowPlaceholders = true +
    Usually, if a cell hasn't finished its display pass before it has reached the screen it will show placeholders until it has drawing its content. Setting this option to YES makes your scrolling node or ASViewController act more like UIKit, and in fact makes AsyncDisplayKit scrolling visually indistinguishable from UIKit's, except that it's faster. diff --git a/static/main.css b/static/main.css index 2e71e3a2..e6f58543 100755 --- a/static/main.css +++ b/static/main.css @@ -763,7 +763,7 @@ body { margin-top: 1em; font-family: BodyFontFamily,"Georgia Pro",Georgia,Times; margin: 0; - border-top: 3px #008ED4 solid; + border-top: 3px #1C9BC7 solid; background: #f8f7f5; border-radius: 4px; } @@ -781,3 +781,17 @@ pre { font-weight: 500; color: #333333; } + +.paddingBetweenCols th { + text-align: left; + padding: 15px 15px 15px 15px; +} + +.paddingBetweenCols td { + padding: 15px 15px 15px 15px; +/* border: 1 px solid black;*/ +} + +.paddingBetweenCols tr:nth-child(even){ + background-color: #f2f2f2 +}