Component in SPEAK 1.2 - Client Side

SPEAK 1.2 is not realeased yet

SPEAK 1.2 comes with a new javascript API which we think will be much more simple to use.

What are the main differences with SPEAK 1.1

The component in 1.2 are really unopinonated. In SPEAK 1.1, we were forcing you to use requirejs, backbone, jquery, knockout.

The consequence was you needed to learn a lot of those APIs in order to understand how to create a simple component. In addition to that, you also needed to understand how SPEAK was implementing it. This was clearly a bad choice on the learning curve point of view.

Of course, if you want to build really really complex component, you will end-up to use some of the libraries listed above but at least now they are no more required.

In SPEAK 1.2, you decide which library you want to use to build your components. If you are an experienced Javascript developer, we let you the opportunity to create vanilla javascript component. No dependency at all (except SPEAK of couse).

We have also introduced a new syntax to create component:

Sitecore.component({  
  name: "MyFirstComponent",
  initialize: function () {
  },
  doSomething: function () {
  }
})

First question that will come to the mind of people if they were using SPEAK 1.1 is:

What about my components written in SPEAK 1.1?

I have already answered this question in a previous blog post but just to be sure we are on the same line.

Components written in SPEAK 1.1 should work in Speak 1.2 but may not work in the next SPEAK release.

We have provided you a bridge (a presenter) integrated by default in the SPEAK-TechnologyPreviewLayout to make your component in 1.1 working in a 1.2 environment.

Will it be a 100% backward compatiblity?

We can't answer that question as it is impossible for Sitecore to test all the components created in 1.1. All we can say is, Sitecore is aiming for 100%. So, if you have an error by switching to SPEAK 1.2, let us know by contacting the support.

What is a component in SPEAK 1.2?

In a Javascript point of view, a Component is simply a javascript object bound to a DOM element.

That's it!

What is new in SPEAK 1.2?

The syntax

Sitecore.component(["/path/to/deps"], {  
  name: "MyFirstComponent",
  initialize: function () {
    console.log(this.Text); //will ouput "Hello World"
  }
})

Support for Ms Typescript

Please note, the code below can be generated using ROCKS.

class MyFirstComponent {

  // #region Public Properties

  // This region was generated by a tool.
  // Changes to this region may cause incorrect behavior
  // and will be lost if the code is regenerated.
  public isEnabled: string;
  public IsVisible: boolean;
  public Size: string;
  public Text: string;
  public Tooltip: string;
  public Type: string;

  // #endregion

  initialized() {
  }

}

Sitecore.component(MyFirstComponent, "MyFirstComponent");

Component's Parameters directly set

In 1.2, the values set for the Parameters in ROCKS Design Layout are now automatically available in your component on the client side.

For example, I have a component called "MyFirstComponent". I add this component to a page and set a parameter "Text" to "Hello World".

The Text property of the component will be set to "Hello World".

Sitecore.component({  
  name: "MyFirstComponent",
  initialize: function () {
    console.log(this.Text); //will ouput "Hello World"
  }
})

The case (Pascal vs camelCase)

In SPEAK 1.2, all parameters of a Component use PascalCase.

NOTE: In order to keep backward compatiblity with pageCode 1.1, some tricks are done for the casing but please stick to the convention. A component parameter must be written in PascalCase.

Assigning a Parameter

In you pageCode, doing this:

this.MyFirstComponent.Text = "A new Value";  

will be the same as doing this:

this.MyFirstComponent.set("Text", "A new Value");  

So if you listen for a change like this:

this.MyFirstComponent.on("change:Text", callback);  

Both example above will trigger a change.

No more model and View

In SPEAK 1.1, the component was exposing a "Model" to the pageCode and all interaction was encapsulated in the "View". Based on the feedbacks we recieved, we have now gave up for that pattern and now just use a "Component".

NOTE: For SPEAK 1.1 users, it means you will need to merge the view and the model in one object.

A component with no Presenter and Javascript does nothing

If a component does not have any Presenter and any javascript file, the component won't have any behaviour.

It will just be exposed to your pageCode with the value of your parameters set.

By default we use a Presenter called "scKoPresenter". This will give you the ability to do data-binding using Knockout. Sitecore will use that presenter as much as possible for their own components. We encourage you to use it. You will even have nice C# helpers to setup your bindings inside your MVC view (without bothering what to put in your data-bind attribute).

Defining new Property Types

In SPEAK 1.2, you can now define complex parameters. As Sitecore is all about bindings and setting appropriate value in a component's parameter, we thought it was important to be able to create complex Parameter type.

Here is the syntax for a read only property type:

Sitecore.propertyType( {  
  name: "TypeFullname",
  get: function () {
    return this.component.FirstName + " " + this.component.LastName;
  }
} );

In order to use the that type, you need to express it in the attribute data-sc-properties='{ TypeFullName:FullName: "" }'

If your component has something like this in the data-sc-properties, the FullName property of your component will use the property type FullName.

myComponent.FirtName = "Marty";  
myComponent.LastName = "Mc Fly";  
console.log( myComponent.FullName ); //out put Marty Mc Fly  

You can off course create read/write. In addition to the get, you will need to define the set and isNew methods.

The isNew method is used to make those complex properties work with bindings. If the method returns true, it means that the value is new and the component will trigger a change event for that property ("change:PropertyName").

Here is the full syntax:

Sitecore.propertyType( {  
    name: "CustomType",
    get: function () {
        return this.value;
    },
    set: function ( newValue ) {
      this.value = newValue + " extend";
    },
    isNew: function ( newValue ) {
      return this.value !== newValue;
    }
} );

Convention for your Javascript File

By default, if you name your javascript code with the same name as your component followed by a ".js" extension.

SPEAK will use that file for your component automatically.

NOTE: A good practise is to gather all you code in the same folder.

Component can act as a container of other components

If you want to created a composite components, you can now do that by setting the HasNested property to true.

Basically, each component which will have the attribute data-sc-hasnested on their markup will act as a container.

Be careful, if you do this, the components exposed under them won't be exposed to the pageCode.

A Component must have a Presenter

So far, we did not talk about Presenter. A presenter is an object which act as a Facade for your pageCode. It "presents" the Component to the world.

If not defined, the Component uses the default presenter. This presenter does nothing, it just exposed your component to the PageCode that's it.

A presenter is shared by component and is used to contain framework specific logic. You would maybe end up using a BackbonePresenter, EmberPresenter,...

Sitecore is providing you 2 presenters.

  • The scKoPresenter:

    This is our default choice when building component. Basically, it gives you the ability to do bindings between your HTML and your component using Knockout.

  • The scSpeakPresenter

    This presenter is used to make your SPEAK 1.1 components working. I think this presenter prooves that you can really make any kind of components talking with each others.

I won't explain you how to create new Presenters as it would deserve its own blog post.

What did not change?

Bindings

Still the same syntax, still working the same way.

Events capabilities

You can still listen for changes on a component the same way as in 1.1.

The definition of a component

The overall idea of a Component remains unchanged. The idea is to create a Page based on components and link those togheter with Bindings and/or by writing some code in your pageCode.

If you want to know more about the definition of a component, I invite you to read my previous blog post: How Should I write a component?

Conclusion

As you can see, the major changes we did in SPEAK 1.2 was focused around components. The component is the most important building block in SPEAK and that's why we put a lot of effort to make them simpler and more powerful. By introducing the concept of a presenter, we have given the responsability of which framework to use to you (and not us).

If you are not opinonated about client-side framework, we have provided you the "knockout presenter" which will give you the opportunity to quickly create dynamic component using knockout without too much effort.

We hope you are as much exited by those changes as we are and if you have ideas on how to make the Component building block even better, just drop a comment or contact me on twitter @dervalp.

comments powered by Disqus