7. Special functions
Last updated
Last updated
Let's continue our walkthrough of the functionalities with special functions. Now special functions refer to a range of different commands that you can use to perform all sorts of manipulations of the text, in order to optimize how it is portrayed. In this chapter we'll take a look at two clauses in particular that are greatly benefited by the inclusion of special functions.
The first clause that we’re going to be taking a look at is the services clause. As you can see here, the template author has indicated that we need to create a bulleted list of services, so that’s exactly what we’re going to do.
We’ll start by first closing the existing clause, since we ordered this currently open clause since we don’t really need it anymore and then create a new library clause. We don’t really have a suitable folder to place this in right now, so we’ll just create a new folder which we’ll call services. And then place that clause in the services folder and then we’ll also naturally create a file name along the likes of services. Content title and content body can of course be imported via the global panel.
We don’t really need to do anything to optimize the import here, so we can just click this import icon, close the global panel. Then the content title and the content body will be inserted.
Now Clause9 has chosen to transform this title services into the concept services, that’s a valid approach there. There are arguments to be made for that, however it’s not really necessary at this point in time, so you can just hard code that word services as is. Then the content body is of course fine like that, the only thing that we still need to do is to replace this placeholder with a datafield where users can fill out a list of different elements.
Of course, if you hear datafields and lists in the same sentence, then you should immediately be thinking of a list of texts datafield that users can fill in. For the name of this datafields you could go with quite a few different options, you could go with agreement, services for example. We recommend you to use services list and that’s because you will have a lot of different arguments to make for including datafields in the agreement concept. If we then create this datafield naturally we’re going to be creating a list of texts datafield and then we’ll click save and insert to actually create this clause.
When naming datafields you may run the risk to overload that concept with way too many datafields. So it’s best to keep this a little bit more concrete and to use this notation for the datafield in question.
Now as you can see here, we have in the interactive preview the option to fill out multiple different elements to this list. So the first element we’ll say is marketing, the second element for example will be sales, and the final element will be let’s say legal advice services that are offered by the consultant. If we now click apply to insert all of those elements into the actual document, then you can see here that clause base transforms this not into a bulleted list but simply in a list included in this one bullet. Of course, here we need to manipulate the text so that it is actually portrayed as a bulleted list.
Fortunately, we have a special function just for that, the approach to writing special functions always happens in three steps:
First of all you write the @ symbol.
Then you write the name of the special function (in our case that is bullets).
Then you surround the different parameters that it manipulates, (the different text bits that that are affected by the special function) with parentheses.
In our case we are simply including, and for this special function in particular, we are simply transforming this particular list into bullets. So that’s the only parameter, the only item that we really need to include here, in this in this special function. And if I now click save in library, you can see that the text is included in a bulleted list. I could even turn this into cumulative enumeration too, by writing dash and at the end of the special function, to showcase the word and in the second to last element of the list. I can do the same for or, and I can even try and do this for and or, if you would be so inclined. For now the bullets list will suffice.
So that’s one example of a list or of a special function that we can use to optimize the text, the second example that we’ll be taking a look at, is the fees clause. Where in particular we need to be able to flexibly play around with how this word hour is displayed, depending on whether or not one hour is filled out. In which case this word needs to be the word hour or multiple hours are chosen, in which case the word needs to be hours.
So we will again close the currently open clause, we will create a new library clause. We can add this clause to the services folder, if you prefer having a folder a separate folder called fees, you’re welcome to create that. Then we can of course name the file name fees and we can of course import the content directly from the global panel. Again nothing we really need to do to optimize the import here, so we just click this import icon, close the global panel and then the content title is as it should be and the content body is as it should be.
Now the real interesting stuff happens in paragraph two, so let’s quickly get paragraph one out of the way where we still need to create a datafield here. We have already looked at currency datafields in the past, naturally there is a sum of money that needs to be filled out here, so we’re going to be using a currency datafield again.
The name of the currency datafields again is more or less up to you, but we suggest that you continue this spirit of intertwining services and fees a little bit. And for example turning this into services monthly remuneration, so in other words the monthly remuneration for the services. You could alternatively also attach this datafield to the concept of consultant or the concept of fees that you could create on the spot here. Both of those approaches work as well, but for now let’s take this approach. Then of course we’ll turn this into a currency type datafield and if I now click save and insert, you can see here that we can fill out a number and a certain currency to create a sum of money.
But the really interesting bit is of course still this part of the second paragraph. First of all we need to create a datafield that allows us to fill out a number of hours that the consultant needs to perform per month. Let’s stick with the services concept for now, where we can then name the datafields. For example hours per month, so the hours per month invested in these services. That is naturally going to be a number type datafield, because we fill out a number of hours. Of course if we now click save in library and fill out a certain value here, let’s say that the consultant needs to perform 100 hours in a given month, then this makes a lot of sense, of course this part of the sentence.
But if we were to say for whatever reason that the consultant only performs one hour per month, then of course the word hours needs to be replaced with the word hour. Now you could transform this into a condition, but that you run the risk of making that a little bit clunky. So there is a special function that allows you to do this in a bit more of a succinct manner. The special function that we’re going to be using here is the one dash else function, in other words a special function that focuses on a certain value of a number datafield. Depending on that value of the number datafield it either provides a bit of text for, if one is the value, or if anything else is the value.
I think an example will showcase that in a little bit more of a better light, so we’ll start by writing the @ symbol, we’ll then use the name or write the name of the special function. Then in between parentheses we’re writing three elements this time:
The first element or the first parameter, is called the datafields that the special function hinges on in our case. That is the datafield we just created, services hours per month, so that’s the datafield that the special function will use to either show the second or the third parameter. Then of course we separate these parameters with commas.
Then the second parameter will be the text that needs to be displayed for the value one, that’s in our case of course our, we’re surrounding those with quotation marks because it should be indicated as being static text.
The third parameter again separated with commas, is the text value that needs to be portrayed if the number is anything other than one, in the else situation.
So as you can see here we’re essentially asking one else of the services hour per month, if the answer is one then we’re showing the word hour, if the answer is anything else then we show the word hours. And of course then we also get rid of the hard-coded word hours, since we won’t be needing that anymore. Then you can see here in the interactive preview this now says one hour, but if we were to change that to two hours then it says two hours.
These are just two examples of the special functions that you can use. Now, the Clause9 grammar sheet contains quite a few more special functions and also contains a link to the full list of special functions. This is a very expansive list, just know that you don’t need to know every single one of them, but that it is a useful resource for you to take a look at, whenever you’re confronted with a similar sort of small manipulation of the text that needs to occur in a useful manner. In order to optimize how the text is portrayed, the special functions list will therefore be a very valuable resource but not one that you need to of course know by heart.
⏭ Next on we will be exploring cross-references.
Do you want to learn more about this chapter? Check out our help page on special functions.
