The model model is somewhat special in that it is used to generate all of the other models. Since changes to the model model could potentially break other models, we do not supply the specification for this model. We do explain in detail how to use the model model to create your own models to extend the capabilities of GenHelm.
Models vs. Dollar Functions
Before creating a model you should first decide whether your use case calls for a model or a dollar function. Generally speaking, dollar functions are used to generate small stand-alone components whereas models are used to create pages, classes or other large components. Another factor used to make this decision is the number of parameters required. Usually dollar functions work best when they only require a "handful" of parameters, say, fewer than 10.
Sometimes the best approach is to combine dollar functions with models. For example, since rendering responsive efficient images with srcset, styling, titles, etc. involves a lot of parameters, it would be unwieldy to do so using just a dollar function so we created an image model to gather all of these parameters in a structured way. Nevertheless, we also need a image dollar function to render the image making use of all of the information generated by the image model.
What Should Your Model Generate?
Any type of component that you create often is a candidate for a model. Models have three main goals:
- Reduce the time needed to build code that follows standard patterns.
- Help eliminate coding errors often introduced in hand-written components.
- Reduce the level of expertise needed to build certain classes of components.
Suppose your websites have a lot of pages that interact with Google Sheets or other Google Workspace documents. This might be a skill that only one or two people on your team has and because there are so many pages that require this sort of integration perhaps these team members are constantly falling behind on their work. One way to solve this problem would be to have these experts build a model that would allow other, less knowledgeable, team members to build these components without requiring a great deal of expertise. Essentially, your experts encapsulate their knowledge into a model so the model becomes a new "expert" that can be leveraged by anyone on your team.
Models are not that different from functions in that you pass in parameters and they return something. The parameters that get passed to the model are entered by a developer using the model's input form. The model uses this information to generate one or more components that are saved to the file system. One of the components that is generated automatically by the framework is the xml specification used to externalize the parameters entered by the developer. This allows the developer to come back at a later time and re-read the specification and make changes to the parameters to affect the features and options generated into the code.
Generally speaking, you should try to make the code generated by the models as simple as possible. Let's consider the Google Workspace example again. Suppose interfacing with Google Worksheets requires a lot of complex code. This would make it difficult to create a model since the model would need to generate all of this complex code. Furthermore, every time someone uses the model your system would take on more and more complex code, albeit generated. Just as with normal software development, the better approach is usually to create a class which handles much of the complexity generically. This way, most of the complexity is encapsulated in one class. In this case, the model can generate much simpler classes that extend the functionality of the base class.
Model Class Name
All models are implemented by a class named model_[model_name]. For example, the tags model class is model_tags.
Model Inheritance
All models inherit from a base class named spec so this is the default base class if you don't specify an alternate base class. All page-oriented models inherit from a base class named page_spec. It is also possible to extend other models. For example, here we see that the form and bootgrid models use the table model as their base class in order to take advantage of functionality that is common to these models:
spec
model_anchor
model_bootcar
model_php_class
model_form_handler
page_spec
model_tags
model_table
model_form
model_bootgrid
Model Form Names
The main form used by each model is named e_[model_name]. For example, the form used by the tags model is called e_tags.
Each model needs a minimum of two components. If you are creating a new model called widget, you need:
- A class named model_widget (created using the model model)
- A form named e_widget (created using the form model)
We also recommend creating a third component named widget which is created using the translation model. This will define the labels and field help for the model.
GenHelm supplies all of the model source code so a good way to learn about creating models is to look at the model classes and forms used by the supplied models.
Model Example
Follow this link to see step-by-step instructions describing how the faq model was created.
