ArcGIS API for JavaScript: CustomizingArcGIS API for JavaScript: CustomizingWidgetsWidgets

Matt Driscoll – Matt Driscoll –

JC Franco – JC Franco –

@driskull@driskull

@arfncode@arfncode

AgendaAgendaWhat can be customizedCustomization approaches with demos

Customizing WidgetsCustomizing Widgets

Customizing WidgetsCustomizing WidgetsTheming

Changing styles: colors, sizing, font, etc.

Customizing WidgetsCustomizing WidgetsTheming

Changing styles: colors, sizing, font, etc.Altering presentation of a widget

New viewRecreating a view

Customizing WidgetsCustomizing WidgetsTheming

Changing styles: colors, sizing, font, etc.Altering presentation of a widget

New viewRecreating a view

ExtendingOverriding, adding functionality

Customization ApproachesCustomization Approaches

Customization ApproachesCustomization ApproachesAuthoring a theme

Customization ApproachesCustomization ApproachesAuthoring a themeRecreating a view

Customization ApproachesCustomization ApproachesAuthoring a themeRecreating a viewExtending a view

Part IPart IThemingTheming

Part I: ThemingPart I: Theming

Part I: ThemingPart I: ThemingWhy Theme?Why Theme?

Part I: ThemingPart I: ThemingWhy Theme?Why Theme?

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

Esri ThemesEsri Themes10 themes are provided out-of-the-box:

Using a theme requires only a slight update to the CSS path.

<link rel="stylesheet" href="https://js.arcgis.com/<version>/esri/themes/<theme-name>/main.css" />

Theme Switcher

Out-of-the-box themes

Theming TechnologyTheming Technology

We use

to create our CSS.to create our CSS.

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.

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.

Theming StepsTheming Steps

Theming StepsTheming Steps1. Get our theme utility.2. Use the utility.3. Customize your theme.4. Host your CSS �le.

Step 1Step 1Clone the repo.

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

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

Step 2Step 2npm install

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

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" />

GoalsGoalsTheme Smart

Avoid adding additional CSS selectorsInstead, use Sass to your advantage

Theme StructureTheme StructureLet's look at how the core theme is structured

Color Size Type

Theme StructureTheme StructureLet's look at how the core theme is structured

Color : _color.scssSize : _sizes.scssType : _type.scss

Theme StructureTheme StructureDefaultDefault

Any value assignment overrides the !default value.

// Inside base/_color_.scss$background-color: #fff !default;

// Inside sass/my-theme/main.scss$background-color: #1e0707;

Theme StructureTheme StructureDefaultDefault

Any value assignment overrides the !default value.

But wait...there's more!

// Inside base/_color_.scss$background-color: #fff !default;

// Inside sass/my-theme/main.scss$background-color: #1e0707;

Theme StructureTheme StructureOverride the core color variables...

$font-color: #3a5fe5; $interactive-font-color: #ff1515; $background-color: #1e0707; $button-color: #8070cc;

Theme StructureTheme StructureOverride the core color variables...

...then magic!

$font-color: #3a5fe5; $interactive-font-color: #ff1515; $background-color: #1e0707; $button-color: #8070cc;

MagicMagicUsing $button-color we "automagically" set the hover color.

$button-color--hover: darken($button-color, 10%) !default; // ...etc

API Styling Guide

Part I: Let's make a themePart I: Let's make a theme

Custom Theme

| Preview Demo Steps

Part I: Theming RecapPart I: Theming RecapUse the utility for easy theming.Theme structure

ColorSizeTypography

Use the core and override values.

End Part IEnd Part I

Part IIPart IIViewsViews

Part II: Widget CompositionPart II: Widget CompositionWidgets are composed of Views & ViewModels

Part II: Widget CompositionPart II: Widget CompositionWidgets are composed of Views & ViewModels

Logic is separate from presentationReusableUI replacementFramework integration

Part II: TypeScriptPart II: TypeScriptWidgets written in TypeScript (Typed JavaScript)

Part II: TypeScriptPart II: TypeScriptWidgets written in TypeScript (Typed JavaScript)JS of the future, now

Part II: TypeScriptPart II: TypeScriptWidgets written in TypeScript (Typed JavaScript)JS of the future, nowIDE support

Visual StudioWebStormSublimeand more!

Part II: ViewsPart II: Views

Part II: ViewsPart II: ViewsPresentation of the WidgetUses ViewModel APIs to render the UIView-speci�c logic resides hereExtend esri/widgets/Widget

Part II: Widget ClassPart II: Widget Classesri/widgets/Widget

Part II: Widget ClassPart II: Widget Classesri/widgets/Widget

Provides lifecycleAPI consistency

Part II: Widget LifecyclePart II: Widget Lifecycle

Part II: Widget LifecyclePart II: Widget Lifecycle constructor

Part II: Widget LifecyclePart II: Widget Lifecycle constructor

postInitialize

Part II: Widget LifecyclePart II: Widget Lifecycle constructor

postInitialize render

Part II: Widget LifecyclePart II: Widget Lifecycle constructor

postInitialize render destroy

Part II: Part II: renderrender

Part II: Part II: renderrenderDe�nes UIReacts to stateUses JSXVDOM

Part II: Working with ViewsPart II: Working with ViewsAPI Exploration

ScaleRangeSlider DocScaleRangeSlider Demo

Part II: Recreating a viewPart II: Recreating a viewCustom ScaleRangeSlider

Part II: CustomScaleRangeSlider InterfacePart II: CustomScaleRangeSlider Interfaceinterface CustomScaleRangeSlider { layer: Layer; // aliased rangeType: "to" | "from"; region: string; // will use to get thumbnails view: MapView | SceneView; // aliased viewModel: ScaleRangeSliderViewModel; // handling logic! }

Recreating a view

| | Demo Start Demo Steps ScaleRangeSlider Doc

Part II: Views RecapPart II: Views RecapWhat have we learned about Widget Views?

Part II: Views RecapPart 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

End Part IIEnd Part II

Part IIIPart IIIExtending a ViewExtending a View

Part III: ExtendingPart III: Extending

Part III: ExtendingPart III: ExtendingWhy?

Part III: ExtendingPart III: ExtendingWhy?

Reusable

Part III: ExtendingPart III: ExtendingWhy?

ReusableSame ecosystem

Part III: ExtendingPart III: ExtendingWhy?

ReusableSame ecosystem

How?

Part III: ExtendingPart III: ExtendingWhy?

ReusableSame ecosystem

How? Leveragingesri/widgets/Widget

Part III: ExtendingPart III: ExtendingWhy?

ReusableSame ecosystem

How? Leveragingesri/widgets/WidgetAPI widget views

Part III: Extending a ViewPart III: Extending a ViewCustomScaleRangeSlider (revisited)

| | API Reference Demo Steps

Part III: Extending a View RecapPart III: Extending a View Recap

Part III: Extending a View RecapPart III: Extending a View RecapReusable

View/ViewModel

Part III: Extending a View RecapPart III: Extending a View RecapReusable

View/ViewModelSame ecosystem

No extra libraries

Part III: Extending a View RecapPart III: Extending a View RecapReusable

View/ViewModelSame ecosystem

No extra librariesExtended existing widget

LifecycleTypeScript

End Part IIIEnd Part III

ConclusionConclusion

ConclusionConclusionAuthored a theme

ConclusionConclusionAuthored a themeRecreated a view

ConclusionConclusionAuthored a themeRecreated a viewExtended a view

Additional ResourcesAdditional ResourcesImplementing AccessorSetting up TypeScriptWidget DevelopmentStylingArcGIS API for JavaScript - next

You might also be interested in...You might also be interested in...ArcGIS API for JavaScript: Getting Started with Web DevelopmentArcGIS API for JavaScript: Using TypeScriptArcGIS API for JavaScript: Tips and Tricks for Developing and Debugging AppsBuilding Light-Weight Map Authoring Web AppsArcGIS API for JavaScript: Building Your Own Widget

Questions? 🤔Questions? 🤔Where can I �nd the slides/source?

bit.ly/buildwidgetsds20

Where can I submit a question?

bit.ly/askjsapi