ShinobiEssentials is a collection of user interface controls for iOS, created by ShinobiControls.

Installing the ShinobiEssentials framework

ShinobiEssentials now ships with an installer, to make it easier to get started. To run the installer, run the ShinobiEssentials.dmg file which you downloaded from ShinobiControls. When it opens up, it should look as below.

The easiest way to install the ShinobiEssentials framework is to run the install.pkg file. This will install the framework into Xcode for you, along with the framework documentation. This means you can add the framework to your project in the same way as you would any of the frameworks which are automatically shipped with Xcode.

If you don’t want to run the installer, the framework is also contained within the ShinobiEssentials folder in the disk image. Regardless of whether you ran the installer, you will need to copy this folder onto your machine, so let’s do that now. Drag the ShinobiEssentials folder onto the Desktop icon in the disk image. This will copy the folder onto your desktop.

The ShinobiEssentials folder contains:

  • A copy of the framework.
  • The ShinobiEssentials.bundle file which contains all the resources which the framework needs.
  • A copy of the documentation for the framework.
  • A set of samples to demonstrate getting started with ShinobiEssentials.
  • An uninstall script for uninstalling the ShinobiEssentials framework from Xcode.
  • The Xamarin.iOS version of the framework.
  • A README file with setup steps.
  • A text file containing the version number.
  • A copy of the ShinobiControls license.
  • A change log containing the changes made to this release.

Adding ShinobiEssentials to your project

To add ShinobiEssentials to your Xcode project, you need to add a reference to the ShinobiEssentials framework, and the bundle which contains its resources. There are two ways of doing this:

  • If you have run the Essentials installer, the easiest way to add the framework is to open up the project window, go to the Build Phases tab, and select to add frameworks in the “Link Binary With Libraries” section. In the menu which is displayed, select ShinobiEssentials.framework.
  • If you didn’t run the pkg installer, you can drag the framework into your project from the ShinobiEssentials folder on your desktop.

Once you have added the ShinobiEssentials.frameworkto your project, you will need to add theShinobiEssentials.bundle, so that the framework has all of the resources it needs. Drag this file from theShinobiEssentials folder on your desktop into your project.

ShinobiEssentials makes use of the QuartzCore.framework, so you should add this to your project from the “Link Binary With Libraries” section of the project window. Trial users will need to import Security.framework too.

To check you have done all of this correctly, open up the project window, go to the Build Phases tab and check that ShinobiEssentials.framework and QuartzCore.framework are both under “Link Binary With Libraries”, and that ShinobiEssentials.bundle is listed under “Copy Bundle Resources”.

Individual Control User Guides

This page has a brief overview of each of the controls, and then a full description of the API.

SEssentialsCarousel SEssentialsSlidingOverlay SEssentialsFlowLayout
SEssentialsTabbedView SEssentialsProgressIndicator SEssentialsAccordion
SEssentialsPullToAction

Carousel

The SEssentialsCarousel provides an easy way to layout and display views on screen, in any 2D or 3D configuration. The SEssentialsCarousel is a family of components, each providing different layout appearances, such as a Cover Flow, Linear, or Cylindrical layouts.

For more information, have a look at the UserGuide.

Sliding Overlay

The SEssentialsSlidingOverlay component offers an easy way to show and hide a small panel, allowing it to be shown when needed, without it taking up screen space when it is no longer required. It works in a similar way to the UISplitViewController, but while the Split View Controller only displays both views in landscape, and only one in portrait, the Sliding Overlay allows you to hide or display the underlay whenever you need to.

For more information, have a look at the UserGuide.

Flow Layout

The SEssentialsFlowLayout provides an easy way to layout and display views on screen. The views are arranged in a raster fashion, in the order they are provided to the control. The default behavior supports an edit mode in which the user can reorder and remove the views. Views can be removed from the flow layout using one of 2 delete idioms - one matching the iOS home screen icon management, and the other providing a trash can to which the views can be dragged.

For more information, have a look at the UserGuide.

Tabbed View

The SEssentialsTabbedView provides an easy way to display and navigate between multiple views using a single viewport, in a similar way to tab separators in paper documents. Tabs can be added, removed, and rearranged by default, or locked in position.

For more information, have a look at the UserGuide.

Progress/Activity Indicators

ShinobiEssentials contains 2 different indicator types (progress and activity) in a multitude of configurations. Progress indicators can be used to inform the user of the proportion of given task which has been completed (for tasks when such values can be calculated), whereas activity indicators are used to advise that the device is busy, or waiting for something.

The UserGuide describes the different indicator types available and goes into detail about how they can be used.

Accordion

The SEssentialsAccordion provides a control with expandable sections, allowing content to be shown and hidden. Accordions may be fixed, where only one section is open at a time, or flexible, where many sections can be open and closed.

For more information, have a look at the UserGuide.

Pull to Action

The SEssentialsPullToAction is used in conjunction with a UIScrollView allowing users to trigger an event (such as refreshing content) by pulling the scroll view down past a custom threshold. Whilst your users interact with the scroll view, the Pull to Action component will pass through various states, updating its appearance accordingly.

For more information, have a look at the UserGuide.

Common Concepts

There are some concepts which are common to all ShinobiEssentials controls:

Setting The License Key

ShinobiControls trial downloads require a license key to work. If you have downloaded a trial version of ShinobiEssentials you will have been issued with a trial license key. Add the key that you were supplied with at the location indicated below.

AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [ShinobiEssentials setLicenseKey:@""]; // Add license key here
  ...

or

ViewController.m

- (void)viewDidLoad
{
  [ShinobiEssentials setLicenseKey:@""]; // Add license key here
  ...

The license key can be set in the ViewController or the AppDelegate, so long as it is set before any SEssentials controls are created. It only needs setting once across the whole application.

Note: Full featured versions of ShinobiControls do not require a license key to be set in code.

Styling and Theming

Each ShinobiEssentials control has a an instance of a SEssentialsStyle object associated with it. To configure the look and feel of a control, you should update the style object which is associated with it. The available style objects are as follows:

Each style object is created with an instance of a SEssentialsTheme. This defines the default settings of the style object. You can either define your own theme object, or you can use the global one, which is provided by SEssentials. If you don’t specify a theme when you create a style object, the global one is used. To get the global theme, you can use the following code:

SEssentialsTheme *globalTheme = [ShinobiEssentials theme];

If you would like to set the global theme across your application, you can do it like so:

[ShinobiEssentials setTheme:newTheme];

The advantage of using a theme object to set the defaults of your style is that you can style multiple controls in your app to have the same look and feel.

SEssentialsTheme defines a set of generic properties, which individual style objects can then utilize for their specific needs. The properties defined are:

  • A palette of colors to use within a control.
  • A set of textures which can be used for sub-components of a control.
  • A set of fonts and text colors which can be used within a control.

We also use the concept of decoration when configuring the look and feel of ShinobiEssentials controls. This refers to things such as shine, shadowing or chisel effects which are applied to the controls. In iOS7, we tend to turn off shine or shadowing effects, or at least make them a lot more subtle. In earlier versions of iOS, we use shine and shadowing effects to make items look more realistic. Chisel effects are applied in all versions of iOS, although again, they are more subtle in iOS7.

The properties on the SEssentialsTheme are used by controls according to the table below;

Accordion Carousel Flow Layout Indicators Pull to Action Sliding Overlay Tabbed View
Color Palette
primaryTintColor
secondaryTintColor
tertiaryTintColor
activeTintColor
inactiveTintColor
Textures
primaryTexture
secondaryTexture
Text
primaryFont
primaryTextColor
secondaryFont
secondaryTextColor
Decoration
primaryDecorationTintColor
secondaryDecorationTintColor
shadowColor
shadowDepth
shineColor
elementStyle
Accordion Carousel Flow Layout Indicators Pull to Action Sliding Overlay Tabbed View

Once you’ve created a style object, you can configure it in a couple of ways:

  • Change the values of the properties on the style. This gives you fine-grained control over the style.
  • If you want to reconfigure a style object from a theme, for example if you’re applying a common theme to a number of controls in your app, you can apply the theme to the style. This is done by calling the applyTheme: method on the style. For convenience, and to be consistent with other Shinobi controls, you can also call applyTheme: on all of the Essentials controls themselves. This will have the same effect.

Decorated Views

SEssentialsDecoratedView allows for decoration to be added to the wrapped UIView. This allows for effects, such as reflection and shadows, to be applied to the view, which update as the wrapped view is updated.

For more information on the individual effects, see the relevant class SEssentialsDecoratedShadowedView, SEssentialsDecoratedFadedView, SEssentialsDecoratedReflectedView, SEssentialsDecoratedDoubleSidedView, SEssentialsDecoratedCachedView.

For example use the following code

UIView *blueView = [ [ UIView alloc] initWithFrame:frame ];
blueView.backgroundColor = [ UIColor blueColor];
SEssentialsDecoratedReflectedView *reflected = [ [ SEssentialsDecoratedReflectedView alloc] initWithView:blueView ];

To create a reflecting view that looks like this

Effects can be chained together to allow for multiple effects. For example, to add fading around the edges of a view, then reflect it;

SEssentialsDecoratedFadedView *faded = [ [ SEssentialsDecoratedFadedView alloc ] initWithView:view ];
SEssentialsDecoratedReflectedView *reflected = [ [ SEssentialsDecoratedReflectedView alloc] initWithView:faded ];

The SEssentialsDecoratedDoubleSidedView is for use in the cylindrical carousel, it allows an item to have a defined view that will show when the item rotates away from the camera as it moves around the back of the carousel. For an example of this see the how-to section of the SEssentialsCarousel User Guide

Trouble shooting

If you encounter problems that the documentation cannot answer then the first port of call should be ShinobiDeveloper and the Blog. If you still can’t find an answer, then please do get in touch.