DOCSEARCHbyAlgolia
Submit Docs

EmptyDataSet-Swift

repository·master·Indexed 20 days ago

https://github.com/waizeiaifu/emptydataset-swift

A Swift implementation inspired by DZNEmptyDataSet that provides a customizable superclass category for UITableView and UICollectionView to display empty states. It allows developers to define visual elements via the EmptyDataSetSource protocol, handle interactions through the EmptyDataSetDelegate protocol, or configure views using a builder-like extension.

Tokens
1.7K
Snippets
4
Records
6
Agent score
22%

What's inside EmptyDataSet-Swift

  1. Display a CustomView for the empty state

    master

    You can display a completely custom view instead of the default title/image/button layout.

    Important Rules:

    1. Conflict Resolution: If you set customView via EmptyDataSetSource, other settings (like title/image) will be ignored. If you set it via the emptyDataSetView extension, AutoLayout for other elements will be invalid.
    2. Positioning: The customView is centered in the tableView.
    3. Alignment: You can adjust the vertical position using verticalOffset(forEmptyDataSet:) in the source or .verticalOffset() in the extension.
    4. Sizing: The view's size is determined by its frame. However, if the view is a UILabel with a CGRect.zero frame, its width and height will be determined by its content via AutoLayout.

    Example (Source Protocol):

    func customView(forEmptyDataSet scrollView: UIScrollView) -> UIView? {
    let view = CustomView(frame: CGRect(x: 0, y: 0, width: 150, height: 150))
    return view
}

func verticalOffset(forEmptyDataSet scrollView: UIScrollView) -> CGFloat {
    return 200
}
    func customView(forEmptyDataSet scrollView: UIScrollView) -> UIView? {
    let view = CustomView(frame: CGRect(x: 0, y: 0, width: 150, height: 150))
    return view
}

  2. Install EmptyDataSet-Swift via CocoaPods or Carthage

    master

    You can integrate EmptyDataSet-Swift into your iOS project using either CocoaPods or Carthage.

    CocoaPods Add the following to your Podfile:

    pod 'EmptyDataSet-Swift', '~> 5.0.0'

    Carthage Add the following to your Cartfile:

    github "Xiaoye220/EmptyDataSet-Swift" "4.2.0"
    pod 'EmptyDataSet-Swift', '~> 5.0.0'

  3. Use EmptyDataSet-Swift with EmptyDataSetSource and EmptyDataSetDelegate

    master

    The standard way to use the library is by conforming your UITableViewController or UICollectionView controller to EmptyDataSetSource and EmptyDataSetDelegate.

    1. Import EmptyDataSet_Swift.
    2. Set the emptyDataSetSource and emptyDataSetDelegate on your table view or collection view in viewDidLoad().
    3. Implement the required protocol methods to provide content (title, description, image, etc.) and handle events (taps, appearance changes).
    import EmptyDataSet_Swift

class OriginalUsageViewController: UITableViewController, EmptyDataSetSource, EmptyDataSetDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        tableView.emptyDataSetSource = self
        tableView.emptyDataSetDelegate = self
    }
}

  4. Configure empty state using the emptyDataSetView extension

    master

    If you prefer not to conform to protocols, you can use the emptyDataSetView closure extension on UITableView (or UICollectionView) to configure the view using a builder-like pattern.

    tableView.emptyDataSetView { view in
    view.titleLabelString(titleString)
        .detailLabelString(detailString)
        .image(image)
        .imageAnimation(imageAnimation)
        .buttonTitle(buttonTitle, for: .normal)
        .buttonTitle(buttonTitle, for: .highlighted)
        .buttonBackgroundImage(buttonBackgroundImage, for: .normal)
        .buttonBackgroundImage(buttonBackgroundImage, for: .highlighted)
        .dataSetBackgroundColor(backgroundColor)
        .verticalOffset(verticalOffset)
        .verticalSpace(spaceHeight)
        .shouldDisplay(true, view: tableView)
        .shouldFadeIn(true)
        .isTouchAllowed(true)
        .isScrollAllowed(true)
        .isImageViewAnimateAllowed(isLoading)
        .didTapDataButton { /* action */ }
        .didTapContentView { /* action */ }
}
    tableView.emptyDataSetView { view in
    view.titleLabelString(titleString)
        .detailLabelString(detailString)
        .image(image)
        .imageAnimation(imageAnimation)
        .buttonTitle(buttonTitle, for: .normal)
        .buttonTitle(buttonTitle, for: .highlighted)
        .buttonBackgroundImage(buttonBackgroundImage, for: .normal)
        .buttonBackgroundImage(buttonBackgroundImage, for: .highlighted)
        .dataSetBackgroundColor(backgroundColor)
        .verticalOffset(verticalOffset)
        .verticalSpace(spaceHeight)
        .shouldDisplay(true, view: tableView)
        .shouldFadeIn(true)
        .isTouchAllowed(true)
        .isScrollAllowed(true)
        .isImageViewAnimateAllowed(isLoading)
        .didTapDataButton { 
            // Do something
        }
        .didTapContentView { 
            // Do something
        }
}

  5. Implement EmptyDataSetDelegate to handle events and behavior

    master

    The EmptyDataSetDelegate protocol allows you to control the behavior and respond to interactions within the empty dataset view.

    Behavioral Controls:

    • emptyDataSetShouldFadeIn(_:): Return true to enable fade-in animation (default: true).
    • emptyDataSetShouldBeForcedToDisplay(_:): Return true to show the empty state even if items exist (default: false).
    • emptyDataSetShouldDisplay(_:): Return true to allow rendering (default: true).
    • emptyDataSetShouldAllowTouch(_:): Return true to allow user interaction (default: true).
    • emptyDataSetShouldAllowScroll(_:): Return true to allow scrolling (default: false).
    • emptyDataSetShouldAnimateImageView(_:): Return true to enable image animations (default: false).

    Event Callbacks:

    • emptyDataSet(_:didTapView:): Triggered when the empty dataset view is tapped.
    • emptyDataSet(_:didTapButton:): Triggered when the action button is tapped.
    • emptyDataSetWillAppear(_:), emptyDataSetDidAppear(_:), emptyDataSetWillDisappear(_:), emptyDataSetDidDisappear(_:): Lifecycle callbacks for the empty state visibility.

  6. Implement EmptyDataSetSource to provide dataset content

    master

    The EmptyDataSetSource protocol is used to define the visual elements of the empty state. Key methods include:

    • title(forEmptyDataSet:): Returns an NSAttributedString? for the title.
    • description(forEmptyDataSet:): Returns an NSAttributedString? for the description.
    • image(forEmptyDataSet:): Returns a UIImage?.
    • imagetintColor(forEmptyDataSet:): Returns a UIColor? for the image.
    • imageAnimation(forEmptyDataSet:): Returns a CAAnimation? for animating the image.
    • buttonTitle(forEmptyDataSet:for:): Returns an NSAttributedString? for specific button states.
    • buttonImage(forEmptyDataSet:for:): Returns a UIImage? for specific button states.
    • buttonBackgroundImage(forEmptyDataSet:for:): Returns a UIImage? for the button background.
    • backgroundColor(forEmptyDataSet:): Returns a UIColor? for the dataset background.
    • customView(forEmptyDataSet:): Returns a UIView? to replace the default labels/image/button layout.
    • verticalOffset(forEmptyDataSet:): Returns a CGFloat for vertical alignment.
    • spaceHeight(forEmptyDataSet:): Returns a CGFloat for vertical spacing between elements.