ArcGIS API for JavaScript: CustomizingArcGIS API for JavaScript: CustomizingWidgetsWidgets

Alan Sangma – Alan Sangma –

Matt Driscoll – Matt Driscoll –

JC Franco – JC Franco –

@alansangma@alansangma

@driskull@driskull

@arfncode@arfncode

AgendaAgendaWhat can be customizedCustomization approaches with demosQ & A

Customizing WidgetsCustomizing WidgetsTheming

Changing styles: colors, sizing, font, etc.Implementing widget in a different frameworkAltering presentation of a widget

Customization ApproachesCustomization ApproachesAuthoring a themeRecreating a viewExtending a view

Level ILevel I

ThemingTheming

Level I: ThemingLevel I: ThemingWhy Theme?Why Theme?

Match branding.Match the map.Contrast with the map.Based on the environment.User-speci�c (e.g. bigger buttons)

Theming TechnologyTheming Technology

We use

to create our CSS.to create our CSS.

| nodejs.org gruntjs.com

is a powerful scripting language for compiling CSS.is a powerful scripting language for compiling CSS.

It's modular.It's DRY.It makes theming easy.

PREVIOUSLY ON THEMINGPREVIOUSLY ON THEMING

LIFE WAS HARD.

Before, you needed to

1. Pull down the API .2. Create a theme directory in the right place.3. Create a Sass �le.4. Import the core �le.5. Run the compiler.6. Wonder if there were an easier way.

(arcgis-js-api)

There is an easier way!There is an easier way!1. Get our theme utility.2. Use the utility.3. Customize your theme.4. Host your CSS �le.

There is an easier way!There is an easier way!1. Clone the utility jsapi-styles.git2. Run npm install3. Edit sass/my-theme/main.scss.4. See dist/my-theme/main.css.

You won't need the base stylesheet.

Step 1Step 1Clone the repo.

https://github.com/jcfranco/jsapi-styles

git clone https://github.com/jcfranco/interactive-design.git

Step 2Step 2npm install

Installs the necessary bits.Creates a sample theme directory.Compiles the CSS from the SCSS.Spins up a preview in your default browser.

Step 3Step 3Edit your theme.

sass/my-theme/main.scss

Optionally, edit your app. preview/index.html

Step 4Step 4Host your stylesheet and any relevant assets.

Link your stylesheet in your app.

<!-- In your app: --> <link href="path/to/your/theme/main.css" rel="stylesheet">

Let's have a look!Let's have a look!

Theme SmartTheme SmartAvoid adding additional CSS selectors.

Instead, use Sass to your advantage. Let's look at how the core theme is structured.

Theme StructureTheme StructureColor : colorVariables.scssSize : sizes.scssType : type.scss

Theme StructureTheme StructureDefaultDefault

Any value assignment overrides the !default value.

But wait...there's more!

// Inside base/_colorVariables.scss $background_color : #fff !default ;

// Inside sass/my-theme/main.scss $background_color : #cc4b09;

Theme StructureTheme StructureOverride the four main color variables...

...then magic!

$text_color : #fff; // white $background_color : #cc4b09; // mario $anchor_color : #ffbaaa; // luigi $button_text_color : #ffbaaa; // luigi

MagicMagic

$button_text_hover_color: offset-foreground-color($button_text_color, 25%) !default; $anchor_hover_color: offset-foreground-color($anchor_color, 25%) !default; $background_hover_color: offset-background-color($background_color, 5%) !default; // etc.

Theming Guide

So let's make a theme!So let's make a theme!

Level I: Theming RecapLevel I: Theming RecapUse the utility for easy theming.Theme structure

ColorSizeTypography

Use the core and override values.

LEVEL UP!LEVEL UP!

Ready?Ready?

LEVEL IILEVEL II

ViewsViews

Level II: Widget CompositionLevel II: Widget CompositionWidgets are composed of Views & ViewModels

ReusableUI replacementFramework integration

Level II: ViewsLevel II: ViewsPresentation of the WidgetUses ViewModel APIs to render the UIView-speci�c logic resides here

Level II: Working with ViewsLevel II: Working with ViewsAPI Exploration

Attribution DocAttribution Sample

Level II: Level II: AttributionViewModelAttributionViewModel// AttributionViewModel in 4.7 Release interface AttributionViewModel { items: Collection<AttributionItem>; state: "ready" | "disabled"; view: MapView | SceneView; } interface AttributionItem { layer: Layer; text: string; }

Views: Let's customize!Views: Let's customize!Lets create a custom widget view.

DemoDemoCreate a custom Attribution Table view

Demo StepsDemo CompleteDemo Start

Level II: Views RecapLevel II: Views RecapWhat have we learned about Widget Views?

Face of the widgetPresent ViewModel logicViewModel separation allows framework integration or custom viewsDownloadable on API docs

LEVEL UP!LEVEL UP!

Ready?Ready?

LEVEL IIILEVEL III

Extending a ViewExtending a View

Level III: Extending a ViewLevel III: Extending a ViewWhy?

ReusableSame ecosystem

How?JS API v4.7esri/widgets/WidgetTypeScript

esri/widgets/Widget

Provides lifecycleAPI consistency

LifecycleLifecycleconstructorpostInitializerenderdestroy

renderrenderDe�nes UIReacts to stateUses JSXVDOM

TypeScriptTypeScriptTyped JavaScriptJS of the future, nowIDE support

Visual StudioWebStormSublimeand more!

Demo: Extending a ViewDemo: Extending a View | Demo Steps

Level III: Extending a View RecapLevel III: Extending a View RecapReusable

View/ViewModelSame ecosystem

No extra librariesExtended existing widget

LifecycleTypeScript

LEVEL UP!LEVEL UP!

Ready?Ready?

LEVEL IVLEVEL IV

Put it all together.Put it all together.

ConclusionConclusionAuthored a themeRecreated a viewExtended a view

Additional ResourcesAdditional ResourcesImplementing AccessorSetting up TypeScriptWidget DevelopmentJS API SDK

Questions?Questions?For exampleFor example

� �

� Where can I �nd the slides/source?

esriurl.com/customwidgetsds2018