News!

• New Demo-3 branch contains a non-data-binding example
• Improvements to general API

Library for dynamically generating and animating skeleton drawables. This library can generate a drawable skeleton loader for any View or ViewGroup. Simply define the desired properties and the skeleton drawable will be generated for the ViewGroup and its children. It is that simple! Below you’ll find information on how to use this library. Medium Article

• Features
• Glossary
• Getting Started
• Functional Demos
• How can I use in my project?
  • Step 1
  • Step 2
  • Example Usage 1
  • Example Usage 2
• ViewGroup Skeleton Attributes
  • Skeleton
  • Bones
  • Shimmer Rays
• View Bone Attributes
  • Bones
  • Bone Shimmer Rays
• Using a Property Holder
  • Property Bones
  • Property Shimmer Rays
• Resources
• How does it work?
• Caveats, limitations and notes?
• Future plans
• Contribute
• Contact
• Disclaimers
• License

# Resources

For a more thorough guides and descriptions please look at the following links:

Skeleton Contains information about skeletons and their properties

Skeleton Bones Contains information about bones and their properties

Shimmer Rays Contains information about shimmer rays and their properties

Shimmer Rays Contains information about shimmer rays and their properties

Examples Contains examples and technical and technical guides

# Glossary

Skeleton: A drawable loader representation of a ViewGroup. The skeleton is the wrapper around the generated bones where each bone represents a view within the ViewGroup. The skeleton is in charge of managing and rendering each of the bones generated for each non-ignored view within the owner layout. Skeleton drawables are recommended over single Bone Drawables when possible since the a single drawable is used for representing a complex layout. The skeleton drawable is created and overlaid over the layout in order to render the bones and the visible shimmers. See Shimmer Rays, See Skeleton

Skeleton Bone: A bone drawable loader representation of a View. Bones are typically contained within a skeleton, but bones can also be on their own. When a bone is contained within a parent that is a SkeletonDrawable, the parent drawable is in charge of the rendering of said bone. Every detail of the bone can be customized in order to provide the best look. When a bone is not contained within a Skeleton, the bone is then an independent bone and has similar but limited functionality. The bone can have its own state and can display an overlay shimmer. Below you’ll find a list of properties that can be customized. Independent bones can share properties through a BonePropertyHolder, See Skeleton Bones

Shimmer Ray: The effect that overlays a skeleton or bone in order to communicate to the user that the View or ViewGroup is currently loading. Shimmer rays can be applied to both Skeletons and individual bones. Most aspects of the shimmer rays can be customized. See Shimmer Rays

# Features

• Lightweight and easy to use
• Non-invasive, No changes to existing code required.
• No layout nor view wrapping which creates complex hierarchies
• No mock layouts needed
• Pixel perfect skeleton bone placing
• Disposed when no longer needed
• No boilerplate
• Uses data binding
• Highly performant
• Extremely customizable
• Code-free use
  
  

# Getting started

Bones is highly customizable and provides you the freedom of creating concise skeletons that will fit your apps design seamlessly. Although the recommended way of using bones is to apply it and modify it using data-binding, it is possible to customize Bones by directly accessing its properties through an instance. Bones can be customized by creating an instance of a SkeletonDrawable or BoneDrawable and directly applying the desired properties to it. The properties can be modified using both builder and property accessors patterns. It can also be use with data-binding.

Examples and demos

Check out the demo branches in this project for demos. New demo-3 added which showcases skeleton drawables without data-binding

How can I use in my project?

Step 1

Add it in your root build.gradle at the end of repositories:

allprojects {
  repositories {
    maven { url 'https://jitpack.io' }
  }
}

Add as a dependency in you applications build.gradle.

dependencies {
  implementation 'com.github.EudyContreras:Skeleton-Bones:${lib_version}'
}

Step 2

Refer to a skeleton from any ViewGroup in order to apply a Skeleton effect to it and its child views

Example Usage 1:

<androidx.constraintlayout.widget.ConstraintLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/background"
    android:elevation="4dp"
    app:skeletonAnimateRestoredBounds="@{true}"
    app:skeletonAllowSavedState="@{true}"
    app:skeletonBoneColor="@{@color/bone_color}"
    app:skeletonBoneCornerRadius="@{Utils.getDp(10)}"
    app:skeletonBoneMaxThickness="@{Utils.getDp(12)}"
    app:skeletonBoneMinThickness="@{Utils.getDp(10)}"
    app:skeletonDissectLargeBones="@{false}"
    app:skeletonEnabled="@{viewModel.loading}"
    app:skeletonGenerateBones="@{true}"
    app:skeletonShimmerRayColor="@{@color/bone_ray_color}"
    app:skeletonShimmerRayCount="@{4}"
    app:skeletonShimmerRayInterpolator="@{@android:interpolator/accelerate_quad}"
    app:skeletonShimmerRaySharedInterpolator="@{true}"
    app:skeletonShimmerRaySpeedMultiplier="@{1f}"
    app:skeletonShimmerRayThickness="@{Utils.getDp(120)}"
    app:skeletonShimmerRayTilt="@{-0.2f}"
    app:skeletonTransitionDuration="@{200L}"
    app:skeletonUseStateTransition="@{true}"
    tools:background="@color/white">
</androidx.constraintlayout.widget.ConstraintLayout>

Example Usage 2:

You can use the available extension function

val viewGroup: ViewGroup = getSomeContainer()
viewGroup.applySkeletonDrawable().apply {  }

Use the builder pattern by calling build on the instance of the drawable

val viewGroup: ViewGroup = getSomeContainer()
SkeletonDrawable.create(viewGroup)
  .build()
  .setEnabled(true)
  .setAllowSavedState(true)
  .withShimmerBuilder { 
      setThickness(10.dp)
      setTilt(0.3f)
  }
  .setCornerRadius(10f)

You can use accessor patterns

val viewGroup: ViewGroup = getSomeContainer()
SkeletonDrawable.create(viewGroup).apply { 
    this.getProps().apply {
        this.enabled = true
        this.allowSavedState = true
        this.shimmerRayProperties.apply { 
            this.shimmerRayThickness = 10.dp
            this.shimmerRayTilt = 0.3f
        }
    }
}

The recommended way of applying a skeleton drawable is by using Bone’s data-binding properties/attributes. Here are the lists of the main properties that can be applied in order to achieve a desirable effect.

# ViewGroup Skeleton Attributes

These are the properties that can be access through any ViewGroup. Although, some of the following properties will also work when set from a View, the behaviour will be different.

• Properties that start with skeleton are applied to the actual skeleton ViewGroup which generates the bones.
• Properties that start with skeletonBone are applied to the children bone (Views) of the skeleton.
• Properties that start with skeletonShimmerRay are applied to the shimmer ray of the skeleton ViewGroup

# View Bone Attributes

The following are bone properties that can be access through any View. Some of these will not work when set from an independent BoneDrawable since they are meant only for virtually dependent bones within a Skeleton ViewGroup. For more information feel free to consult the Bone document. See Skeleton Bones

Each of the above attributes has documentation. Please consult the xml docs by hovering over the attribute in order to get a more detailed description of the attribute

# Using a Property Holder

BonePropertyHolder This is a fake View that can be added anywhere within the view hierarchy. It has the sole purpose of acting as a property holder that can later be referenced by any View (Bone). The bone created for that view will then clone the properties of the BonePropertyHolder in order to define its own properties. This is usually done when multiple views share a same independent style or behaviour.

The BoneProperty holder can make use of the following properties. For a detailed description of the properties and their effects please refer to the property guide.

A view can refer to a BonePropertyHolder using its id through the app:skeletonBonePropId attribute. In order to override the properties set in the referenced property holder, the attributes must be prepended with prop_. Example: app:prop_skeletonBoneColor

How does it work?

The library works by creating a drawable based on some View or ViewGroup. The drawable can listen to a state using data-binding. When the state is true the skeleton loader drawable is shown and animated if it has any shimmers added to it. Each skeleton drawable has a skeleton object and a skeleton manager which is in charge for manipulating the skeleton, the bones and the shimmer rays. Same applies to BoneDrawables. The skeleton is visually created based on the ViewGroup/View that the drawable was bound to and then added as an overlay. The skeleton loader drawables are added as temporary foreground drawables. Once the state of the loader changes to false, the skeleton or bone drawable is removed and the original foreground is restored given that one was previously present.

# Caveats, Limitations and Notes

BEWARE In order for the skeleton and bone drawables to be properly generated, there must be some pre-determined minimum set dimensions (Width and Height) for the none ignored children. This is needed in order to know how to visually build the bone representations of said children views.

Setting dimensions using the android:minWidth and/or the android:minHeight should suffice. Otherwise if the minWidth and/or minHeight are set using the skeleton binding properties app:skeletonBoneMinWidth and app:skeletonBoneMinHeight, the dimensions will then be applied to the view and restored once the loading state is set to false. (The content has loaded). Additionally restoring the bounds of the view once the content was loaded can be done using layout animations in order to provide a smoother user experience. This is optional and can be done by setting this to true skeletonAnimateRestoredBounds.

When the state of a bone is true (Loading) and if the skeletonBoneToggleView is set to true, the view which the bone represents is hidden. When this is the case, if the owner view of the bone has an elevation, fake shadows are generated under the bone. This is done to preserve the look and feel.

If the owner view of a bone does not have valid drawable bounds, meaning its height is less than bone’s set minimum height skeletonBoneMinThickness or if not set, the default minimum thickness which is 10dp, no bone will be generated for it. This is done to avoid generating bones that are too thin or barely visible.

# Future plans

• Facilitate use with Glide and other popular Image Loaders
• Allow defining styles for both the Skeleton and Bone drawables
• Bones should be able to have a set of enter/exit animations
  • Ex: Rectangular bones collapse to the left
  • Ex: Rectangular bones collapse to the center
  • Ex: Circular bones collapse to the center
    
    

Contribute

Please read Contributing for details about how to contribute, and the process for submitting pull requests to Bones

Authors

Eudy Contreras

Contact

If you wish to contact me, you can reach me through my LinkedIn or my EudyContrerasRosario@gmail.com">Email

Disclaimer

The avatar images are not created by me. They are amazing and I wanted to use them. If you are the author please contact me.

License

This project is licensed under the MIT License - see the Licence file for details