Presentation about SPEAK – 15 September 2017 Bialystok

On 15 September in Bialystok I had a pleasure to talk about SPEAK 2.

During presentation I showed how to start working with Sitecore and how to prepare own custom components.

It was great to share that knowledge and answer to many questions about basic and more advanced stuff.

Few photos from the event:

 

Sitecore SPEAK 2 – Stage 2- creation of custom component

I had an opportunity to work again with SPEAK 2 and I have got few new tips for you.

If you have not seen yet my previous article – you can (if you are new in SPEAK you should) check it here. You have seen it? – great, we can move forward.

How to create custom component in SPEAK 2

I was looking for the answer for some time and I have found many blog posts which are not up to date – every time when I was trying to run the code, something was wrong. Hopefully my solution will work longer and for everyone 🙂

Before we will start – remember one thing – location of files and items is extremely important in SPEAK2.

To create custom component you need to prepare following things:

  • item in core database – to define the component
  • cshtml file to define how it looks like
  • JavaScript file to define how it works

Item with definition in core database

In manuals on the internet you will find the information that you can put custom component in the structure tree below your SPEAK application – in this case structure would look like this:

- YOUR'S SPEAK APP
 -- Renderings Folder
 --- Definition of the custom rendering

Probably it would work for SPEAK1 but will not work for SPEAK2. In new version of SPEAK you should put all your components in the place where all predefined components are “/sitecore/client/Business Component Library/version 2/Layouts/Renderings”.

So we are starting from creation of new directory for the component:

Then inside this directory we have to create definition of our component:

As you probably have noticed it is just a “View Rendering”. Inside this item we should define values at least for following fields:

  • Path (path to the file with view)
  • Model (definition of model which we want to use in our view – in my case I took just one prepared by Sitecore)
  • Parameters Template (item with configuration of parameters for the component)

Ok, before we will select value in Parameters Template field we have to create the configuration item – it should be placed below the Custom Component.

Yes it is template and it is a good idea to inherit fields from one of available base templates.

In my case I have selected “ButtonControlBase” template – later you can specify “__Standard Values” item.

Great – we have definition of our component – it is time for some coding.

File with definition of view

Files, exactly as items, should be placed in particular directory. In the case of our component it will be:

\sitecore\shell\client\Business Component Library\version 2\Layouts\Renderings\CustomComponent

Inside this path we can then create CustomComponent.cshtml file with content:

So at the end it will look like this:

Ok, we have our view – it is time for some JavaScript.

File with JavaScript code

JavaScript file should be placed in the same directory as cshtml file.

When we develop new component we should always define “initialize” function which will be called every time when our component will be displayed. We can also define own functions  – like I defined “getTheListOfComponents”.

My function is taking the list of components from the application and then display some html.

As you can see there – I use “Sitecore.Speak” in JavaScript code – it is JavaScript object provided by Sitecore.

Inside Sitecore.Speak you will find a lot of useful functions and properties. Just open your browser console and play with it.

What next?

At this point you should have defined component with some HTML and JavaScript – it means that you should be able to use that component in the same way as others developed and provided by Sitecore.

To test our new component you need to define own application (If you do not know how to do this – check my previous post about SPEAK).

There is one extremely important thing which you have to check before you will put any SPEAK2 component in your application – configuration of the PageCode component. 

Open “Design Layout” for your page and check the properties of “PageCode”. In the field “SpeakCoreVersion” you should have selected value “SPEAK 2-x”.

Now, when we are sure that everything is set properly – it is time to add new rendering to our application.

When your’s component is added – remember to define properly “PlaceholderKey” to be sure that your component will be visible.

In my case it is “ApplicationContent.Main” – but it strongly related to the structure of your application.

As a result you will see your content from the view:

That is cool! But you probably remember that we had also a custom function “getTheListOfComponents” – it is time to use it!

We can call our function from many places – to be honest, from every place where Sitecore.Speak object is available. We just need to use code:

Sitecore.Speak.app.COMPONENT_ID.FUNCTION()

In my example I will use button. Below the custom component I added Button rendering and I set the value “javascript:app.CustomComponent1.getTheListOfComponents()” in “Click” field:

Finally we have component and the button:

When we will click the button – our action will trigger the function from the Custom Component and will display the list of components inside it.

It is alive! What means that you can do with it everything what you want – have a fun 🙂

 

Common issue

During development of my custom component I had and error message from Sitecore JavaScript library.

"Uncaught TypeError: Cannot read property 'model' of undefined"

Error was thrown from scSpeakPresenter.js file

More interesting was the fact that this part of code is not called by existing Sitecore components – it is called only when you register own components.

At this level you can also notice that even when we call SPEAK 2 components they are loaded with SPEAK 1 url

~/speak/v1

It means that we have there routing and behind it we have some code which search for particular files to load all ingredients of the component.

Because of that if you will put your files in wrong directory you will see an error similar or exactly the same which I had – check locations of your files once again. The second option – you forgot about the SpeakCoreVersion setting inside PageCode properties.

SPEAK 2.0 – STAGE 1

I have decided to create first ever tutorial for SPEAK 2.0 which will give you really working examples.

Why? Because I was not able to find any information about that and I was not sure which version should I choose for greenfield projects (1.2 or 2.0).

I hope I will be able to answer for all your questions in this and all future articles.

Do not hesitate to ask when you will have any additional questions.

Before we will start, please remember – if you want to work with SPEAK you have to:

  • work on core database
  • use Sitecore Rocks for Visual Studio

SPEAK 2.0 guidance

Sitecore with second verions of SPEAK provides us something new – the guidance. Inside core database under the path:

/sitecore/client/Business Component Library/version 2/Content/Guidance/Dashboard

We can find SPEAK application with all available SPEAK 2.0 components.

Application looks in the following way:

2016-08-13_16h08_54

Under the url

/sitecore/client/Business Component Library/version 2/Content/Guidance/AllComponentsList

we can see all available components but this time as a list. The number of components is really impressive. We can use following components:

Category Component Name
Authentications AccountInformation
Charts LineChart
Charts RadarChart
Charts AreaChart
Charts BarChart
Charts ColumnChart
Charts DoughnutChart
Charts PieChart
Common BackButton
Common Button
Common CheckBox
Common DropDownButton
Common DropList
Common GlobalLogo
Common HyperlinkButton
Common Image
Common ListBox
Common MessageBar
Common ProgressBar
Common SearchableDropList
Common Separator
Common ButtonTextBox
Common Text
Common TextBox
Common TextArea
Common ToggleButton
Common ChildRenderer
Common ItemRenderer
Common PageCode
Common RenderView
Common SubPageCode
Containers Border
Containers Expander
Containers Frame
Containers ScrollablePanel
Containers SubAppRenderer
Containers TabControl
Containers Popover
Data QueryDataSource
Data SearchDataSource
Data EntityDataSource
Data BaseDataSource
Data ChartDataSource
Data GenericDataSource
Dialogs ConfirmationDialog
Dialogs DialogWindow
Forms Form
Forms Uploader
Forms UploaderInfo
Indicators ArrowIndicator
Indicators ValueLabel
Lists and Grids Grid
Lists and Grids ListControl
Navigation Breadcrumb
Navigation Menu
Navigation NavigationToggle
Resources Pipeline
Resources Rule
Structures Page Structures
Structures Substructures

Sitecore also provides us a list of all available properties which defines the components behavior. List is available under the url:

/sitecore/client/Business Component Library/version 2/Content/Guidance/AllComponentProperties

It is really long list – so i will not paste it here.

SPEAK 2.0 page branches

In previous version of SPEAK we had possibility to use branches for faster creation of pages. We could find them under the path:

/sitecore/client/Business Component Library/version 1/Templates/Branches

Unfortunately they are currently not available for SPEAK 2.0.

That is why I prepared a branch for dashboard. You can download Sitecore package with this branch from here: SPEAK 2.0 Branches-1.0

Install this package in your Sitecore instance. If you will create a page with my template branch you will be able to see following page:

2016-08-13_16h56_25

Nothing special – that’s right, but it is looking exactly the same as page created from SPEAK 1.2 template branch. If you will compare “Design Layout” definitions you will find many differences.

Your first SPEAK application in 4 simple steps

  1. Open Core database inside Sitecore Rocks 2016-08-13_20h18_44
  2. Create your application directory under path “/sitecore/client/Your Apps” (my application name is “Speak2”)
  3. Add first item to your application – page which is based on DashboardPage branch from “SPEAK 2.0 Branches” package 2016-08-13_20h28_42As result you should see item with PageSettings item under your page item. 2016-08-13_20h32_11
  4. Open your application in browser – use item path and paste it into the browser.

Congratulations – you have created your first SPEAK 2.0 application!

Check also “Design Layout” properties for your Dashboard item. You should have following renderings:

2016-08-13_20h37_47

 

What will be next?

In next article I will show you how to build SPEAK 2.0 application with ListControl.

More about SPEAK 2.0